@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/backend/core-seed/cli/scaffold-core-seed/index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-core-seed
+ *
+ * Generates 5 Core Foundation Seed providers per application (under
+ * Persistence/Seeding/Applications/{AppPascal}/Core/) + patches
+ * DependencyInjection.cs once per application from a multi-app
+ * CoreSeedSpec JSON.
+ *
+ * Usage:
+ *   npx tsx skills/development/backend/core-seed/cli/scaffold-core-seed/index.ts \
+ *     --spec-file /path/to/core-seed-spec.json [--outdir /path/to/target-app] [--dry-run]
+ *
+ * Or with inline spec (small specs only — JSON gets quoted on the shell):
+ *   npx tsx ... --spec '{"appCode":"TestV2","applications":[...],...}'
+ *
+ * Called by Phase 0 of /ba-develop (skill backend-core-seed).
+ * The spec is built by the Studio backend (prepareCoreSeedContext) from the
+ * BA tables and dropped to a temp file before the agent invokes this CLI.
+ */
+import { parseArgs } from 'node:util';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+import { validate } from './validate.js';
+import { generate, patchDependencyInjection } from './generate.js';
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js';
+import type { CoreSeedSpec } from './types.js';
+
+const COMMAND = 'scaffold-core-seed';
+
+function main(): void {
+  const { values } = parseArgs({
+    options: {
+      spec: { type: 'string' },
+      'spec-file': { type: 'string' },
+      outdir: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    strict: true,
+  });
+
+  const rawJson = loadSpecJson(values);
+  if (rawJson === null) {
+    printEnvelope(failGenerate(COMMAND, ['Either --spec or --spec-file is required']));
+    process.exit(1);
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(rawJson);
+  } catch {
+    printEnvelope(failGenerate(COMMAND, ['Invalid JSON in spec']));
+    process.exit(1);
+  }
+
+  const validation = validate(raw);
+  if (!validation.valid) {
+    printEnvelope(failGenerate(COMMAND, validation.errors));
+    process.exit(1);
+  }
+
+  const spec = raw as CoreSeedSpec;
+  const result = generate(spec);
+
+  if (values['dry-run']) {
+    printEnvelope(
+      generateEnvelope(COMMAND, {
+        data: {
+          dryRun: true,
+          files: result.files.map((f) => f.path),
+          diBlocks: result.diRegistration.perApp.map((p) => ({
+            appCode: p.appCode,
+            appPascal: p.appPascal,
+            block: p.markerBlock,
+          })),
+          diCandidates: result.diRegistration.candidatePaths,
+          testUsersManifest: result.testUsersManifest?.path ?? null,
+        },
+        warnings: validation.warnings,
+      }),
+    );
+    process.exit(0);
+  }
+
+  const outdir = values.outdir ?? spec.projectPath;
+  const filesCreated: string[] = [];
+  const filesModified: string[] = [];
+  const warnings: string[] = [...validation.warnings];
+
+  // 1. Write the per-application Core providers + optional shared test users manifest.
+  for (const file of result.files) {
+    const fullPath = resolve(join(outdir, file.path));
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, file.content, 'utf-8');
+    filesCreated.push(fullPath);
+  }
+  if (result.testUsersManifest) {
+    const fullPath = resolve(join(outdir, result.testUsersManifest.path));
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, result.testUsersManifest.content, 'utf-8');
+    filesCreated.push(fullPath);
+  }
+
+  // 2. Patch DependencyInjection.cs (or sibling) once per application. Walk
+  // candidates in priority order, patch the FIRST file that exists. Each
+  // application's block has its own `<<< CORE-SEED-DI-{AppPascal} BEGIN/END >>>`
+  // marker pair, so re-runs replace blocks idempotently per app.
+  let diHostPath: string | null = null;
+  for (const candidate of result.diRegistration.candidatePaths) {
+    const fullPath = resolve(join(outdir, candidate));
+    if (existsSync(fullPath)) {
+      diHostPath = fullPath;
+      break;
+    }
+  }
+
+  const appsPatched: string[] = [];
+  if (diHostPath !== null) {
+    let source = readFileSync(diHostPath, 'utf-8');
+    let dirty = false;
+    for (const reg of result.diRegistration.perApp) {
+      const next = patchDependencyInjection(source, reg);
+      if (next !== null) {
+        source = next;
+        dirty = true;
+      }
+      appsPatched.push(reg.appCode);
+    }
+    if (dirty) {
+      writeFileSync(diHostPath, source, 'utf-8');
+      filesModified.push(diHostPath);
+    }
+  } else {
+    const allBlocks = result.diRegistration.perApp.map((p) => p.markerBlock).join('\n\n');
+    warnings.push(
+      `No DependencyInjection.cs / ServiceCollectionExtensions.cs / *Module.cs found under src/${spec.appCode}.Infrastructure/. The Core providers will not be resolved at startup until they are registered. Register manually:\n${allBlocks}`,
+    );
+  }
+
+  printEnvelope(
+    generateEnvelope(COMMAND, {
+      data: {
+        appCode: spec.appCode,
+        applications: spec.applications.map((a) => ({
+          code: a.code,
+          modules: a.modules,
+          navCount: a.navigation.length,
+          roleCount: a.roles.length,
+          permissionCount: a.permissions.length,
+          rolePermissionCount: a.rolePermissions.length,
+          testUserCount: a.testUsers.length,
+        })),
+        applicationCount: spec.applications.length,
+        diPatched: diHostPath !== null,
+        diHostPath,
+        appsPatched,
+      },
+      filesCreated,
+      filesModified,
+      warnings,
+      nextSteps: [
+        'Run `dotnet build` to verify the per-app Core providers compile.',
+        'Run the Core Foundation Seed gate (verifyCoreFoundationSeed in ba-prd-develop-gates.ts) to confirm every PRD module has nav + roles + permissions.',
+        diHostPath !== null
+          ? 'DI registration is in place — the providers will be resolved at startup.'
+          : 'DI registration MISSING — register the Core providers in DependencyInjection.cs (or equivalent). See the warning above.',
+      ],
+    }),
+  );
+}
+
+function loadSpecJson(values: { spec?: string; 'spec-file'?: string }): string | null {
+  if (values['spec-file']) {
+    try {
+      return readFileSync(values['spec-file'], 'utf-8');
+    } catch (err) {
+      printEnvelope(
+        failGenerate(COMMAND, [
+          `Failed to read --spec-file ${values['spec-file']}: ${err instanceof Error ? err.message : String(err)}`,
+        ]),
+      );
+      process.exit(1);
+    }
+  }
+  return values.spec ?? null;
+}
+
+main();

package/templates/skills/development/backend/core-seed/cli/scaffold-core-seed/types.ts

@@ -0,0 +1,163 @@
+/**
+ * cli:scaffold-core-seed — types.ts
+ *
+ * Source-of-truth schemas for the multi-application Core Foundation Seed spec
+ * — one bundle of navigation + roles + permissions + role-permission mappings
+ * + dev test users PER application declared in the project. Generates the 5
+ * `{AppPascal}Core*SeedDataProvider.cs` files under
+ * `Persistence/Seeding/Applications/{AppPascal}/Core/`.
+ *
+ * Contrast with scaffold-seed (`development/backend/seed-data/`) which generates
+ * per-module reference-data providers ONLY (lookup tables, enum codes), now
+ * placed under `Persistence/Seeding/Applications/{AppPascal}/Modules/{ModuleCode}/`.
+ *
+ * NavigationEntry / RoleEntry / PermissionEntry / RolePermission /
+ * TestUserEntry schemas are re-exported from scaffold-seed/types.ts so the
+ * shapes stay in lockstep — only the *bundling* differs (per-module vs
+ * per-application vs per-project).
+ */
+import { z } from 'zod';
+import {
+  NavigationEntrySchema,
+  RoleEntrySchema,
+  PermissionEntrySchema,
+  RolePermissionSchema,
+  TestUserEntrySchema,
+} from '../../../seed-data/cli/scaffold-seed/types.js';
+
+export {
+  NavigationEntrySchema,
+  RoleEntrySchema,
+  PermissionEntrySchema,
+  RolePermissionSchema,
+  TestUserEntrySchema,
+} from '../../../seed-data/cli/scaffold-seed/types.js';
+export type {
+  NavigationEntry,
+  NavigationLevel,
+  RoleEntry,
+  PermissionEntry,
+  RolePermission,
+  TestUserEntry,
+} from '../../../seed-data/cli/scaffold-seed/types.js';
+
+/**
+ * Per-application Core Foundation Seed slice.
+ *
+ * `modules[]` is REQUIRED and load-bearing: the gate verifies that every
+ * code listed here has at least one matching `level: 'module'` entry in
+ * `navigation[]`, ≥ 1 role with that `code`, and ≥ 2 permissions
+ * referencing one of its sections. This is the structural fix that makes
+ * "module declared but seed empty" (the Budget regression in TestV2/ba-002)
+ * impossible by construction.
+ */
+export const ApplicationSpecSchema = z.object({
+  /**
+   * Navigation application code (lowercase, kebab-case). Used in
+   * `Role.applicationCode` to scope roles per app, and as the path segment
+   * for `Persistence/Seeding/Applications/{Pascal(code)}/...`.
+   */
+  code: z.string().min(1).regex(
+    /^[a-z][a-z0-9-]*$/,
+    'application code must be kebab-case (lowercase) and start with a letter',
+  ),
+  /**
+   * Module codes whose nav/permissions/roles MUST be present in this app's
+   * slice. The validator and the runtime gate use this list to fail fast
+   * when a module declared in the PRD has no seeded artefacts.
+   */
+  modules: z.array(z.string().min(1)).min(1, 'At least one module code is required per application'),
+  navigation: z.array(NavigationEntrySchema).min(1, 'At least one navigation entry required per application'),
+  roles: z.array(RoleEntrySchema).default([]),
+  permissions: z.array(PermissionEntrySchema).default([]),
+  rolePermissions: z.array(RolePermissionSchema).default([]),
+  testUsers: z.array(TestUserEntrySchema).default([]),
+});
+
+export type ApplicationSpec = z.infer<typeof ApplicationSpecSchema>;
+
+/**
+ * Project-level Core Foundation Seed spec — one or more applications, each
+ * producing 5 `{AppPascal}Core*SeedDataProvider.cs` files under their own
+ * `Seeding/Applications/{AppPascal}/Core/` folder. DI is patched once with
+ * one block per application between `<<< CORE-SEED-DI-{AppPascal} BEGIN/END >>>`
+ * markers.
+ */
+export const CoreSeedSpecSchema = z.object({
+  /**
+   * .NET project namespace prefix (PascalCase, e.g. `TestV2`). Drives the
+   * `src/{AppCode}.Infrastructure/...` paths and the C# namespaces. Distinct
+   * from `applications[].code` which is the per-app navigation code.
+   */
+  appCode: z.string().min(1).regex(
+    /^[A-Za-z][A-Za-z0-9-]*$/,
+    'appCode must start with a letter and contain only letters, digits and hyphens (PascalCase like "TestV2" or kebab like "test-v2")',
+  ),
+  namespace: z.string().optional(),
+  applications: z.array(ApplicationSpecSchema).min(1, 'At least one application is required'),
+  testUserPassword: z.string().min(8).default('DevTest!2026Secure'),
+  testUserEmailDomain: z.string().default('smartstack.local'),
+  emitDevCredentialsManifest: z.boolean().default(true),
+  projectPath: z.string().min(1),
+});
+
+export type CoreSeedSpec = z.infer<typeof CoreSeedSpecSchema>;
+
+export interface GeneratedFile {
+  path: string;
+  content: string;
+}
+
+export interface ModifiedFile {
+  path: string;
+  content: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Build the BEGIN marker comment for a given application's DI registration
+ * block. Each application gets its own marker pair so multi-app projects
+ * patch independently and re-runs are idempotent per app.
+ */
+export function diBeginMarker(appPascal: string): string {
+  return `// <<< CORE-SEED-DI-${appPascal} BEGIN >>>`;
+}
+
+export function diEndMarker(appPascal: string): string {
+  return `// <<< CORE-SEED-DI-${appPascal} END >>>`;
+}
+
+/**
+ * Suffixes of the 5 Core providers, in DI registration + execution order.
+ * Multi-app class names are formed as `{AppPascal}{Suffix}` (e.g.
+ * `CrmCoreNavigationSeedDataProvider`). The gate iterates per-app and
+ * verifies all 5 prefixed files exist under the per-app Core folder.
+ */
+export const CORE_PROVIDER_SUFFIXES = [
+  'CoreNavigationSeedDataProvider',
+  'CoreRolesSeedDataProvider',
+  'CorePermissionsSeedDataProvider',
+  'CoreRolePermissionsSeedDataProvider',
+  'CoreTestUsersSeedDataProvider',
+] as const;
+
+export type CoreProviderSuffix = (typeof CORE_PROVIDER_SUFFIXES)[number];
+
+/** Convert a kebab-case code (e.g. "crm", "test-app") to PascalCase ("Crm", "TestApp"). */
+export function pascalCase(code: string): string {
+  return code
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}
+
+/** Full class name for a Core provider in a given application. */
+export function coreProviderClassName(appPascal: string, suffix: CoreProviderSuffix): string {
+  return `${appPascal}${suffix}`;
+}

package/templates/skills/development/backend/core-seed/cli/scaffold-core-seed/validate.ts

@@ -0,0 +1,129 @@
+/**
+ * cli:scaffold-core-seed — validate.ts
+ *
+ * Two-stage validation:
+ *  1. Structural (Zod) — schema parse, regex on codes/paths
+ *  2. Business — per-application, every module in `modules[]` MUST have
+ *     nav + ≥ 1 role + ≥ 2 permissions. Application codes are unique
+ *     across the project. This is the gate the previous per-module
+ *     pipeline lacked (Budget had 9 entities + 2 controllers but empty
+ *     SeedNavigationAsync).
+ */
+import {
+  CoreSeedSpecSchema,
+  type ApplicationSpec,
+  type CoreSeedSpec,
+  type ValidationResult,
+} from './types.js';
+
+export function validateStructure(raw: unknown): ValidationResult {
+  const result = CoreSeedSpecSchema.safeParse(raw);
+  if (result.success) return { valid: true, errors: [], warnings: [] };
+  const errors = result.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`);
+  return { valid: false, errors, warnings: [] };
+}
+
+export function validateBusinessRules(spec: CoreSeedSpec): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Project-level: application codes are unique.
+  const seen = new Set<string>();
+  for (const app of spec.applications) {
+    if (seen.has(app.code)) {
+      errors.push(`Duplicate application code "${app.code}" in spec.applications[]`);
+    }
+    seen.add(app.code);
+  }
+
+  for (const app of spec.applications) {
+    validateApplication(app, errors, warnings);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateApplication(app: ApplicationSpec, errors: string[], warnings: string[]): void {
+  const ctx = `applications[${app.code}]`;
+
+  // 1. Exactly one application-level entry, matching `app.code`.
+  const apps = app.navigation.filter((n) => n.level === 'application');
+  if (apps.length === 0) {
+    errors.push(`${ctx}: navigation must include exactly one application-level entry`);
+  } else if (apps.length > 1) {
+    errors.push(`${ctx}: navigation contains ${apps.length} application-level entries — only one is allowed per application slice`);
+  } else if (apps[0].code !== app.code) {
+    errors.push(`${ctx}: application-level navigation code "${apps[0].code}" must equal application.code "${app.code}"`);
+  }
+
+  // 2. Every declared module has a matching nav entry.
+  const moduleNavCodes = new Set(app.navigation.filter((n) => n.level === 'module').map((n) => n.code));
+  const missingModuleNav = app.modules.filter((m) => !moduleNavCodes.has(m));
+  if (missingModuleNav.length > 0) {
+    errors.push(
+      `${ctx}: modules declared but missing from navigation: ${missingModuleNav.join(', ')}. Each module in modules[] must have a level: 'module' navigation entry — otherwise its menu would be empty at runtime.`,
+    );
+  }
+
+  // 3. Every app has ≥ 1 role scoped to its code.
+  const rolesForApp = app.roles.filter((r) => r.applicationCode === app.code);
+  if (rolesForApp.length === 0) {
+    errors.push(
+      `${ctx}: no roles defined with applicationCode "${app.code}". Every Core seed must include at least one role per app (typically one per actor).`,
+    );
+  }
+
+  // 4. Every declared module has ≥ 2 permissions referencing one of its
+  // sections (access + read floor).
+  const sectionsByModuleCode = new Map<string, string[]>();
+  for (const sect of app.navigation.filter((n) => n.level === 'section')) {
+    if (!sect.parentCode) continue;
+    const arr = sectionsByModuleCode.get(sect.parentCode) ?? [];
+    arr.push(sect.code);
+    sectionsByModuleCode.set(sect.parentCode, arr);
+  }
+  for (const moduleCode of app.modules) {
+    const sections = sectionsByModuleCode.get(moduleCode) ?? [];
+    const sectionSet = new Set(sections);
+    const modulePerms = app.permissions.filter((p) => sectionSet.has(p.sectionCode));
+    if (modulePerms.length < 2) {
+      errors.push(
+        `${ctx}: module "${moduleCode}" has ${modulePerms.length} permission(s) — minimum is 2 (access + read). Sections under this module: [${sections.join(', ') || '(none)'}].`,
+      );
+    }
+  }
+
+  // 5. Permissions reference existing sections.
+  const allSectionCodes = new Set(app.navigation.filter((n) => n.level === 'section').map((n) => n.code));
+  for (const perm of app.permissions) {
+    if (!allSectionCodes.has(perm.sectionCode)) {
+      warnings.push(`${ctx}: permission ${perm.path} references unknown section: ${perm.sectionCode}`);
+    }
+  }
+
+  // 6. Role-permissions reference existing roles + permissions.
+  const roleCodes = new Set(app.roles.map((r) => r.code));
+  const permPaths = new Set(app.permissions.map((p) => p.path));
+  for (const rp of app.rolePermissions) {
+    if (!roleCodes.has(rp.roleCode)) {
+      warnings.push(`${ctx}: role-permission references unknown role: ${rp.roleCode}`);
+    }
+    if (!permPaths.has(rp.permissionPath)) {
+      warnings.push(`${ctx}: role-permission references unknown permission: ${rp.permissionPath}`);
+    }
+  }
+
+  // 7. Test users reference existing roles (hard error — Phase 5 needs them
+  // to log in, a typo here surfaces as 401s in UI tests).
+  for (const tu of app.testUsers) {
+    if (!roleCodes.has(tu.roleCode)) {
+      errors.push(`${ctx}: test user references unknown role: ${tu.roleCode}. Add the role to applications[${app.code}].roles or fix the typo.`);
+    }
+  }
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const structural = validateStructure(raw);
+  if (!structural.valid) return structural;
+  return validateBusinessRules(raw as CoreSeedSpec);
+}

package/templates/skills/development/backend/data-layer/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: backend-data-layer
+description: >
+  Generates Domain entities with BaseEntity (SmartStack.Core.Domain NuGet),
+  domain events, soft-delete, EF Core configurations with schema targeting,
+  and migrations.
+phase: development/backend
+cli: cli/
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Data Layer — Entities + Events + EF Core + Migration
+
+Generates domain entities, domain events, and their EF Core configurations
+following SmartStack conventions. Consumes NuGet packages:
+- `SmartStack.Core.Domain.BaseEntity` (provides `Id`, `CreatedAt`, `UpdatedAt`, `DeletedAt`, `AddDomainEvent`)
+- `SmartStack.Core.Domain.ITenantEntity` / `IOptionalTenantEntity`
+- `SmartStack.Core.Domain.IDomainEvent` (for emitted events)
+- `SmartStack.Infrastructure.Persistence.SchemaConstants` (Core vs Extensions)
+
+## Entity Pattern
+
+- `BaseEntity` inheritance (Id, CreatedAt, UpdatedAt, DeletedAt + domain events list)
+- Tenant: `ITenantEntity` (strict) / `IOptionalTenantEntity` / none
+- Private parameterless constructor + static `Create()` factory
+- `Update(...)` mutator with required-field validation
+- `SoftDelete()` / `Restore()` toggles `DeletedAt`
+- Domain events emitted on Create/Update/SoftDelete/Restore
+
+## Domain Events
+
+Each entity gets four companion event records in `{Entity}Events.cs`:
+
+```csharp
+public record EmployeeCreatedEvent(Guid EmployeeId) : IDomainEvent;
+public record EmployeeUpdatedEvent(Guid EmployeeId) : IDomainEvent;
+public record EmployeeDeletedEvent(Guid EmployeeId) : IDomainEvent;
+public record EmployeeRestoredEvent(Guid EmployeeId) : IDomainEvent;
+```
+
+Clients can subscribe via MediatR `INotificationHandler<EmployeeCreatedEvent>`.
+
+## Schema targeting
+
+The `schemaTarget` input decides the DB schema:
+- `"core"` → `SchemaConstants.Core` — for SmartStack built-in extensions only
+- `"extensions"` → `SchemaConstants.Extensions` (default) — for client modules
+
+Client projects should always leave `schemaTarget` to default. `"core"` is
+reserved for SDK-level seeding.
+
+## Table & column naming (aligned with SmartStack.app)
+
+- **Table**: `{domainPrefix}_{PluralName}` (PascalCase plural) in the selected
+  schema — e.g. `aff_Demandes`, `support_Tickets`, `hrm_Employees`.
+- **`domainPrefix`**: the entity's **business-domain** prefix from `entité.md`
+  (`Préfixe table: aff_` → `aff`), lowercase alphanumeric. **Never `ext`** —
+  `ext` is the migration prefix of the `extensions` schema, not a table prefix.
+- **Columns**: **PascalCase, EF Core default mapping — NO `HasColumnName`.**
+  SmartStack.app never remaps columns (`FirstName`, `CreatedAt`, `ClientId`),
+  so neither do we. snake_case columns are forbidden.
+- **FK columns**: `{TargetEntity}Id` (PascalCase), default mapping.
+
+## Indexes
+
+Always generated (EF Core default index names — no `HasDatabaseName` override):
+- an index on `CreatedAt` — sort/filter by recency
+- an index on `TenantId` (if tenant mode ≠ none)
+
+Additionally, any field flagged `indexed: true` in the spec gets its own index.
+
+## EF Core Configuration Pattern
+
+Columns use EF Core's **default PascalCase mapping** — no `HasColumnName`. Only
+constraints (required string / maxLength) and indexes are declared.
+
+```csharp
+public class EmployeeConfiguration : IEntityTypeConfiguration<Employee>
+{
+    public void Configure(EntityTypeBuilder<Employee> builder)
+    {
+        builder.ToTable("hrm_Employees", SchemaConstants.Extensions);
+        builder.HasKey(e => e.Id);
+        builder.HasQueryFilter(e => e.DeletedAt == null);
+
+        builder.HasIndex(e => e.CreatedAt);
+        builder.HasIndex(e => e.TenantId);
+
+        builder.Property(e => e.FirstName).IsRequired().HasMaxLength(100);
+        builder.Property(e => e.LastName).IsRequired().HasMaxLength(100);
+    }
+}
+```
+
+## Relationships (foreign keys)
+
+Same-module foreign keys are declared in the `relations[]` input — **not** as
+bare `Guid` fields. Each owning relation (`many-to-one` / `one-to-one`) emits, in
+generated code: the FK column (`{TargetEntity}Id` by default, or `foreignKey`),
+a reference **navigation property**, and a **real EF Core constraint**
+`HasOne(...).WithMany()/.WithOne().HasForeignKey(...).OnDelete(DeleteBehavior.X)`.
+
+`onDelete` mirrors the BA cascade vocabulary (`create-data-model/levels/relationships.md`):
+
+| `onDelete` | EF `DeleteBehavior` | Use when |
+|------------|---------------------|----------|
+| `restrict` (default) | `Restrict` | a rule blocks deletion of the parent |
+| `cascade` | `Cascade` | children can't exist without the parent |
+| `set-null` | `SetNull` | detach on delete (requires `nullable: true`) |
+| `no-action` | `NoAction` | self-references (SQL can't cascade a cycle) |
+
+`one-to-many` / `many-to-many` declared on the principal emit only the inverse
+collection navigation (`ICollection<T>`); the FK column lives on the owning side.
+
+Relation spec entry:
+
+```json
+{ "type": "many-to-one", "targetEntity": "Contact", "foreignKey": "ContactId", "nullable": false, "onDelete": "restrict" }
+```
+
+**The ONLY exception is cross-module / Core references** — model those as a plain
+`Guid` field with no relation, since a FK can't span DbContext boundaries (see
+`relationships.md` § Cross-module). Audit **DEV-DAT-008** fails the build (err)
+when a same-module PRD relationship has no matching FK constraint with the
+declared cascade.
+
+## CLIs
+
+- `scaffold-entity`: emits `Entity.cs` + `EntityEvents.cs` + `Configuration.cs` (incl. FK constraints + navigation properties from `relations[]`)
+- `scaffold-migration`: runs `dotnet ef migrations add` with the correct `-o` path
+
+## Invocation
+
+```bash
+npx tsx skills/development/backend/data-layer/cli/scaffold-entity/index.ts \
+  --spec '{"name":"Employee","module":"hrm","appCode":"MyApp","domainPrefix":"hrm","fields":[{"name":"FirstName","type":"string","required":true,"maxLength":100,"indexed":true}],"relations":[{"type":"many-to-one","targetEntity":"Department","foreignKey":"DepartmentId","nullable":false,"onDelete":"restrict"}],"tenantMode":"strict","schemaTarget":"extensions","projectPath":"/path"}'
+```
+
+## Key rules
+
+1. **Factory + private ctor**: `new Employee()` outside the class MUST fail.
+2. **Required string validation**: `ArgumentException.ThrowIfNullOrWhiteSpace(...)` in `Create` and `Update`.
+3. **Domain events on every state change**: Create/Update/SoftDelete/Restore each emit one.
+4. **Soft-delete, not hard-delete**: `SoftDelete()` sets `DeletedAt`. Physical deletion is an ops concern.
+5. **Query filter**: `HasQueryFilter(e => e.DeletedAt == null)` so soft-deleted rows are hidden by default.
+6. **Indexes default on**: CreatedAt and TenantId always indexed; other fields require `indexed: true`.
+7. **domainPrefix convention**: lowercase alphanumeric, no hyphen — the entity's
+   business-domain prefix from `entité.md` (`aff_` → `aff`), **never `ext`** (that
+   is the `extensions` migration prefix, not a table prefix).
+8. **Computed fields are skipped**: any `fields[]` entry with a non-empty
+   `formula` is **omitted** from the Domain entity and the EF Configuration —
+   the value lives only in the read DTOs (`scaffold-business` injects the
+   formula into the LINQ projection, single SQL query, no extra column).
+   Don't add a property by hand in the Domain entity for a computed field
+   ; the `[NotMapped]` round-trip would just confuse EF tracking.
+9. **Same-module relationships become real FKs**: each `relations[]` entry of
+   type `many-to-one` / `one-to-one` emits the FK column + navigation property +
+   `HasOne(...).HasForeignKey(...).OnDelete(DeleteBehavior.X)` with the declared
+   cascade. Only cross-module / Core references stay bare `Guid` fields
+   (DEV-DAT-008 enforces this — blocking).
+10. **Columns are PascalCase**: EF Core default mapping, NO `HasColumnName`. The
+   property name IS the column name (`FirstName`, `CreatedAt`, `ClientId`),
+   matching SmartStack.app. snake_case columns are forbidden.