@atlashub/smartstack-cli 3.30.0 → 3.32.0

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

@@ -151,6 +151,94 @@ public class {Name} : BaseEntity, IAuditableEntity
 }
 ```
 
+### Entity Pattern — Cross-Tenant (IOptionalTenantEntity)
+
+For entities that can be shared across tenants (e.g., Department, Currency). TenantId is nullable — null means shared, Guid means tenant-specific. The user decides the scope at creation time.
+
+```csharp
+public class {Name} : BaseEntity, IOptionalTenantEntity, IAuditableEntity
+{
+    // TenantId nullable — null = shared across all tenants
+    public Guid? TenantId { get; private set; }
+
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Business properties
+    public string Code { get; private set; } = string.Empty;
+    public string Name { get; private set; } = string.Empty;
+
+    private {Name}() { }
+
+    /// <param name="tenantId">null = shared (cross-tenant), Guid = tenant-specific</param>
+    public static {Name} Create(Guid? tenantId = null, string code, string name)
+    {
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+}
+```
+
+**EF Core global query filter (already in SmartStack.app CoreDbContext):**
+```csharp
+builder.HasQueryFilter(e => !ShouldFilterByTenant || e.TenantId == null || e.TenantId == CurrentTenantId);
+```
+This automatically includes shared (null) + current tenant data in all queries.
+
+**Service pattern for optional tenant:**
+```csharp
+// No guard clause — tenantId is nullable
+var tenantId = _currentTenant.TenantId; // null = creating shared data
+var entity = Department.Create(tenantId, dto.Code, dto.Name);
+```
+
+### Entity Pattern — Scoped (IScopedTenantEntity)
+
+For entities with explicit visibility control via EntityScope enum (Tenant, Shared, Platform).
+
+```csharp
+public class {Name} : BaseEntity, IScopedTenantEntity, IAuditableEntity
+{
+    public Guid? TenantId { get; private set; }
+    public EntityScope Scope { get; private set; }
+
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    private {Name}() { }
+
+    public static {Name} Create(Guid? tenantId = null, EntityScope scope = EntityScope.Tenant)
+    {
+        if (scope == EntityScope.Tenant && tenantId == null)
+            throw new ArgumentException("TenantId is required when scope is Tenant");
+
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Scope = scope,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+}
+```
+
+### MCP tenantMode Parameter
+
+When calling `scaffold_extension`, use the `tenantMode` parameter:
+- `strict` (default) — ITenantEntity, Guid TenantId (required)
+- `optional` — IOptionalTenantEntity, Guid? TenantId (cross-tenant)
+- `scoped` — IScopedTenantEntity, Guid? TenantId + EntityScope
+- `none` — No tenant interface (platform-level entities)
+
+The old `isSystemEntity: true` still works and maps to `tenantMode: 'none'`.
+
 ---
 
 ## EF Configuration Pattern
@@ -599,6 +687,130 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
 | `GetAllAsync()` without search param | ALL GetAll endpoints MUST support `?search=` for EntityLookup |
 | FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |
+| `PagedResult<T>` / `PaginatedResultDto<T>` | FORBIDDEN — use `PaginatedResult<T>` only |
+
+---
+
+## PaginatedResult Pattern
+
+> **Canonical type for ALL paginated responses.** One name, one contract, everywhere.
+
+### Definition (Backend — `SmartStack.Application.Common.Models`)
+
+```csharp
+namespace SmartStack.Application.Common.Models;
+
+public record PaginatedResult<T>(
+    List<T> Items,
+    int TotalCount,
+    int Page,
+    int PageSize)
+{
+    public int TotalPages => PageSize > 0
+        ? (int)Math.Ceiling((double)TotalCount / PageSize) : 0;
+    public bool HasPreviousPage => Page > 1;
+    public bool HasNextPage => Page < TotalPages;
+
+    public static PaginatedResult<T> Empty(int page = 1, int pageSize = 20)
+        => new([], 0, page, pageSize);
+}
+```
+
+### Extension Method
+
+```csharp
+namespace SmartStack.Application.Common.Extensions;
+
+public static class QueryableExtensions
+{
+    public const int MaxPageSize = 100;
+
+    public static async Task<PaginatedResult<T>> ToPaginatedResultAsync<T>(
+        this IQueryable<T> query,
+        int page = 1,
+        int pageSize = 20,
+        CancellationToken ct = default)
+    {
+        page = Math.Max(1, page);
+        pageSize = Math.Clamp(pageSize, 1, MaxPageSize);
+
+        var totalCount = await query.CountAsync(ct);
+        var items = await query
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync(ct);
+
+        return new PaginatedResult<T>(items, totalCount, page, pageSize);
+    }
+}
+```
+
+### Usage in Service (with search + extension method)
+
+```csharp
+public async Task<PaginatedResult<{Name}ResponseDto>> GetAllAsync(
+    string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
+{
+    var tenantId = _currentTenant.TenantId
+        ?? throw new TenantContextRequiredException();
+
+    var query = _db.{Name}s
+        .Where(x => x.TenantId == tenantId)
+        .AsNoTracking();
+
+    if (!string.IsNullOrWhiteSpace(search))
+        query = query.Where(x => x.Name.Contains(search) || x.Code.Contains(search));
+
+    return await query
+        .OrderBy(x => x.Name)
+        .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
+        .ToPaginatedResultAsync(page, pageSize, ct);
+}
+```
+
+### Frontend Types (`@/types/pagination.ts`)
+
+```typescript
+export interface PaginatedResult<T> {
+  items: T[];
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasPreviousPage: boolean;
+  hasNextPage: boolean;
+}
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  sortBy?: string;
+  sortDirection?: 'asc' | 'desc';
+}
+```
+
+### FORBIDDEN Type Names
+
+| Forbidden | Canonical Replacement |
+|-----------|----------------------|
+| `PagedResult<T>` | `PaginatedResult<T>` |
+| `PaginatedResultDto<T>` | `PaginatedResult<T>` |
+| `PaginatedResponse<T>` | `PaginatedResult<T>` |
+| `PageResultDto<T>` | `PaginatedResult<T>` |
+| `PaginatedRequest` | `PaginationParams` |
+| `QueryParameters` | `PaginationParams` |
+| `currentPage` (property) | `page` |
+| `HasPrevious` (property) | `HasPreviousPage` |
+| `HasNext` (property) | `HasNextPage` |
+
+### Rules
+
+- **Max pageSize = 100** — enforced via `Math.Clamp(pageSize, 1, 100)` or extension method
+- **Default page = 1, pageSize = 20** — all GetAll endpoints
+- **Search param mandatory** — enables `EntityLookup` on frontend
+- **POST-CHECK 16** blocks `List<T>` returns on GetAll
+- **POST-CHECK 31** blocks non-canonical pagination type names
 
 ---
 
@@ -701,16 +913,28 @@ public class MyEntity : BaseEntity, ITenantEntity, IAuditableEntity
 **INCORRECT — Race condition:**
 ```csharp
 // WRONG: Two concurrent requests get the same count
-var count = await _db.MyEntities.Where(x => x.TenantId == _currentUser.TenantId).CountAsync(ct);
-return $"ENT{(count + 1):D4}";
+var count = await _db.MyEntities.Where(x => x.TenantId == tenantId).CountAsync(ct);
+return $"emp-{(count + 1):D5}";
 ```
 
-**CORRECT — Use `GenerateNextCodeAsync()` (atomic):**
+**CORRECT — Use `ICodeGenerator<T>.NextCodeAsync()` (atomic with retry):**
 ```csharp
-var code = await GenerateNextCodeAsync("MyEntity", _currentUser.TenantId, ct);
+private readonly ICodeGenerator<MyEntity> _codeGenerator;
+
+// In CreateAsync:
+var code = await _codeGenerator.NextCodeAsync(ct);
+var entity = MyEntity.Create(tenantId, code, dto.Name, createdBy: null);
 ```
 
-**Why it's wrong:** `Count() + 1` causes **race conditions** — concurrent requests generate duplicate codes.
+**Why it's wrong:** `Count() + 1` causes **race conditions** — concurrent requests generate duplicate codes. `ICodeGenerator<T>` uses `OrderByDescending` on existing codes + retry on unique constraint violation for safe concurrency.
+
+**Key rules when using auto-generated codes:**
+- **REMOVE** `Code` from `CreateDto` (auto-generated, not user-provided)
+- **KEEP** `Code` in `ResponseDto` (returned to frontend)
+- Register `ICodeGenerator<T>` in DI with `CodePatternConfig`
+- Code regex in validators: `^[a-z0-9_-]+$` (supports hyphens)
+
+**Full reference:** See `references/code-generation.md` for strategies (sequential, timestamp, yearly, UUID), volume-to-digits calculation, and complete implementation patterns.
 
 ---
 

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

@@ -223,6 +223,7 @@ 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';
 
 // API hook (generated by scaffold_api_client)
 import { useEntityList } from '@/hooks/useEntity';
@@ -284,17 +285,20 @@ export function EntityListPage() {
   // 6. CONTENT — create button navigates to /create route
   return (
     <div className="space-y-6">
-      {/* Header */}
+      {/* 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>
-        <button
-          onClick={() => navigate('create')}
-          className="px-4 py-2 bg-[var(--color-accent-500)] text-white rounded"
-        >
-          {t('{module}:actions.create', 'Create')}
-        </button>
+        <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: SmartTable with row click → detail, edit action → /:id/edit */}
@@ -953,13 +957,20 @@ public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
 ### Rules
 
 - **NEVER** render a `Guid` FK field as `<input type="text">` — always use `EntityLookup`
+- **NEVER** render a `Guid` FK field as `<select>` — even with API-loaded `<option>` elements, `<select>` is NOT acceptable
 - **NEVER** ask the user to manually type or paste a GUID/ID
-- **ALWAYS** provide a search-based selection for FK fields
+- **ALWAYS** provide a search-based selection via `<EntityLookup />` for FK fields
 - **ALWAYS** show the entity's display name (Name, FullName, Code+Name) not the GUID
 - **ALWAYS** include `mapOption` to define how the related entity is displayed
 - **ALWAYS** load the selected entity's display name on mount (for edit forms)
 - **ALWAYS** 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
+
 **FORBIDDEN:**
 ```tsx
 // WRONG: Plain text input for FK field
@@ -970,6 +981,17 @@ public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
   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 Department...</option>
+  {departments.map((dept) => (
+    <option key={dept.id} value={dept.id}>{dept.name}</option>
+  ))}
+</select>
+
 // WRONG: Raw GUID displayed to user
 <span>{entity.departmentId}</span>
 
@@ -979,6 +1001,18 @@ public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
 </select>
 ```
 
+**CORRECT — ONLY this pattern:**
+```tsx
+<EntityLookup
+  apiEndpoint="/api/business/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
+/>
+```
+
 ### I18n Keys for EntityLookup
 
 Add these keys to the module's translation files:
@@ -996,16 +1030,83 @@ Add these keys to the module's translation files:
 
 ---
 
-## 7. Checklist for /apex Frontend Execution
+## 7. Documentation Panel Integration (DocToggleButton)
+
+> **EVERY list/detail page MUST include a `DocToggleButton` in its header.**
+> This button opens the right-side documentation panel showing the module's user documentation.
+
+### Component Import
+
+```tsx
+import { DocToggleButton } from '@/components/docs/DocToggleButton';
+```
+
+### Placement — Always in the page header actions area (top right)
+
+```tsx
+{/* 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="...">
+      {t('{module}:actions.create', 'Create')}
+    </button>
+  </div>
+</div>
+```
+
+### How it Works
+
+1. `DocToggleButton` uses `useDocPanel()` context (provided by the Layout)
+2. On click → opens the `DocPanel` on the right side of the screen
+3. The panel loads the module's documentation via iframe (`?embedded=true`)
+4. Route → doc mapping is in `DocPanelContext.tsx` — maps current pathname to doc URL
+5. Panel is resizable (20-60% width), size persists in localStorage
+
+### Documentation Generation
+
+After frontend pages are created, invoke the `/documentation` skill to generate:
+
+| File | Content |
+|------|---------|
+| `src/pages/docs/business/{app}/{module}/doc-data.ts` | Data-driven documentation (~50-80 lines) |
+| `src/pages/docs/business/{app}/{module}/index.tsx` | Page wrapper (~10 lines) using `DocRenderer` |
+| `src/i18n/locales/fr/docs-{app}-{module}.json` | French doc translations (source language) |
+
+The `DocRenderer` shared component renders all 8 documentation sections (overview, use cases, benefits, features, steps, FAQ, business rules, permissions, API endpoints) from the `doc-data.ts` file.
+
+### Custom Doc URL (optional)
+
+If the automatic route mapping doesn't work for your module, pass a custom URL:
+
+```tsx
+<DocToggleButton customDocUrl="/docs/business/human-resources/employees" />
+```
+
+### Rules
+
+- **EVERY** list page MUST include `DocToggleButton` in its header actions
+- **EVERY** detail page MUST include `DocToggleButton` in its header actions
+- Create/Edit form pages do NOT need DocToggleButton (users don't read docs while filling forms)
+- DocToggleButton is imported from `@/components/docs/DocToggleButton` (shared component)
+- The Layout already provides `DocPanelProvider` — no additional wrapping needed
+- Documentation content is generated by the `/documentation` skill AFTER frontend pages exist
+
+---
+
+## 7b. Checklist for /apex Frontend Execution
 
 Before marking frontend tasks as complete, verify:
 
 - [ ] All page imports use `React.lazy()` with named export wrapping
 - [ ] `<Suspense fallback={<PageLoader />}>` wraps all lazy components in routes
-- [ ] Translation files exist for **all 4 languages** (fr, en, it, de)
+- [ ] Translation files exist for **all 4 languages** (fr, en, it, de) in `src/i18n/locales/`
 - [ ] All `t()` calls include namespace prefix AND fallback value
 - [ ] No hardcoded strings in JSX — all text goes through `t()`
-- [ ] CSS uses variables only — no hardcoded Tailwind colors
+- [ ] CSS uses variables only — no hardcoded Tailwind colors (BLOCKING POST-CHECK 13)
 - [ ] Pages follow loading → error → content pattern
 - [ ] Pages use `src/pages/{Context}/{App}/{Module}/` hierarchy
 - [ ] API calls use generated hooks or `apiClient` (never raw axios)
@@ -1019,6 +1120,262 @@ Before marking frontend tasks as complete, verify:
 - [ ] No `<Modal>`, `<Dialog>`, `<Drawer>` imports in form-related pages
 - [ ] Form pages include back button with `navigate(-1)`
 - [ ] Form pages are covered by frontend tests (see section 8)
+- [ ] **`DocToggleButton` present in header of every list/detail page (see section 7)**
+- [ ] **`/documentation` skill invoked to generate module doc-data.ts**
+
+---
+
+## 7c. Cross-Tenant Entity UI Patterns
+
+> **For optional and scoped tenant entities, the frontend MUST provide UI controls to set the scope/visibility.**
+
+### Scope Types
+
+| Type | Behavior | Use case |
+|------|----------|----------|
+| **Optional** | Entity can be tenant-specific OR shared (binary choice) | Data that can belong to one org or all orgs |
+| **Scoped** | Entity has explicit scope enum: Tenant / Shared / Platform | Data with multiple visibility levels |
+
+### Scope Selector in Create Forms (Optional Entities)
+
+For `optional` tenant entities, add a toggle in the create form allowing the user to decide:
+
+```tsx
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export function EntityCreatePage() {
+  const { t } = useTranslation(['{module}']);
+  const [formData, setFormData] = useState({
+    name: '',
+    isShared: false,  // User decision: tenant-specific (false) or shared (true)
+  });
+
+  const handleScopeChange = (value: string) => {
+    setFormData({ ...formData, isShared: value === 'shared' });
+  };
+
+  return (
+    <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>
+          ),
+        },
+      ]} />
+    </div>
+  );
+}
+```
+
+### Scope Selector in Create Forms (Scoped Entities)
+
+For `scoped` entities with explicit enum values (Tenant, Shared, Platform), use a dropdown with all scope options:
+
+```tsx
+export function EntityCreatePage() {
+  const { t } = useTranslation(['{module}']);
+  const [formData, setFormData] = useState({
+    name: '',
+    scope: 'Tenant',  // Enum: 'Tenant' | 'Shared' | 'Platform'
+  });
+
+  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'),
+      },
+    ]} />
+  );
+}
+```
+
+### Scope Indicator in List Views
+
+Display a visual indicator/badge on each row showing the entity scope:
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+// ScopeBadge component for reuse
+interface ScopeBadgeProps {
+  tenantId?: string | null;      // For optional entities: null = shared, value = tenant-specific
+  scope?: string;                 // For scoped entities: 'Tenant' | 'Shared' | 'Platform'
+}
+
+export function ScopeBadge({ tenantId, scope }: ScopeBadgeProps) {
+  const { t } = useTranslation(['common']);
+
+  // Optional entity scope
+  if (tenantId !== undefined) {
+    const isTenant = Boolean(tenantId);
+    return (
+      <span
+        className={`px-2 py-1 rounded-full text-xs font-semibold ${
+          isTenant
+            ? 'bg-[var(--bg-accent-light)] text-[var(--color-accent-600)]'
+            : 'bg-[var(--bg-secondary)] text-[var(--text-secondary)]'
+        }`}
+      >
+        {isTenant
+          ? t('common:scope.tenant', 'Tenant')
+          : t('common:scope.shared', 'Shared')}
+      </span>
+    );
+  }
+
+  // Scoped entity scope
+  if (scope) {
+    const scopeStyles: Record<string, { bg: string; text: string }> = {
+      Tenant: {
+        bg: 'bg-[var(--bg-accent-light)]',
+        text: 'text-[var(--color-accent-600)]',
+      },
+      Shared: {
+        bg: 'bg-[var(--bg-secondary)]',
+        text: 'text-[var(--text-secondary)]',
+      },
+      Platform: {
+        bg: 'bg-[var(--bg-warning-light)]',
+        text: 'text-[var(--color-warning-600)]',
+      },
+    };
+
+    const style = scopeStyles[scope] || scopeStyles.Tenant;
+    const scopeLabel = {
+      Tenant: t('common:scope.tenant', 'Organization'),
+      Shared: t('common:scope.shared', 'Shared'),
+      Platform: t('common:scope.platform', 'Platform'),
+    }[scope] || scope;
+
+    return (
+      <span className={`px-2 py-1 rounded-full text-xs font-semibold ${style.bg} ${style.text}`}>
+        {scopeLabel}
+      </span>
+    );
+  }
+
+  return null;
+}
+```
+
+### Using ScopeBadge in SmartTable Columns
+
+```tsx
+// In the list page, add a scope column
+const columns = [
+  { key: 'name', label: t('{module}:columns.name', 'Name') },
+  { key: 'code', label: t('{module}:columns.code', 'Code') },
+  {
+    key: 'scope',
+    label: t('common:scope', 'Scope'),
+    render: (row) => (
+      // For optional entities: show based on tenantId
+      <ScopeBadge tenantId={row.tenantId} />
+      // OR for scoped entities: show based on scope field
+      // <ScopeBadge scope={row.scope} />
+    ),
+  },
+  { key: 'actions', label: t('{module}:columns.actions', 'Actions') },
+];
+
+return (
+  <SmartTable
+    columns={columns}
+    data={data}
+    loading={loading}
+    onRowClick={(row) => navigate(`${row.id}`)}
+  />
+);
+```
+
+### I18n Keys for Scope UI
+
+Add these keys to `src/i18n/locales/*/common.json`:
+
+```json
+{
+  "scope": "Scope",
+  "scope.tenant": "My Organization",
+  "scope.tenant.hint": "This data will only be visible to your organization",
+  "scope.shared": "Shared (All Organizations)",
+  "scope.shared.hint": "This data will be accessible to all organizations",
+  "scope.platform": "Platform (Admin Only)",
+  "scope.help": "Select the visibility level for this data"
+}
+```
+
+And in the module-specific translation files (e.g., `employees.json`):
+
+```json
+{
+  "form": {
+    "scope": "Scope",
+    "scopeHint": "Choose who can see this data"
+  }
+}
+```
+
+### Rules
+
+- **ALWAYS** provide scope controls in create forms for optional/scoped entities
+- **ALWAYS** show scope indicator badges in list views
+- **ALWAYS** use `ScopeBadge` component for consistency across modules
+- **NEVER** let users create shared entities without explicit choice
+- **NEVER** hide scope controls — scope is a business-critical property
+- **ALWAYS** include scope-related translation keys in i18n files (all 4 languages)
+- **FORBIDDEN:** Form field for scope labeled ambiguously (e.g., "Public/Private" without context)
+- **FORBIDDEN:** Scope badges with hardcoded colors — always use CSS variables
 
 ---