@memberjunction/codegen-lib 4.0.0 → 4.1.0

package/README.md

@@ -1,31 +1,6 @@
 # @memberjunction/codegen-lib
 
-🚀 **The most sophisticated code generation engine you've ever seen** - automatically transforms your database schema into a complete, type-safe, full-stack application with AI-powered intelligence.
-
-## What Makes This Badass?
-
-MemberJunction's CodeGen doesn't just generate boilerplate code. It's an **AI-powered, metadata-driven architecture** that creates **bulletproof, production-ready applications** from your database schema with **zero manual intervention**.
-
-### 🧠 AI-Powered Intelligence
-- **CHECK Constraint Translation**: Our AI automatically translates complex SQL CHECK constraints into **perfect TypeScript union types** and **Zod validation schemas**
-- **Smart Type Inference**: Analyzes relationships and generates **contextually appropriate Angular form controls** (dropdowns, search boxes, checkboxes)
-- **Intelligent Naming**: AI-driven naming conventions ensure your generated code follows best practices
-
-### ⚡ Synchronization Across Everything
-Watch your database changes **instantly propagate** through your entire stack:
-```
-Database Schema Change → TypeScript Entities → Angular Forms → SQL Procedures → GraphQL Schema
-```
-**One command. Complete synchronization. Zero breaking changes.**
-
-### 🎯 What Gets Generated (Automatically)
-- **TypeScript Entity Classes** with full type safety and validation
-- **Angular Form Components** with proper field types and validation
-- **SQL Stored Procedures** for all CRUD operations
-- **Database Views** with optimized joins and indexing
-- **GraphQL Schemas** and resolvers
-- **Zod Validation Schemas** from SQL constraints
-- **Complete API Endpoints** with type-safe parameters
+The code generation engine for the MemberJunction platform. This library transforms database schema metadata into a complete, type-safe, full-stack application: TypeScript entity classes with Zod validation, Angular form components, SQL stored procedures and views, GraphQL resolvers, and Action subclasses -- all from a single `mj codegen` invocation.
 
 ## Installation
 
@@ -33,824 +8,1036 @@ Database Schema Change → TypeScript Entities → Angular Forms → SQL Procedu
 npm install @memberjunction/codegen-lib
 ```
 
-## The Magic in Action
-
-### From This SQL Constraint:
-```sql
-ALTER TABLE [AIPrompt]
-ADD [PromptRole] nvarchar(20) NOT NULL
-    CONSTRAINT [CK_AIPrompt_PromptRole] CHECK ([PromptRole] IN (N'System', N'User', N'Assistant', N'SystemOrUser'))
+## Overview
+
+CodeGenLib sits at the center of MemberJunction's development workflow. When you change a database schema (add a table, alter a column, define a CHECK constraint), CodeGenLib detects those changes, updates internal metadata, and regenerates synchronized code across every layer of the stack. The result is guaranteed type safety from database to UI with zero manual boilerplate.
+
+The library is designed for extensibility: every major generator is a base class that can be subclassed and registered via `@RegisterClass` to override or extend default behavior.
+
+```mermaid
+flowchart TD
+    subgraph Input["Input Sources"]
+        DB["SQL Server\nDatabase Schema"]
+        CFG["mj.config.cjs\nConfiguration"]
+        AI["AI Prompts\n(Advanced Generation)"]
+    end
+
+    subgraph Pipeline["CodeGen Pipeline"]
+        META["Metadata\nManagement"]
+        SQLGEN["SQL\nGeneration"]
+        ENTITY["Entity Class\nGeneration"]
+        ANGULAR["Angular\nGeneration"]
+        GQL["GraphQL\nGeneration"]
+        ACTION["Action\nGeneration"]
+    end
+
+    subgraph Output["Generated Outputs"]
+        VIEWS["Views &\nStored Procedures"]
+        TS["TypeScript Entity\nClasses + Zod"]
+        NG["Angular Form\nComponents"]
+        GQLR["GraphQL\nResolvers"]
+        ACTS["Action\nSubclasses"]
+        JSON["DB Schema\nJSON"]
+    end
+
+    DB --> META
+    CFG --> META
+    AI --> META
+
+    META --> SQLGEN
+    META --> ENTITY
+    META --> ANGULAR
+    META --> GQL
+    META --> ACTION
+
+    SQLGEN --> VIEWS
+    ENTITY --> TS
+    ANGULAR --> NG
+    GQL --> GQLR
+    ACTION --> ACTS
+    META --> JSON
+
+    style Input fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Pipeline fill:#7c5295,stroke:#563a6b,color:#fff
+    style Output fill:#2d8659,stroke:#1a5c3a,color:#fff
 ```
 
-### To This TypeScript (Automatically):
-```typescript
-PromptRole: z.union([
-    z.literal('System'), 
-    z.literal('User'), 
-    z.literal('Assistant'), 
-    z.literal('SystemOrUser')
-]).describe('Determines how the prompt is used in conversation...')
+## Key Features
+
+- **Full-Stack Synchronization**: A single schema change propagates to TypeScript entities, Angular forms, SQL procedures, and GraphQL resolvers automatically
+- **AI-Powered Intelligence**: Uses AI prompts to translate CHECK constraints into Zod schemas, generate semantic form layouts, identify name fields, and create entity descriptions
+- **Extensible Architecture**: Every generator (`SQLCodeGenBase`, `EntitySubClassGeneratorBase`, `AngularClientGeneratorBase`, etc.) can be subclassed and overridden via MJ's class factory
+- **Zod Validation Schemas**: Generates Zod schemas from SQL CHECK constraints with proper union types and refinements
+- **Recursive Hierarchy Support**: Automatically detects self-referential foreign keys and generates CTE-based `Root{FieldName}` columns in views
+- **Cascade Delete Generation**: Produces cursor-based cascade delete procedures that call child entity stored procedures, respecting business logic at every level
+- **Force Regeneration**: Surgically regenerate specific SQL objects for specific entities without requiring schema changes
+- **Class Registration Manifests**: Prevents tree-shaking of `@RegisterClass`-decorated classes by generating static import manifests
+- **SQL Migration Logging**: Outputs all generated SQL as Flyway-compatible migration files with schema placeholder support
+- **Configurable via Zod-Validated Config**: All settings validated at startup through comprehensive Zod schemas with sensible defaults
+
+## Architecture
+
+### Pipeline Stages
+
+The code generation process follows a well-defined pipeline orchestrated by the `RunCodeGenBase` class:
+
+```mermaid
+flowchart LR
+    S0["BEFORE\nCommands"]
+    S1["Metadata\nManagement"]
+    S2["SQL Object\nGeneration"]
+    S3["GraphQL\nResolvers"]
+    S4["Entity\nSubclasses"]
+    S5["Angular\nComponents"]
+    S6["DB Schema\nJSON"]
+    S7["Action\nSubclasses"]
+    S8["Integrity\nChecks"]
+    S9["AFTER\nCommands"]
+
+    S0 --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9
+
+    style S0 fill:#64748b,stroke:#475569,color:#fff
+    style S1 fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style S2 fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style S3 fill:#7c5295,stroke:#563a6b,color:#fff
+    style S4 fill:#7c5295,stroke:#563a6b,color:#fff
+    style S5 fill:#7c5295,stroke:#563a6b,color:#fff
+    style S6 fill:#7c5295,stroke:#563a6b,color:#fff
+    style S7 fill:#7c5295,stroke:#563a6b,color:#fff
+    style S8 fill:#b8762f,stroke:#8a5722,color:#fff
+    style S9 fill:#64748b,stroke:#475569,color:#fff
 ```
 
-### To This Angular Form (Automatically):
-```typescript
-<mj-form-field 
-    [record]="record"
-    FieldName="PromptRole"
-    Type="dropdownlist"  // AI chose dropdown based on constraint
-    [EditMode]="EditMode"
-></mj-form-field>
-```
+| Stage | Class | Description |
+|-------|-------|-------------|
+| BEFORE Commands | `RunCommandsBase` | Execute pre-generation shell commands and SQL scripts |
+| Metadata Management | `ManageMetadataBase` | Analyze schema changes, create/update entity metadata, run AI-powered field analysis |
+| SQL Generation | `SQLCodeGenBase` | Generate base views (with recursive CTEs), stored procedures (create/update/delete), foreign key indexes, permissions |
+| GraphQL Resolvers | `GraphQLServerGeneratorBase` | Generate TypeGraphQL resolver and type definitions for all API-enabled entities |
+| Entity Subclasses | `EntitySubClassGeneratorBase` | Generate TypeScript entity classes with Zod validation schemas, typed getters/setters, and value list types |
+| Angular Components | `AngularClientGeneratorBase` | Generate Angular form components with smart field types, category-based layouts, and related entity tabs |
+| DB Schema JSON | `DBSchemaGeneratorBase` | Export database schema as JSON for documentation and AI consumption |
+| Action Subclasses | `ActionSubClassGeneratorBase` | Generate Action implementation classes from metadata-defined business logic |
+| Integrity Checks | `SystemIntegrityBase` | Validate entity field sequences and other system consistency rules |
+| AFTER Commands | `RunCommandsBase` | Execute post-generation commands (typically package builds) |
 
-### To This SQL Procedure (Automatically):
-```sql
-CREATE PROCEDURE [spCreateAIPrompt]
-    @PromptRole nvarchar(20),
-    -- 20+ other parameters auto-generated
-AS BEGIN
-    -- Complete CRUD logic with validation
-END
-```
+### Core vs Non-Core Entity Separation
 
-**All from ONE schema change. All type-safe. All production-ready.**
+CodeGen distinguishes between core MemberJunction entities (in the `__mj` schema) and application-specific entities. Each generator runs twice: once for core entities with output directed to `@memberjunction/core-entities`, and once for non-core entities with output directed to the application's generated packages. This separation ensures MJ framework code and application code stay independent.
 
-## Quick Start - Watch The Magic
+### Class Factory Extensibility
 
-```typescript
-import { initializeConfig, runCodeGen } from '@memberjunction/codegen-lib';
+Every generator base class can be subclassed and registered with a higher priority to customize behavior:
 
-// Initialize configuration
-await initializeConfig();
+```mermaid
+classDiagram
+    class RunCodeGenBase {
+        +setupDataSource() SQLServerDataProvider
+        +Run(skipDatabaseGeneration) void
+    }
 
-// Generate your entire application stack
-await runCodeGen();
+    class ManageMetadataBase {
+        +manageMetadata(pool, user) boolean
+        +loadGeneratedCode(pool, user) boolean
+    }
 
-// That's it. Seriously.
-```
+    class SQLCodeGenBase {
+        +manageSQLScriptsAndExecution(pool, entities, dir, user) boolean
+        +runCustomSQLScripts(pool, when) boolean
+    }
 
-Your database schema just became:
-- ✅ **295+ TypeScript entity classes** with full validation
-- ✅ **Complete Angular UI** with smart form controls  
-- ✅ **All SQL stored procedures** for every operation
-- ✅ **GraphQL API** with type-safe resolvers
-- ✅ **Perfect type safety** across your entire stack
+    class EntitySubClassGeneratorBase {
+        +generateAllEntitySubClasses(pool, entities, dir, skipDB) boolean
+    }
+
+    class AngularClientGeneratorBase {
+        +generateAngularCode(entities, dir, prefix, user) boolean
+    }
+
+    class GraphQLServerGeneratorBase {
+        +generateGraphQLServerCode(entities, dir, lib, exclude) boolean
+    }
+
+    class ActionSubClassGeneratorBase {
+        +generateActions(actions, dir) boolean
+    }
 
-## Core Capabilities
+    RunCodeGenBase --> ManageMetadataBase : creates via ClassFactory
+    RunCodeGenBase --> SQLCodeGenBase : creates via ClassFactory
+    RunCodeGenBase --> EntitySubClassGeneratorBase : creates via ClassFactory
+    RunCodeGenBase --> AngularClientGeneratorBase : creates via ClassFactory
+    RunCodeGenBase --> GraphQLServerGeneratorBase : creates via ClassFactory
+    RunCodeGenBase --> ActionSubClassGeneratorBase : creates via ClassFactory
+
+    style RunCodeGenBase fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style ManageMetadataBase fill:#7c5295,stroke:#563a6b,color:#fff
+    style SQLCodeGenBase fill:#7c5295,stroke:#563a6b,color:#fff
+    style EntitySubClassGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
+    style AngularClientGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
+    style GraphQLServerGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
+    style ActionSubClassGeneratorBase fill:#7c5295,stroke:#563a6b,color:#fff
+```
 
-### 🏗️ Entity Subclass Generation
-Generates **bullet-proof TypeScript classes** from your database schema:
+To override any generator, subclass the base and register it:
 
 ```typescript
-// Auto-generated from your schema
-export class AIPromptEntity extends BaseEntity {
-  // 30+ properties with perfect types
-  PromptRole: 'System' | 'User' | 'Assistant' | 'SystemOrUser';
-  
-  // AI-powered validation from CHECK constraints
-  validate(): ValidationResult {
-    return this.validateWithZod(AIPromptSchema);
-  }
+import { RegisterClass } from '@memberjunction/global';
+import { EntitySubClassGeneratorBase } from '@memberjunction/codegen-lib';
+
+@RegisterClass(EntitySubClassGeneratorBase, undefined, 1) // priority 1 overrides default (0)
+export class CustomEntityGenerator extends EntitySubClassGeneratorBase {
+    // Override methods to customize generation
 }
 ```
 
-### 🎨 Angular Component Generation
-Creates **production-ready Angular forms** with intelligent field types:
+## Usage
+
+### Running the Full Pipeline
 
 ```typescript
-// Auto-detects relationships and creates search components
-<mj-form-field 
-    FieldName="CategoryID"
-    Type="textbox"           // Smart field type selection
-    LinkType="Record"        // Auto-detected relationship
-    LinkComponentType="Search" // AI chose search over dropdown
-></mj-form-field>
-```
+import { RunCodeGenBase, initializeConfig } from '@memberjunction/codegen-lib';
 
-### 🗃️ SQL Script Generation
-Generates **optimized database objects** with best practices:
+// Initialize configuration from working directory
+const config = initializeConfig(process.cwd());
 
-```sql
--- Auto-generated indexes for performance
-CREATE INDEX IDX_AUTO_MJ_FKEY_AIPrompt_CategoryID
-ON [AIPrompt] ([CategoryID]);
+// Run the complete code generation pipeline
+const codeGen = new RunCodeGenBase();
+await codeGen.Run();
 
--- Complete CRUD procedures with validation
-CREATE PROCEDURE [spCreateAIPrompt]
-    @PromptRole nvarchar(20) -- Validated against CHECK constraint
--- Full implementation auto-generated
+// Or skip database operations for faster UI-only regeneration
+await codeGen.Run(true);
 ```
 
-#### 🌲 Automatic Recursive Hierarchy Support
+The convenience function provides a simpler entry point:
 
-CodeGen **automatically detects self-referential foreign keys** and generates `Root{FieldName}` columns in base views using efficient recursive CTEs. This enables instant root node lookup for hierarchical data structures with **zero overhead when not selected**.
+```typescript
+import { runMemberJunctionCodeGeneration } from '@memberjunction/codegen-lib';
 
-**How It Works:**
+await runMemberJunctionCodeGeneration();
+```
 
-For any table with a self-referential foreign key (like `ParentTaskID` → `Task.ID`), CodeGen automatically:
+### Using Individual Generators
 
-1. **Detects the recursive relationship** - Identifies foreign keys where `RelatedEntityID === entity.ID`
-2. **Generates a recursive CTE** - Creates SQL that traverses the hierarchy to find the root
-3. **Adds Root columns** - Exposes `Root{FieldName}` in the base view (e.g., `RootParentTaskID`)
-4. **Zero-overhead when unused** - SQL optimizer eliminates the CTE when column not selected
+Each generator can be used independently:
 
-**Example - Task Hierarchy:**
+```typescript
+import { EntitySubClassGeneratorBase } from '@memberjunction/codegen-lib';
+import { MJGlobal } from '@memberjunction/global';
 
-```sql
-CREATE TABLE [Task] (
-    [ID] uniqueidentifier PRIMARY KEY,
-    [ParentTaskID] uniqueidentifier FOREIGN KEY REFERENCES [Task]([ID]),
-    [Name] nvarchar(255)
+const generator = MJGlobal.Instance.ClassFactory.CreateInstance<EntitySubClassGeneratorBase>(
+    EntitySubClassGeneratorBase
 );
+
+await generator.generateAllEntitySubClasses(pool, entities, outputDir, false);
 ```
 
-**CodeGen Automatically Generates:**
+### Generating Class Registration Manifests
 
-```sql
-CREATE VIEW [vwTasks]
-AS
-WITH
-    CTE_RootParentTaskID AS (
-        -- Anchor: rows with no parent (root nodes)
-        SELECT
-            [ID],
-            [ID] AS [RootParentTaskID]
-        FROM
-            [__mj].[Task]
-        WHERE
-            [ParentTaskID] IS NULL
-
-        UNION ALL
-
-        -- Recursive: traverse up the hierarchy
-        SELECT
-            child.[ID],
-            parent.[RootParentTaskID]
-        FROM
-            [__mj].[Task] child
-        INNER JOIN
-            CTE_RootParentTaskID parent ON child.[ParentTaskID] = parent.[ID]
-    )
-SELECT
-    t.*,
-    CTE_RootParentTaskID.[RootParentTaskID]  -- Auto-generated root column
-FROM
-    [__mj].[Task] AS t
-LEFT OUTER JOIN
-    CTE_RootParentTaskID
-  ON
-    t.[ID] = CTE_RootParentTaskID.[ID]
-```
+The manifest generator prevents tree-shaking of `@RegisterClass`-decorated classes:
 
-**Benefits:**
+```typescript
+import { generateClassRegistrationsManifest } from '@memberjunction/codegen-lib';
 
-- ✅ **Automatic Detection** - No configuration needed, works for any recursive FK
-- ✅ **Multiple Recursive FKs** - Handles tables with multiple self-referential relationships
-- ✅ **SQL Optimizer Magic** - CTE only executes when `RootParentTaskID` is selected
-- ✅ **Always Correct** - No stale data (unlike computed columns or triggers)
-- ✅ **TypeScript Integration** - Root fields automatically appear in entity classes
-- ✅ **Naming Convention** - Consistent `Root{FieldName}` pattern across all entities
+const result = await generateClassRegistrationsManifest({
+    outputPath: './src/generated/class-registrations-manifest.ts',
+    appDir: './packages/MJAPI',
+    excludePackages: ['@memberjunction'], // Use pre-built manifest for MJ packages
+});
 
-**Use Cases:**
+if (result.success) {
+    console.log(`${result.packages.length} packages, ${result.classes.length} classes`);
+}
+```
 
-- **Organizational Charts** - `Employee.ManagerID` → `RootManagerID` finds CEO
-- **Task Hierarchies** - `Task.ParentTaskID` → `RootParentTaskID` finds root project
-- **Category Trees** - `Category.ParentCategoryID` → `RootParentCategoryID` finds top level
-- **Comment Threads** - `Comment.ParentCommentID` → `RootParentCommentID` finds original post
-- **Bill of Materials** - `Part.ParentPartID` → `RootParentPartID` finds top-level assembly
+See the [Class Manifest Guide](CLASS_MANIFEST_GUIDE.md) for comprehensive documentation on the manifest system.
 
-**Performance Note:**
+## Configuration
 
-The CTE approach is **ideal for read-heavy workloads** (typical in business applications). The SQL optimizer completely eliminates the CTE from the execution plan when the root column isn't selected, meaning zero overhead for queries that don't need hierarchy information.
+CodeGenLib uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to locate configuration. The recommended approach is a `mj.config.cjs` file at the repository root:
 
-#### 🎯 Smart Delete Procedures with Cascade Handling
+```javascript
+module.exports = {
+    // Database connection
+    dbHost: 'localhost',
+    dbPort: 1433,
+    dbDatabase: 'YourDatabase',
+    codeGenLogin: 'codegen_user',
+    codeGenPassword: 'your_password',
+    mjCoreSchema: '__mj',
+
+    // Output directories for each generator
+    output: [
+        { type: 'SQL', directory: '../../SQL Scripts/generated' },
+        { type: 'Angular', directory: '../MJExplorer/src/app/generated' },
+        { type: 'GraphQLServer', directory: '../MJAPI/src/generated' },
+        { type: 'CoreEntitySubclasses', directory: '../MJCoreEntities/src/generated' },
+        { type: 'EntitySubclasses', directory: '../GeneratedEntities/src/generated' },
+    ],
+
+    // AI-powered features
+    advancedGeneration: {
+        enableAdvancedGeneration: true,
+        features: [
+            { name: 'SmartFieldIdentification', enabled: true },
+            { name: 'FormLayoutGeneration', enabled: true },
+            { name: 'ParseCheckConstraints', enabled: true },
+            { name: 'TransitiveJoinIntelligence', enabled: true },
+        ],
+    },
 
-Our generated delete procedures are **production-grade** with intelligent handling of:
+    // SQL output for Flyway migrations
+    SQLOutput: {
+        enabled: true,
+        folderPath: './migrations/v3/',
+        convertCoreSchemaToFlywayMigrationFile: true,
+    },
 
-**1. Result Feedback - Know What Happened**
-```sql
--- Returns NULL for all PKs when no record found
-IF @@ROWCOUNT = 0
-    SELECT NULL AS [CustomerID], NULL AS [OrderID]
-ELSE
-    SELECT @CustomerID AS [CustomerID], @OrderID AS [OrderID]
+    // Force regeneration of specific objects
+    forceRegeneration: {
+        enabled: false,
+        entityWhereClause: "SchemaName = 'dbo'",
+        baseViews: true,
+        spUpdate: true,
+    },
+};
 ```
 
-**2. Cascade Deletes via Stored Procedure Calls**
+All configuration is validated at startup using Zod schemas, with clear error messages for invalid settings. Environment variables (`DB_HOST`, `DB_DATABASE`, `CODEGEN_DB_USERNAME`, `CODEGEN_DB_PASSWORD`) provide fallback values for database connection settings.
 
-Instead of basic DELETE statements, we generate **cursor-based cascade operations** that respect your business logic:
+### Key Configuration Sections
 
-```sql
--- BAD: Direct DELETE (bypasses business logic)
-DELETE FROM OrderItems WHERE OrderID = @OrderID
+| Section | Purpose |
+|---------|---------|
+| `output` | Maps each generator type to its output directory |
+| `advancedGeneration` | Controls which AI-powered features are enabled |
+| `newEntityDefaults` | Default settings for newly discovered entities (permissions, tracking, API access) |
+| `forceRegeneration` | Surgically regenerate specific SQL object types for filtered entities |
+| `SQLOutput` | Controls Flyway migration file generation from SQL logging |
+| `commands` | Shell commands to run before/after generation (typically package builds) |
+| `excludeSchemas` / `excludeTables` | Filter schemas and tables from metadata discovery |
 
--- GOOD: Cursor-based SP calls (respects custom logic)
-DECLARE @RelatedItemID INT
-DECLARE cascade_delete_OrderItem_cursor CURSOR FOR 
-    SELECT [ItemID] FROM [OrderItems] WHERE [OrderID] = @OrderID
+## What Gets Generated
 
-OPEN cascade_delete_OrderItem_cursor
-FETCH NEXT FROM cascade_delete_OrderItem_cursor INTO @RelatedItemID
+### TypeScript Entity Classes
 
-WHILE @@FETCH_STATUS = 0
-BEGIN
-    -- Calls YOUR stored procedure, enabling N-level cascades
-    EXEC [spDeleteOrderItem] @RelatedItemID
-    FETCH NEXT FROM cascade_delete_OrderItem_cursor INTO @RelatedItemID
-END
+From a SQL table with CHECK constraints, CodeGen produces a complete entity class:
 
-CLOSE cascade_delete_OrderItem_cursor
-DEALLOCATE cascade_delete_OrderItem_cursor
-```
+```typescript
+// Auto-generated from database schema
+export class AIPromptEntity extends BaseEntity {
+    // Typed getter/setter for CHECK-constrained field
+    get PromptRole(): 'System' | 'User' | 'Assistant' | 'SystemOrUser' {
+        return this.Get('PromptRole');
+    }
+    set PromptRole(value: 'System' | 'User' | 'Assistant' | 'SystemOrUser') {
+        this.Set('PromptRole', value);
+    }
 
-**Benefits:**
-- ✅ **Respects custom delete logic** in related entities
-- ✅ **Enables multi-level cascades** (if OrderItem has its own cascades)
-- ✅ **Maintains referential integrity** through proper SP calls
-- ✅ **Clear result feedback** - NULL means no record deleted
+    // Zod validation from CHECK constraint
+    validate(): ValidationResult {
+        return this.validateWithZod(AIPromptSchema);
+    }
+}
+
+// Zod schema with union types from CHECK constraint
+export const AIPromptSchema = z.object({
+    PromptRole: z.union([
+        z.literal('System'),
+        z.literal('User'),
+        z.literal('Assistant'),
+        z.literal('SystemOrUser'),
+    ]),
+    // ... all other fields
+});
+```
 
-**3. Nullable Foreign Key Handling**
+### SQL Views with Recursive Hierarchy Support
 
-For nullable FKs, we update via stored procedures too:
+For tables with self-referential foreign keys, CodeGen automatically generates recursive CTEs:
 
 ```sql
--- Fetch all fields, update only the FK to NULL
-DECLARE cascade_update_Customer_cursor CURSOR FOR 
-    SELECT * FROM [Customers] WHERE [RegionID] = @RegionID
+-- Auto-detected: Task.ParentTaskID references Task.ID
+CREATE VIEW [vwTasks] AS
+WITH CTE_RootParentTaskID AS (
+    SELECT [ID], [ID] AS [RootParentTaskID]
+    FROM [__mj].[Task]
+    WHERE [ParentTaskID] IS NULL
+
+    UNION ALL
+
+    SELECT child.[ID], parent.[RootParentTaskID]
+    FROM [__mj].[Task] child
+    INNER JOIN CTE_RootParentTaskID parent
+        ON child.[ParentTaskID] = parent.[ID]
+)
+SELECT t.*, cte.[RootParentTaskID]
+FROM [__mj].[Task] AS t
+LEFT OUTER JOIN CTE_RootParentTaskID cte ON t.[ID] = cte.[ID]
+```
+
+The CTE is zero-overhead: the SQL optimizer eliminates it entirely when the root column is not selected.
+
+### Angular Form Components
 
--- In cursor loop:
-SET @UpdateRegionID = NULL  -- Only FK changes
-EXEC [spUpdateCustomer] @CustomerID, @Name, @Email, @UpdateRegionID
+CodeGen creates production-ready Angular forms with AI-determined field categories and smart field types:
+
+```typescript
+@Component({
+    selector: 'mj-ai-prompt-form',
+    template: `
+        <mj-form-field [record]="record"
+            FieldName="PromptRole"
+            Type="dropdownlist"
+            [EditMode]="EditMode">
+        </mj-form-field>
+    `
+})
+export class AIPromptFormComponent extends BaseFormComponent { }
 ```
 
-**4. Configuration Error Detection**
+### Cascade Delete Procedures
 
-CodeGen **warns you** about misconfigured cascade scenarios:
+Delete procedures use cursor-based stored procedure calls to respect business logic at every level of the hierarchy:
 
 ```sql
--- WARNING: Orders has non-nullable FK to Customer but doesn't allow delete API
--- This will cause a referential integrity violation
+CREATE PROCEDURE [spDeleteOrder] @ID UNIQUEIDENTIFIER AS
+BEGIN
+    -- Cascade through child stored procedures
+    DECLARE @ItemID UNIQUEIDENTIFIER
+    DECLARE cascade_cursor CURSOR FOR
+        SELECT [ID] FROM [OrderItems] WHERE [OrderID] = @ID
+
+    OPEN cascade_cursor
+    FETCH NEXT FROM cascade_cursor INTO @ItemID
+    WHILE @@FETCH_STATUS = 0
+    BEGIN
+        EXEC [spDeleteOrderItem] @ItemID  -- Respects OrderItem's own cascade logic
+        FETCH NEXT FROM cascade_cursor INTO @ItemID
+    END
+    CLOSE cascade_cursor
+    DEALLOCATE cascade_cursor
+
+    DELETE FROM [Orders] WHERE [ID] = @ID
+END
 ```
 
-The warnings appear both in generated SQL **and** console output during generation.
+## AI-Powered Advanced Generation
+
+When `advancedGeneration.enableAdvancedGeneration` is enabled, CodeGen uses AI prompts (stored in the database as AI Prompt entities) to enhance the generation process:
+
+```mermaid
+flowchart TD
+    subgraph Features["AI-Powered Features"]
+        SF["Smart Field\nIdentification"]
+        FL["Form Layout\nGeneration"]
+        CC["CHECK Constraint\nParsing"]
+        ED["Entity\nDescriptions"]
+        TJ["Transitive Join\nIntelligence"]
+        EN["Entity Name\nGeneration"]
+    end
+
+    subgraph Results["What AI Determines"]
+        SF --> R1["Name fields, Default-in-View\nfields, Searchable fields"]
+        FL --> R2["Field categories, Icons\nDisplay names, Extended types"]
+        CC --> R3["Zod schemas, Validation\nfunctions, Descriptions"]
+        ED --> R4["Entity descriptions\nfor new entities"]
+        TJ --> R5["Junction table detection\nMany-to-many relationships"]
+        EN --> R6["Human-friendly entity\nnames from table names"]
+    end
+
+    style Features fill:#7c5295,stroke:#563a6b,color:#fff
+    style Results fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
-#### 🔄 Smart Update Procedures with Result Validation
+| Feature | Purpose | When It Runs |
+|---------|---------|-------------|
+| `SmartFieldIdentification` | Determines which field is the "name" field, which fields show in default views, and which are searchable | Entity/field creation, or when `AutoUpdate` flags allow |
+| `FormLayoutGeneration` | Groups fields into semantic categories with icons and display names | Every run (forms are always regenerated) |
+| `ParseCheckConstraints` | Translates SQL CHECK constraints into Zod validation schemas and TypeScript union types | When CHECK constraints are detected |
+| `EntityDescriptions` | Generates human-readable descriptions for entities | Entity creation only |
+| `TransitiveJoinIntelligence` | Detects junction tables and many-to-many relationships | Entity/relationship creation |
+| `EntityNames` | Converts technical table names to user-friendly entity names | Entity creation only |
+| `VirtualEntityFieldDecoration` | Analyzes SQL view definitions to identify PKs, FKs, descriptions, and extended types for virtual entities | Virtual entity creation (idempotent unless `forceRegenerate` option is set) |
 
-Our update procedures also provide **clear feedback** when operating on non-existent records:
+### Form Layout Stability Guarantees
 
-```sql
--- Check if update affected any rows
-IF @@ROWCOUNT = 0
-    -- Return empty result set (maintains column structure)
-    SELECT TOP 0 * FROM [vwCustomer] WHERE 1=0
-ELSE
-    -- Return the updated record with calculated fields
-    SELECT * FROM [vwCustomer] WHERE [CustomerID] = @CustomerID
-```
+The form layout system enforces stability to prevent unnecessary churn:
 
-**Why This Matters:**
-- **Empty result set** = Record not found (update failed)
-- **Record returned** = Update successful
-- **Maintains schema** = Calling code doesn't break
-- **Includes calculated fields** = Get the latest computed values
+- Existing category names and icons are never changed by AI
+- AI can assign fields to existing categories or create categories for genuinely new field groups
+- Existing fields cannot be moved to newly created categories (prevents renaming)
+- Per-field `AutoUpdateCategory` and `AutoUpdateDisplayName` flags provide granular control
 
-### 🌐 GraphQL Schema Generation
-Creates **type-safe GraphQL APIs** from your entities:
+## Force Regeneration
 
-```graphql
-type AIPrompt {
-  id: ID!
-  promptRole: PromptRoleEnum!  # Auto-generated from CHECK constraint
-  category: AIPromptCategory   # Auto-resolved relationships
+Regenerate specific SQL objects without schema changes using surgical filtering:
+
+```javascript
+// In mj.config.cjs
+forceRegeneration: {
+    enabled: true,
+    // Filter to specific entities
+    entityWhereClause: "SchemaName = 'CRM' AND __mj_UpdatedAt >= '2025-06-24'",
+    // Control which object types regenerate
+    baseViews: true,
+    spCreate: false,
+    spUpdate: true,
+    spDelete: false,
+    indexes: true,
 }
+```
 
-enum PromptRoleEnum {
-  SYSTEM
-  USER
-  ASSISTANT
-  SYSTEMORUSER
+Only the intersection of matched entities and enabled object types gets regenerated.
+
+## SQL Migration Logging
+
+All SQL generated during metadata management and object generation is logged to a Flyway-compatible migration file. The `SQLOutput` configuration controls this behavior:
+
+```javascript
+SQLOutput: {
+    enabled: true,
+    folderPath: './migrations/v3/',
+    appendToFile: true,
+    convertCoreSchemaToFlywayMigrationFile: true,
+    schemaPlaceholders: [
+        { schema: '__mj', placeholder: '${flyway:defaultSchema}' },
+    ],
 }
 ```
 
-### 🔬 Database Schema Introspection
-**Reverse-engineers your entire database** into metadata:
+The `SQLLogging` class accumulates all SQL statements during a run and writes them as a single migration file with schema names replaced by Flyway placeholders.
+
+## Source Structure
 
-```typescript
-const schemaInfo = await analyzeSchema(connection);
-// Discovers tables, relationships, constraints, indexes
-// Feeds AI engine for intelligent code generation
+```
+src/
+  index.ts                          # Public API exports
+  runCodeGen.ts                     # RunCodeGenBase - main pipeline orchestrator
+
+  Config/
+    config.ts                       # Zod-validated configuration schemas and loaders
+    db-connection.ts                # SQL Server connection pool management
+
+  Database/
+    manage-metadata.ts              # ManageMetadataBase - schema analysis and metadata sync
+    sql_codegen.ts                  # SQLCodeGenBase - views, procedures, indexes, permissions
+    sql.ts                          # SQLUtilityBase - SQL file management and execution
+    dbSchema.ts                     # DBSchemaGeneratorBase - JSON schema export
+    reorder-columns.ts              # Table column reordering utilities
+
+  Angular/
+    angular-codegen.ts              # AngularClientGeneratorBase - form and module generation
+    related-entity-components.ts    # Base classes for related entity display components
+    entity-data-grid-related-entity-component.ts  # Data grid component generator
+    join-grid-related-entity-component.ts         # Join grid component generator
+    timeline-related-entity-component.ts          # Timeline component generator
+
+  Misc/
+    entity_subclasses_codegen.ts    # EntitySubClassGeneratorBase - TypeScript entity generation
+    action_subclasses_codegen.ts    # ActionSubClassGeneratorBase - Action class generation
+    graphql_server_codegen.ts       # GraphQLServerGeneratorBase - resolver generation
+    advanced_generation.ts          # AdvancedGeneration - AI-powered enhancement features
+    status_logging.ts               # Spinner and log utilities (ora-based)
+    sql_logging.ts                  # SQLLogging - migration file accumulator
+    system_integrity.ts             # SystemIntegrityBase - post-generation validation
+    createNewUser.ts                # CreateNewUserBase - initial user setup
+    runCommand.ts                   # RunCommandsBase - shell command execution
+    util.ts                         # File system and sorting utilities
+
+  Manifest/
+    GenerateClassRegistrationsManifest.ts  # Tree-shaking prevention manifest generator
 ```
 
-## Advanced Features That Blow Minds
+## API Reference
 
-### 🎨 AI-Powered Form Layout Generation
+### RunCodeGenBase
 
-CodeGen uses AI to automatically organize entity fields into **semantic categories** with icons, creating intuitive form layouts without manual configuration.
+The main orchestrator class. Creates instances of all generator classes via `MJGlobal.ClassFactory` and runs the pipeline.
 
-#### What It Does:
+| Method | Description |
+|--------|-------------|
+| `Run(skipDatabaseGeneration?)` | Execute the full code generation pipeline. Pass `true` to skip database operations. |
+| `setupDataSource()` | Initialize the SQL Server connection pool and data provider. |
 
-1. **Field Categorization** - Groups fields into domain-specific categories (e.g., "Billing Address", "Pricing and Charges", "System Metadata")
-2. **Category Icons** - Assigns Font Awesome icons to each category for visual navigation
-3. **Category Descriptions** - Generates tooltip descriptions for UX enhancement
-4. **Entity Importance Analysis** - Determines if entities should appear in navigation for new users
-5. **Smart Display Names** - Converts technical field names to user-friendly labels (e.g., `BillToAddress1` → "Billing Address Line 1")
+### ManageMetadataBase
 
-#### Entity Importance Detection:
+Analyzes database schema changes and updates MJ metadata tables.
 
-The AI uses **FK ratio analysis** to classify entities:
+| Method | Description |
+|--------|-------------|
+| `manageMetadata(pool, user)` | Full metadata management: detect schema changes, create entities/fields, run AI features. |
+| `loadGeneratedCode(pool, user)` | Load previously generated AI code from database (used when skipping DB generation). |
 
-| Entity Type | FK Ratio | Example | DefaultForNewUser |
-|-------------|----------|---------|-------------------|
-| **Primary** | 10-30% | Contact, Order, Deal | ✅ Yes |
-| **Supporting** | 20-40% | OrderItem, Address | Sometimes |
-| **Reference/Type** | 0-20% | OrderStatus, ContactType | ❌ No |
-| **Junction** | 40-80% | UserRole, ContactAccount | ❌ No |
+### SQLCodeGenBase
 
-#### Stability Guarantees:
+Generates database objects: views, stored procedures, indexes, and permissions.
 
-The system enforces **category stability** to prevent unnecessary churn on existing entities:
+| Method | Description |
+|--------|-------------|
+| `manageSQLScriptsAndExecution(pool, entities, dir, user)` | Generate and execute all SQL objects for the given entities. |
+| `runCustomSQLScripts(pool, when)` | Execute custom SQL scripts configured for the specified timing. |
 
-**What's Preserved (Never Changed by AI):**
-- ✅ Existing category names - AI cannot rename "Personal Info" to "Personal Details"
-- ✅ Existing category icons - Icons set by admins or previous runs are preserved
-- ✅ Existing category descriptions - Descriptions are only added, never modified
+### EntitySubClassGeneratorBase
 
-**What AI Can Do:**
-- ✅ Assign NEW fields to existing categories
-- ✅ Assign NEW fields to NEW categories (when no existing category fits)
-- ✅ Move existing fields between EXISTING categories (with discretion)
-- ❌ Move existing fields to NEW categories (blocked - prevents renaming)
+Generates TypeScript entity classes with Zod validation.
 
-**Enforcement Example:**
-```
-Field 'Email' is in category 'Contact Info'
-LLM suggests moving to 'Communication Details' (new category)
-→ REJECTED: Cannot move existing field to new category
-→ Field stays in 'Contact Info'
-```
+| Method | Description |
+|--------|-------------|
+| `generateAllEntitySubClasses(pool, entities, dir, skipDB)` | Generate all entity subclass files including Zod schemas. |
+| `generateEntitySubClass(pool, entity, includeHeader, skipDB)` | Generate a single entity subclass. |
+| `GenerateSchemaAndType(entity)` | Generate Zod schema and TypeScript type for an entity. |
 
-**Control Flags on EntityField:**
-- `AutoUpdateCategory` - If FALSE, field's category is locked
-- `AutoUpdateDisplayName` - If FALSE, display name is locked
-- `AutoUpdateIsNameField` - If FALSE, name field designation is locked
+### AngularClientGeneratorBase
 
-#### DefaultForNewUser - Only for New Entities:
+Generates Angular form components, section components, and Angular modules.
 
-The `DefaultForNewUser` flag is **only set when an entity is first created**, not on subsequent updates. This ensures:
-- Admins retain full control over navigation visibility
-- CodeGen won't override manual admin decisions
-- Existing entity configurations remain stable
+| Method | Description |
+|--------|-------------|
+| `generateAngularCode(entities, dir, prefix, user)` | Generate all Angular components and modules. |
 
-#### Storage Format:
+### GraphQLServerGeneratorBase
 
-Category information is stored in `EntitySetting` with two formats for compatibility:
+Generates TypeGraphQL resolver and type definitions.
 
-**New Format** (`FieldCategoryInfo`):
-```json
-{
-  "Billing Address": {
-    "icon": "fa fa-file-invoice",
-    "description": "Address for invoice delivery and billing correspondence"
-  },
-  "System Metadata": {
-    "icon": "fa fa-cog",
-    "description": "System-managed audit and tracking fields"
-  }
-}
-```
+| Method | Description |
+|--------|-------------|
+| `generateGraphQLServerCode(entities, dir, lib, exclude)` | Generate GraphQL resolvers for all entities. |
 
-**Legacy Format** (`FieldCategoryIcons`) - maintained for backwards compatibility:
-```json
-{
-  "Billing Address": "fa fa-file-invoice",
-  "System Metadata": "fa fa-cog"
-}
-```
+### generateClassRegistrationsManifest
 
-### 🤖 AI-Powered CHECK Constraint Translation
-Our AI doesn't just copy constraints - it **understands intent**:
+Generates an import manifest that prevents tree-shaking of `@RegisterClass` decorated classes. See the [Class Manifest Guide](CLASS_MANIFEST_GUIDE.md) for full documentation.
 
-```sql
--- Complex constraint
-CHECK ([Status] IN ('Draft', 'Published', 'Archived') 
-       AND [PublishedAt] IS NOT NULL WHEN [Status] = 'Published')
-```
+| Option | Description |
+|--------|-------------|
+| `outputPath` | Path for the generated manifest file |
+| `appDir` | Directory containing the app's `package.json` (default: `process.cwd()`) |
+| `filterBaseClasses` | Only include classes extending specific base classes |
+| `excludePackages` | Skip packages matching name prefixes (e.g., `['@memberjunction']`) |
 
-Becomes **perfect TypeScript**:
+### Configuration Functions
 
-```typescript
-Status: z.union([z.literal('Draft'), z.literal('Published'), z.literal('Archived')])
-  .refine((status, ctx) => {
-    if (status === 'Published' && !this.PublishedAt) {
-      ctx.addIssue({ code: 'custom', message: 'Published items must have PublishedAt' });
-    }
-  })
-```
+| Function | Description |
+|----------|-------------|
+| `initializeConfig(cwd)` | Load and validate configuration from the given directory |
+| `outputDir(type, fallback)` | Get the configured output directory for a generator type |
+| `getSettingValue(name, default)` | Get a named setting value from configuration |
+| `mj_core_schema()` | Get the MJ core schema name (typically `__mj`) |
 
-### 🔄 Real-Time Synchronization
-Change your database schema → **Everything updates automatically**:
+## Dependencies
 
-1. **Flyway migration** executes
-2. **CodeGen detects changes**
-3. **Regenerates affected code**
-4. **Type safety maintained** across entire stack
-5. **Zero manual intervention**
+This package depends on:
 
-### 🚀 Performance Optimization
-- **Intelligent caching** prevents unnecessary regeneration
-- **Incremental updates** for changed entities only
-- **Optimized SQL** with proper indexing strategies
-- **Lazy loading** for large schema datasets
+- [@memberjunction/core](../MJCore) - Entity framework, metadata system, and type utilities
+- [@memberjunction/core-entities](../MJCoreEntities) - Generated entity classes for MJ system entities
+- [@memberjunction/global](../MJGlobal) - `@RegisterClass` decorator and `MJGlobal.ClassFactory`
+- [@memberjunction/sqlserver-dataprovider](../SQLServerDataProvider) - SQL Server data provider and connection management
+- [@memberjunction/ai](../AI) - AI provider abstraction layer
+- [@memberjunction/ai-prompts](../AI/Prompts) - AI prompt execution for advanced generation features
+- [@memberjunction/ai-core-plus](../AI/CorePlus) - AI prompt parameter types
+- [@memberjunction/aiengine](../AIEngine) - AI engine for model and prompt configuration
+- [@memberjunction/actions](../Actions/Engine) - Action engine for action code generation
+- [@memberjunction/actions-base](../Actions/Base) - Action base classes and types
+- [@memberjunction/config](../Config) - Configuration merging utilities
+- [@memberjunction/server-bootstrap-lite](../server-bootstrap-lite) - Pre-built class registration manifest
 
-### 🔒 Enterprise-Grade Security
-- **Parameterized queries** in all generated SQL
-- **Input validation** at every layer
-- **SQL injection protection** built-in
-- **Type-safe APIs** prevent runtime errors
+## Related Packages
 
-## Configuration
+- [@memberjunction/cli](../MJCLI) - CLI that invokes CodeGenLib (`mj codegen` commands)
+- [@memberjunction/core-entities](../MJCoreEntities) - Contains the generated `entity_subclasses.ts` output
+- [@memberjunction/server-bootstrap](../server-bootstrap) - Ships pre-built server-side class manifest
+- [@memberjunction/ng-bootstrap](../Angular/ng-bootstrap) - Ships pre-built Angular class manifest
 
-Create a `.memberjunctionrc` file:
+## Documentation
 
-```json
-{
-  "memberjunction": {
-    "database": {
-      "server": "localhost",
-      "database": "YourDatabase",
-      "trustedConnection": true
-    },
-    "directories": {
-      "output": "./generated",
-      "entities": "./generated/entities",
-      "actions": "./generated/actions",
-      "angular": "./generated/angular",
-      "sql": "./generated/sql"
-    },
-    "ai": {
-      "enabled": true,
-      "provider": "openai"  // Powers constraint translation
-    }
-  }
-}
-```
+- [Class Manifest Guide](CLASS_MANIFEST_GUIDE.md) - Comprehensive guide to the manifest system for preventing tree-shaking of `@RegisterClass` classes
+- [EXAMPLE_MANIFEST_MJAPI.md](EXAMPLE_MANIFEST_MJAPI.md) - Example server-side manifest (54 packages, 715 classes)
+- [EXAMPLE_MANIFEST_MJEXPLORER.md](EXAMPLE_MANIFEST_MJEXPLORER.md) - Example client-side manifest (17 packages, 721 classes)
 
-## Real-World Example
+## IS-A Type Relationships in CodeGen
 
-Starting with a simple table:
+MemberJunction supports **IS-A (inheritance) relationships** between entities, where one entity extends another by adding additional fields while inheriting the parent's schema. CodeGen automatically handles IS-A relationships with specialized generation logic.
 
-```sql
-CREATE TABLE [Customer] (
-    [ID] uniqueidentifier PRIMARY KEY DEFAULT newsequentialid(),
-    [Name] nvarchar(255) NOT NULL,
-    [Status] nvarchar(20) CHECK ([Status] IN ('Active', 'Inactive', 'Suspended')),
-    [CreatedAt] datetimeoffset DEFAULT getutcdate()
-);
-```
+For comprehensive conceptual documentation, see the **[IS-A Relationships Guide](../../MJCore/docs/isa-relationships.md)** in MJCore.
 
-**One CodeGen run produces:**
+### How CodeGen Handles IS-A Entities
 
-### TypeScript Entity (175 lines)
-```typescript
-export class CustomerEntity extends BaseEntity {
-    Status: 'Active' | 'Inactive' | 'Suspended';
-    // + complete validation, save methods, relationships
-}
-```
+When an entity has a `ParentEntity` relationship (IS-A child):
 
-### Angular Component (89 lines)
-```typescript
-@Component({
-    template: `Complete form with validation and smart controls`
-})
-export class CustomerDetailsComponent {
-    // Ready for production use
-}
-```
+#### 1. SQL View Generation - Parent JOINs
+**Child views automatically JOIN to parent views** to provide a complete record with all inherited fields:
 
-### SQL Procedures (200+ lines)
 ```sql
--- spCreateCustomer, spUpdateCustomer, spDeleteCustomer
--- Complete with validation and error handling
+-- CodeGen automatically generates:
+CREATE VIEW [vwEmployee]
+AS
+SELECT
+    e.*,               -- All Employee fields
+    p.FirstName,       -- Inherited from Person
+    p.LastName,        -- Inherited from Person
+    p.DateOfBirth      -- Inherited from Person
+FROM
+    [__mj].[Employee] AS e
+INNER JOIN
+    [__mj].[vwPerson] AS p ON e.[ID] = p.[ID]
 ```
 
-### GraphQL Schema (45 lines)
-```graphql
-type Customer {
-    # Complete type-safe schema
-}
-```
+This ensures querying the child view returns a complete record including all parent fields.
 
-**Total: 500+ lines of production code from 6 lines of SQL.**
+#### 2. Stored Procedure Generation - Child Fields Only
+**Create and Update procedures only include the child's own fields**, not parent fields:
 
-### Class Registrations Manifest Generation
+```sql
+-- spCreateEmployee only has Employee-specific parameters
+CREATE PROCEDURE [spCreateEmployee]
+    @ID uniqueidentifier,
+    @EmployeeNumber nvarchar(50),
+    @HireDate date,
+    @Salary decimal(18,2)
+    -- No FirstName, LastName (those are Person fields)
+AS BEGIN
+    -- Only inserts into Employee table
+    INSERT INTO [__mj].[Employee] (ID, EmployeeNumber, HireDate, Salary)
+    VALUES (@ID, @EmployeeNumber, @HireDate, @Salary)
+END
+```
 
-Generates an import manifest that prevents tree-shaking of `@RegisterClass` decorated classes. The tool walks an app's transitive dependency tree and produces a tailored manifest for each application.
+**Why this design?** When creating an Employee, you first create the Person record (which gets an ID), then use that same ID to create the Employee record. The stored procedures reflect this two-step creation pattern.
 
-**Why this matters:** Decorators like `@RegisterClass` only execute if their file is imported. Bundlers can tree-shake entire files that appear unused, silently breaking MemberJunction's class factory system. The manifest ensures all registered classes are imported.
+#### 3. GraphQL Schema Generation - Complete Field Set
+**GraphQL input types include ALL fields (parent + child)** for seamless API usage:
 
-**How it works:**
-1. Reads the app's `package.json` and walks the full transitive dependency tree
-2. Scans each dependency's `src/**/*.ts` for `@RegisterClass` decorators using the TypeScript Compiler API
-3. Generates a manifest file with `import` statements for every package that contains registered classes
+```graphql
+input CreateEmployeeInput {
+  # Parent fields (from Person)
+  firstName: String!
+  lastName: String!
+  dateOfBirth: Date
+
+  # Child fields (from Employee)
+  employeeNumber: String!
+  hireDate: Date!
+  salary: Decimal!
+}
+```
 
-**Per-app results (verified):**
+This provides a convenient single-operation API while the resolver handles the underlying two-step creation.
 
-| App | Deps Walked | Packages with @RegisterClass | Total Classes |
-|-----|-------------|------------------------------|---------------|
-| MJAPI | 985 | 54 | 715 |
-| MJExplorer | 1179 | 17 | 721 |
+#### 4. TypeScript Entity Classes - JSDoc Annotations
+**Generated entity classes include JSDoc annotations** on getter/setter methods to indicate IS-A relationships:
 
-**Programmatic usage:**
 ```typescript
-import { generateClassRegistrationsManifest } from '@memberjunction/codegen-lib';
+export class EmployeeEntity extends BaseEntity {
+  /**
+   * Inherited from Person entity
+   */
+  get FirstName(): string {
+    return this.Get('FirstName');
+  }
 
-const result = await generateClassRegistrationsManifest({
-    outputPath: './src/generated/class-registrations-manifest.ts',
-    appDir: './packages/MJAPI',  // defaults to process.cwd()
-    filterBaseClasses: ['BaseEngine'],  // optional filter
-});
+  set FirstName(value: string) {
+    this.Set('FirstName', value);
+  }
 
-if (result.success) {
-    console.log(`${result.packages.length} packages, ${result.classes.length} classes`);
+  // Own fields have no annotation
+  get EmployeeNumber(): string {
+    return this.Get('EmployeeNumber');
+  }
 }
 ```
 
-**CLI usage (via MJCLI):**
-```bash
-mj codegen manifest --output ./src/generated/class-registrations-manifest.ts
-```
-
-See the [MJCLI README](../MJCLI/README.md) for full CLI documentation.
-
-**Pre-built manifests for npm distribution:**
+#### 5. EntityField Metadata Synchronization
+**`manageEntityFields()` respects IS-A hierarchy** when syncing field metadata:
 
-When MJ packages are installed via npm, consumers only receive `dist/` (no `src/`), so the manifest generator can't scan them. To solve this, MJ ships **pre-built manifests** inside the bootstrap packages:
+- Fields from parent entities are NOT duplicated in child entity metadata
+- Only the child's own fields appear in `EntityField` for the child entity
+- `RelatedEntityID` and field relationships are preserved across the hierarchy
+- Prevents metadata pollution from inherited fields
 
-- `@memberjunction/server-bootstrap` — 623 server-side classes from 54 packages
-- `@memberjunction/ng-bootstrap` — 383 Angular classes from 14 packages
+### Configuration in Database Metadata
 
-External consumers import the pre-built manifest for MJ classes, then generate a supplemental manifest for their own classes using `--exclude-packages @memberjunction`.
+IS-A relationships are defined in the `Entity` table:
 
-For complete setup instructions, CLI reference, and troubleshooting, see the **[Class Manifest Guide](CLASS_MANIFEST_GUIDE.md)**.
+```sql
+-- Person is the base entity
+INSERT INTO Entity (ID, ParentEntity, Name)
+VALUES (NEWID(), NULL, 'Person')
 
-**Example output:**
-- [MJAPI manifest (server-side)](EXAMPLE_MANIFEST_MJAPI.md) — 54 packages, 715 classes (AI providers, actions, encryption, scheduling, storage, etc.)
-- [MJExplorer manifest (client-side)](EXAMPLE_MANIFEST_MJEXPLORER.md) — 17 packages, 721 classes (Angular components, dashboards, forms, etc.)
+-- Employee IS-A Person
+INSERT INTO Entity (ID, ParentEntity, Name)
+VALUES (NEWID(), 'Person', 'Employee')
+```
 
-## API Reference
+CodeGen detects the `ParentEntity` relationship and applies the specialized generation logic automatically.
 
-### Core Functions
+### Use Cases for IS-A Relationships
 
-```typescript
-// Generate everything at once
-await runCodeGen();
+Common scenarios where IS-A relationships improve your schema:
 
-// Generate specific components
-await generateEntitySubClasses(options);
-await generateAngularEntityCode(options);
-await generateSQLScripts(options);
-await generateGraphQLServerCode(options);
-```
+- **Person → Employee, Customer, Vendor** - Shared contact information with role-specific fields
+- **Document → Invoice, PurchaseOrder, Contract** - Common document metadata with type-specific data
+- **Product → PhysicalProduct, DigitalProduct** - Shared catalog info with delivery-specific fields
+- **Communication → Email, SMS, PhoneCall** - Common tracking with channel-specific metadata
 
-### Entity Subclass Generation
+### Best Practices
 
-```typescript
-import { generateEntitySubClasses } from '@memberjunction/codegen-lib';
-
-const result = await generateEntitySubClasses({
-  outputDirectory: './generated/entities',
-  generateLoader: true,
-  generateCustomEntityClasses: true,
-  aiEnhanced: true,           // Enable AI features
-  incrementalMode: true,      // Only update changed entities
-  validateGenerated: true     // Compile-check generated code
-});
-```
+1. **Keep hierarchies shallow** - One or two levels is ideal (Person → Employee, not Person → Worker → Employee)
+2. **Parent entities should be meaningful** - Don't create artificial base classes just for inheritance
+3. **Child fields should be truly specific** - If a field applies to all children, put it in the parent
+4. **ID management is manual** - When creating child records, explicitly use the parent's ID
 
-### Action Subclass Generation
+## Virtual Entity Support
 
-```typescript
-import { generateActionSubClasses } from '@memberjunction/codegen-lib';
+MemberJunction supports **virtual entities** - entities backed by database views instead of tables. Virtual entities enable read-only access to complex queries, external data sources, or denormalized views while maintaining the full MemberJunction metadata and API experience.
 
-const result = await generateActionSubClasses({
-  outputDirectory: './generated/actions',
-  generateLoader: true
-});
-```
+For comprehensive conceptual documentation, see the **[Virtual Entities Guide](../../MJCore/docs/virtual-entities.md)** in MJCore.
 
-### GraphQL Server Generation
+### Configuration-Driven Virtual Entity Creation
 
-```typescript
-import { generateGraphQLServerCode } from '@memberjunction/codegen-lib';
+Virtual entities are defined in `database-metadata-config.json` under the `VirtualEntities` array:
 
-await generateGraphQLServerCode({
-  outputDirectory: './generated/graphql',
-  entities: entityMetadata
-});
+```json
+{
+  "VirtualEntities": [
+    {
+      "ViewName": "vwSalesSummary",
+      "EntityName": "Sales Summary",
+      "SchemaName": "__mj",
+      "Description": "Aggregated sales data by region and period",
+      "PrimaryKey": ["SummaryID"],
+      "ForeignKeys": [
+        {
+          "FieldName": "RegionID",
+          "SchemaName": "__mj",
+          "RelatedTable": "Region",
+          "RelatedField": "ID",
+          "Description": "FK to Region table"
+        }
+      ]
+    }
+  ]
+}
 ```
 
-### SQL Code Generation
+#### Key Configuration Properties
 
-```typescript
-import { generateSQLScripts } from '@memberjunction/codegen-lib';
+- **`ViewName`**: The SQL view name (must already exist in the database)
+- **`EntityName`**: The MemberJunction entity name (appears in metadata, UI, APIs)
+- **`SchemaName`**: Database schema (typically `__mj` for core entities)
+- **`Description`**: Entity description for metadata and documentation
+- **`PrimaryKey`**: Array of column names forming the primary key (supports composite keys)
+- **`ForeignKeys`**: Optional array of foreign key relationships to other entities (if omitted, LLM decoration discovers them)
 
-await generateSQLScripts({
-  outputDirectory: './generated/sql',
-  includeStoredProcedures: true,
-  includeViews: true
-});
-```
+### CodeGen Pipeline for Virtual Entities
 
-### Angular Component Generation
+CodeGen processes virtual entities through several specialized steps:
 
-```typescript
-import { generateAllAngularEntityCode } from '@memberjunction/codegen-lib';
+#### 1. `processVirtualEntityConfig()` - Entity Creation
+Reads the `VirtualEntities` configuration and calls `spCreateVirtualEntity` for each entry:
 
-await generateAllAngularEntityCode({
-  outputDirectory: './generated/angular',
-  entities: entityMetadata
-});
+```typescript
+// CodeGen calls this stored procedure for each virtual entity
+EXEC spCreateVirtualEntity
+    @Name = 'Sales Summary',
+    @SchemaName = '__mj',
+    @BaseView = 'vwSalesSummary',
+    @Description = 'Aggregated sales data...',
+    @PrimaryKeyColumnName = 'SummaryID'
 ```
 
-## Performance Stats
-
-On a typical MemberJunction database with **150+ tables**:
+This creates the `Entity` metadata record with `VirtualEntity = 1`.
 
-- **Entity Generation**: 2.3 seconds
-- **Angular Components**: 4.7 seconds  
-- **SQL Procedures**: 1.8 seconds
-- **Total Stack Generation**: **<10 seconds**
+#### 2. `manageVirtualEntities()` - Field Synchronization
+Scans `sys.columns` on the virtual entity's view and creates `EntityField` metadata for each column:
 
-For **295 entity classes** and **thousands of generated files**.
+- Automatically detects data types, nullability, and max lengths
+- Creates `EntityField` records for all view columns
+- Updates existing fields if column definitions change
+- Marks fields as `IsVirtual = 1` in metadata
 
-## Integration with MemberJunction Ecosystem
-
-Works seamlessly with:
+```typescript
+// CodeGen inspects the view schema
+SELECT
+    c.name,
+    t.name AS TypeName,
+    c.max_length,
+    c.is_nullable
+FROM
+    sys.columns c
+INNER JOIN
+    sys.types t ON c.user_type_id = t.user_type_id
+WHERE
+    object_id = OBJECT_ID('__mj.vwSalesSummary')
+```
 
-- `@memberjunction/core` - Entity framework
-- `@memberjunction/ai` - AI-powered features  
-- `@memberjunction/angular-explorer` - UI framework
-- `@memberjunction/graphql-dataprovider` - API layer
-- `@memberjunction/sqlserver-dataprovider` - Data access
+#### 3. `applySoftPKFKConfig()` - Explicit Relationship Overrides
+Applies the `primaryKeyColumnName` and `foreignKeyDefinitions` from the config:
 
-## Advanced Features
+```typescript
+// Sets the primary key field
+UPDATE EntityField
+SET IsPrimaryKey = 1
+WHERE EntityID = @VirtualEntityID
+  AND Name = 'SummaryID'
+
+// Creates foreign key relationships
+INSERT INTO EntityRelationship (...)
+SELECT ... FROM foreignKeyDefinitions
+```
 
-### Custom Templates
+**Why explicit FK definitions?** Views don't have database-level foreign keys, so CodeGen can't detect relationships automatically. The config provides this metadata.
 
-You can provide custom templates for code generation:
+#### 4. LLM-Assisted Field Decoration (Advanced Feature)
+The **`decorateVirtualEntitiesWithLLM()`** pipeline step uses AI to enhance virtual entity field metadata:
 
 ```typescript
-import { setCustomTemplate } from '@memberjunction/codegen-lib';
-
-setCustomTemplate('entity', myCustomEntityTemplate);
+import { AIPromptRunner } from '@memberjunction/ai-prompts';
+
+// CodeGen calls a database-driven prompt to decorate fields
+const promptParams = new AIPromptParams();
+promptParams.prompt = 'Decorate Virtual Entity Fields';
+promptParams.data = {
+    entityName: 'Sales Summary',
+    viewDefinition: viewSQL,
+    existingFields: fieldsFromMetadata
+};
+
+const runner = new AIPromptRunner();
+const result = await runner.ExecutePrompt(promptParams);
 ```
 
-### Schema Analysis
+The LLM analyzes the view definition and provides:
+- **Display names** - User-friendly field labels (e.g., `TotalRevenue` → "Total Revenue")
+- **Descriptions** - Field-level documentation explaining what each column represents
+- **Category assignments** - Semantic grouping for form layouts
+- **DefaultInView flags** - Recommended visibility settings for grid displays
 
-```typescript
-import { analyzeSchema } from '@memberjunction/codegen-lib';
+This is controlled by the `VirtualEntityFieldDecoration` feature in the Advanced Generation Features configuration.
 
-const schemaInfo = await analyzeSchema(databaseConnection);
-// Work with schema information
-```
+### Virtual Entity Metadata Structure
 
-### Progress Tracking
+After CodeGen processing, virtual entities have complete metadata:
 
-```typescript
-import { onProgress } from '@memberjunction/codegen-lib';
+```sql
+-- Entity record
+SELECT * FROM Entity WHERE Name = 'Sales Summary'
+-- VirtualEntity = 1, BaseView = 'vwSalesSummary'
 
-onProgress((status) => {
-  console.log(`Progress: ${status.message} (${status.percentage}%)`);
-});
+-- EntityField records (auto-detected from view)
+SELECT * FROM EntityField WHERE EntityID = @SalesEntityID
+-- Name, Type, Description, IsVirtual = 1
+
+-- EntityRelationship records (from config)
+SELECT * FROM EntityRelationship WHERE EntityID = @SalesEntityID
+-- Foreign keys defined in foreignKeyDefinitions
 ```
 
-### Force Regeneration with Smart Filtering
+### Generated Code for Virtual Entities
 
-Need to regenerate specific SQL objects without schema changes? Our force regeneration feature gives you **surgical precision** over what gets regenerated:
+Virtual entities generate the same TypeScript, GraphQL, and Angular code as table-based entities:
 
-```javascript
-// In mj.config.cjs
-forceRegeneration: {
-  enabled: true,
-  // Filter to specific entities using SQL WHERE clause
-  entityWhereClause: "SchemaName = 'CRM' AND __mj_UpdatedAt >= '2025-06-24'",
-  
-  // Granular control over what gets regenerated
-  baseViews: true,      // Regenerate base views
-  spCreate: false,      // Skip create procedures
-  spUpdate: true,       // Regenerate update procedures
-  spDelete: false,      // Skip delete procedures
-  indexes: true,        // Regenerate foreign key indexes
-  fullTextSearch: false // Skip full-text search components
-}
-```
+**TypeScript Entity Class:**
+```typescript
+export class SalesSummaryEntity extends BaseEntity {
+  get SummaryID(): string {
+    return this.Get('SummaryID');
+  }
 
-#### Common Scenarios:
+  get RegionID(): string {
+    return this.Get('RegionID');
+  }
 
-**Regenerate views for recently modified entities:**
-```javascript
-forceRegeneration: {
-  enabled: true,
-  entityWhereClause: "__mj_UpdatedAt >= '2025-06-24 22:00:00'",
-  baseViews: true
-}
-```
+  get TotalRevenue(): number {
+    return this.Get('TotalRevenue');
+  }
 
-**Regenerate all stored procedures for a specific schema:**
-```javascript
-forceRegeneration: {
-  enabled: true,
-  entityWhereClause: "SchemaName = 'Sales'",
-  allStoredProcedures: true
+  // Save/Delete methods throw errors (read-only entity)
 }
 ```
 
-**Regenerate specific SQL object for a single entity:**
-```javascript
-forceRegeneration: {
-  enabled: true,
-  entityWhereClause: "Name = 'Customer'",
-  spUpdate: true  // Just regenerate the update procedure
+**GraphQL Schema:**
+```graphql
+type SalesSummary {
+  summaryID: ID!
+  regionID: ID!
+  region: Region    # Auto-resolved from FK definition
+  totalRevenue: Float!
 }
-```
 
-**Regenerate everything (no filtering):**
-```javascript
-forceRegeneration: {
-  enabled: true,
-  // No entityWhereClause = regenerate for ALL entities
-  allStoredProcedures: true,
-  baseViews: true,
-  indexes: true
+type Query {
+  SalesSummaries(filter: String): [SalesSummary!]!
 }
 ```
 
-#### How It Works:
-1. **Entity Filtering**: The `entityWhereClause` runs against the Entity metadata table to select which entities qualify
-2. **Type Filtering**: Individual flags control which SQL object types get regenerated
-3. **Smart Combination**: Only regenerates the intersection (selected entities AND selected types)
-4. **Error Handling**: Invalid WHERE clauses stop execution with clear error messages
+**Angular Form:**
+```html
+<mj-form-field
+    [record]="record"
+    FieldName="TotalRevenue"
+    Type="textbox"
+    [ReadOnly]="true"  <!-- Virtual entities are read-only -->
+></mj-form-field>
+```
 
-## Error Handling
+### Virtual Entity Limitations
 
-The library provides comprehensive error handling:
+Virtual entities are **read-only** by design:
 
-```typescript
-try {
-  await runCodeGen();
-} catch (error) {
-  if (error.code === 'CONFIG_NOT_FOUND') {
-    // Handle missing configuration
-  } else if (error.code === 'DB_CONNECTION_FAILED') {
-    // Handle database connection errors
-  }
-}
-```
+- No `spCreate`, `spUpdate`, or `spDelete` procedures generated
+- `AllowCreateAPI`, `AllowUpdateAPI`, `AllowDeleteAPI` set to `0` in metadata
+- Entity class `Save()` and `Delete()` methods throw errors
+- GraphQL mutations not generated for virtual entities
+- Angular forms display in read-only mode
 
-## Why This Changes Everything
+### Advanced Generation Features Configuration
 
-**Before MemberJunction CodeGen:**
-- Weeks of manual entity creation
-- Inconsistent validation logic
-- Type mismatches between layers
-- Manual Angular form creation
-- Brittle SQL procedures
-- Schema changes break everything
+Virtual entity LLM decoration is controlled in the `advancedGeneration.features` array in `mj.config.cjs`:
 
-**After MemberJunction CodeGen:**
-- **10 seconds** to regenerate entire stack
-- **Perfect type safety** across all layers
-- **AI-powered** intelligent code generation
-- **Zero manual intervention**
-- **Production-ready** from day one
+```javascript
+advancedGeneration: {
+    enableAdvancedGeneration: true,
+    features: [
+        {
+            name: 'VirtualEntityFieldDecoration',
+            enabled: true,
+            // Optional: force re-decoration even if entities already have soft PK/FK annotations
+            options: [{ name: 'forceRegenerate', value: true }],
+        },
+    ],
+},
+```
 
-## Best Practices
+By default, `VirtualEntityFieldDecoration` is **enabled** and uses an idempotency check — entities that already have `IsSoftPrimaryKey` or `IsSoftForeignKey` annotations are skipped. Set the `forceRegenerate` option to `true` to override this check and re-run LLM decoration for all virtual entities (useful after prompt improvements or when you want to refresh metadata).
 
-1. **Configuration Management** - Use environment-specific configuration files
-2. **Output Organization** - Keep generated code in separate directories
-3. **Version Control** - Consider excluding generated files from version control
-4. **Regular Updates** - Regenerate code when metadata changes
-5. **Custom Extensions** - Extend generated classes rather than modifying them
+When active, CodeGen calls `decorateVirtualEntitiesWithLLM()` after field synchronization.
 
-## Contributing
+### Use Cases for Virtual Entities
 
-When contributing to this package:
+Virtual entities excel at:
 
-1. **Test with real schemas** - We generate production apps
-2. **Maintain AI accuracy** - Constraint translation must be perfect
-3. **Performance matters** - Large schemas must generate quickly
-4. **Type safety is sacred** - Never compromise type correctness
+- **Reporting and Analytics** - Pre-aggregated views for dashboards (sales summaries, usage metrics)
+- **External Data Sources** - Linked server views, API-backed views, federated queries
+- **Denormalized Views** - Flattened data for grid displays without JOIN overhead
+- **Legacy System Integration** - Expose legacy tables through normalized MJ entity layer
+- **Calculated Fields** - Complex computed columns not suitable for table storage
+- **Security Views** - Row-level security via filtered views with full MJ API access
 
-## License
+### Best Practices
 
-This package is part of the MemberJunction ecosystem and follows the same licensing terms.
+1. **View must exist first** - Create the SQL view before running CodeGen with virtual entity config
+2. **Primary key is required** - Views must have a unique identifier column
+3. **Use meaningful names** - `entityName` appears throughout UI and APIs
+4. **Document foreign keys** - Explicit FK definitions enable relationship navigation
+5. **Enable LLM decoration** - Let AI generate field descriptions for better UX
+6. **Keep views simple** - Complex views with subqueries may have performance issues
+7. **Test read operations** - Verify grid displays and API queries perform acceptably
 
----
+## Contributing
 
-**Ready to experience the future of application development?**
+See the [MemberJunction Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.
 
-```bash
-npm install @memberjunction/codegen-lib
-```
+When contributing to CodeGenLib:
 
-Your database schema deserves better than manual code generation. Give it the AI-powered, production-ready, full-stack treatment it deserves.
+1. All generator base classes use the class factory pattern -- always subclass and register rather than modifying base classes directly
+2. Generated SQL must be compatible with SQL Server and produce valid Flyway migration output
+3. Generated TypeScript must compile without errors and follow MJ naming conventions (PascalCase public members)
+4. AI-powered features must enforce stability guarantees (existing categories and icons are never changed)