@memberjunction/core-entities 3.4.0 → 4.1.0

package/readme.md

@@ -1,16 +1,8 @@
 # @memberjunction/core-entities
 
-A comprehensive library of strongly-typed entity classes for MemberJunction's core metadata schema. This package provides type-safe access to all MemberJunction system entities with built-in validation, custom business logic, and seamless integration with the MemberJunction framework.
+Strongly-typed entity classes, singleton engine caches, and domain logic for every entity in MemberJunction's core metadata schema. This package is the primary data-access layer that all MJ applications -- server and client -- depend on to interact with the MJ data model in a type-safe, validated way.
 
-## Overview
-
-The `@memberjunction/core-entities` package contains:
-- **178+ Generated Entity Classes**: Strongly-typed TypeScript classes for all core MemberJunction entities
-- **Extended Entity Classes**: Custom subclasses with specialized business logic
-- **Artifact Extraction System**: Metadata-driven attribute extraction with hierarchical inheritance
-- **Resource Permission Engine**: Comprehensive permission management system
-- **Zod Schema Validation**: Built-in runtime validation for all entity types
-- **Type Definitions**: Full TypeScript type definitions for enhanced IDE support
+All entity subclasses in this package are **auto-generated by CodeGen**. Manual edits to files under `src/generated/` will be overwritten. Custom business logic is layered on top via extended classes in `src/custom/`.
 
 ## Installation
 
@@ -18,180 +10,476 @@ The `@memberjunction/core-entities` package contains:
 npm install @memberjunction/core-entities
 ```
 
+## Overview
+
+The package is structured into four layers that build on each other:
+
+```mermaid
+flowchart TD
+    subgraph Generated["Generated Layer (CodeGen)"]
+        ZOD["Zod Schemas<br/>Runtime validation"]
+        ENT["272 Entity Subclasses<br/>Typed getters/setters"]
+    end
+
+    subgraph Custom["Custom Layer (Hand-Written)"]
+        EXT["Extended Entities<br/>Business logic overrides"]
+        RPE["Resource Permissions<br/>Access control"]
+    end
+
+    subgraph Engines["Engine Layer (Singletons)"]
+        UIE["UserInfoEngine"]
+        UVE["UserViewEngine"]
+        DE["DashboardEngine"]
+        CME["ComponentMetadataEngine"]
+        AME["ArtifactMetadataEngine"]
+        FE["FileStorageEngine"]
+        EE["EncryptionEngineBase"]
+        ME["MCPEngine"]
+        TTC["TypeTablesCache"]
+    end
+
+    subgraph Extraction["Artifact Extraction"]
+        AER["Extract Rules<br/>Type definitions"]
+        AEX["ArtifactExtractor<br/>Rule resolution + execution"]
+    end
+
+    ENT --> EXT
+    ZOD --> ENT
+    EXT --> Engines
+    ENT --> Engines
+    AER --> AEX
+
+    style Generated fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Custom fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style Engines fill:#7c5295,stroke:#563a6b,color:#fff
+    style Extraction fill:#b8762f,stroke:#8a5722,color:#fff
+```
+
+### Generated Entity Classes
+
+CodeGen scans the MemberJunction database schema and produces:
+
+- **Zod schema objects** for every entity, providing runtime validation with field-level descriptions, related-entity annotations, and value-list constraints.
+- **Entity subclasses** extending `BaseEntity<T>` with strongly-typed getter/setter properties for every column, typed `Load()` methods, and JSDoc annotations including SQL types, defaults, and foreign key references.
+
+There are currently **272 generated entity classes** covering approximately 78,000 lines of code in a single `entity_subclasses.ts` file.
+
+### Extended Entity Classes
+
+Several entities require custom business logic beyond what CodeGen can generate. Extended classes use `@RegisterClass` to override the generated base class in MJ's class factory:
+
+| Extended Class | Entity Name | Purpose |
+|---|---|---|
+| `UserViewEntityExtended` | User Views | Filter/column JSON parsing, WHERE clause generation, smart filter AI stub, permission checks |
+| `DashboardEntityExtended` | Dashboards | Default config initialization, permission-based validation on save/delete |
+| `EntityEntityExtended` | Entities | Auto-sets `AutoUpdateDescription` when description is manually changed |
+| `EntityFieldEntityExtended` | Entity Fields | Prevents modification of database-reflected properties, auto-sets `AutoUpdateDescription` |
+| `ComponentEntityExtended` | MJ: Components | Syncs derived fields from Specification JSON, keeps `spec` property in sync |
+| `TemplateEntityExtended` | Templates | Content/param management, template input validation |
+| `ScheduledActionEntityExtended` | Scheduled Actions | Auto-generates CronExpression from schedule type settings |
+| `ListDetailEntityExtended` | List Details | Composite key handling, duplicate detection on save |
+| `EnvironmentEntityExtended` | MJ: Environments | Exposes static `DefaultEnvironmentID` constant |
+| `ResourcePermissionEntityExtended` | Resource Permissions | Notification workflow on permission request/approval |
+
+### Singleton Engines
+
+Engine classes extend `BaseEngine<T>` to provide cached, singleton access to groups of related entities. They load data once and keep it in memory, with auto-refresh when underlying data changes.
+
+```mermaid
+flowchart LR
+    subgraph App["Application Code"]
+        SVC["Services / Components"]
+    end
+
+    subgraph Engines["Singleton Engines"]
+        UIE["UserInfoEngine"]
+        DE["DashboardEngine"]
+        RPE["ResourcePermissionEngine"]
+    end
+
+    subgraph DB["Database"]
+        MJD["MJ Schema"]
+    end
+
+    SVC -->|".Instance"| Engines
+    Engines -->|"Config() loads once"| DB
+    Engines -->|"Cached data"| SVC
+
+    style App fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Engines fill:#7c5295,stroke:#563a6b,color:#fff
+    style DB fill:#64748b,stroke:#475569,color:#fff
+```
+
+### Artifact Extraction System
+
+A metadata-driven system for extracting structured attributes from artifact content using declarative JavaScript-based rules with hierarchical inheritance through parent artifact types.
+
 ## Key Features
 
-### 1. Strongly-Typed Entity Classes
-Every MemberJunction core entity has a corresponding TypeScript class with:
-- Full type safety for all properties
-- Automatic validation using Zod schemas
-- Relationship navigation properties
-- Built-in CRUD operations
-
-### 2. Extended Entity Classes
-Several entities have custom extended classes that provide additional functionality:
-
-- **UserViewEntityExtended**: Enhanced view management with filter and column parsing
-- **DashboardEntityExtended**: Dashboard configuration management
-- **AIModelEntityExtended**: AI model utilities and helpers
-- **AIPromptEntityExtended**: Prompt management functionality
-- **ArtifactVersionExtended**: Automatic content hashing and attribute extraction
-- **ListDetailEntityExtended**: List view enhancements
-- **ScheduledActionExtended**: Scheduled task management
-- **ResourcePermissionEntity**: Resource access control
-
-### 3. Artifact Extraction System
-A powerful metadata-driven system for extracting structured attributes from artifact content:
-- Hierarchical extract rule inheritance
-- Declarative JavaScript-based extractors
-- Automatic SHA-256 content hashing
-- Standard property mappings for UI rendering
-- Type-safe attribute storage and retrieval
-
-### 4. Resource Permission Engine
-A sophisticated permission system for managing access to various resources:
-- Role-based permissions
-- Resource type definitions
-- Permission inheritance
-- Cached permission lookups
+- **272 strongly-typed entity classes** covering all MemberJunction core schema entities
+- **Zod runtime validation** with field-level constraints and value list enums
+- **Extended entity classes** with permission checks, workflow logic, and JSON state parsing
+- **9 singleton engine caches** eliminating redundant database queries
+- **Resource permission engine** with role-based access control (View/Edit/Owner levels)
+- **Dashboard permission engine** with owner/direct/category permission hierarchy
+- **User view engine** with filter-to-SQL conversion and smart filter AI support
+- **Artifact extraction** with hierarchical rule inheritance and sandboxed execution
+- **Encryption engine base** for field-level encryption metadata caching
 
 ## Usage
 
-### Basic Entity Usage
+### Working with Entity Objects
+
+Always use `Metadata.GetEntityObject<T>()` to create entity instances -- never instantiate entity classes directly. This ensures the MJ class factory resolves the correct (potentially extended) subclass.
 
 ```typescript
 import { Metadata } from '@memberjunction/core';
 import { UserEntity, ApplicationEntity } from '@memberjunction/core-entities';
 
-// Always use Metadata to create entity instances
 const md = new Metadata();
 
-// Load a user by ID
+// Load an existing record
 const user = await md.GetEntityObject<UserEntity>('Users');
-await user.Load('user-id-here');
-
-// Access strongly-typed properties
+await user.Load('some-user-id');
 console.log(user.Email);
 console.log(user.FirstName);
 
-// Create a new application
+// Create a new record
 const app = await md.GetEntityObject<ApplicationEntity>('Applications');
 app.NewRecord();
-app.Name = 'My New Application';
-app.Description = 'A test application';
+app.Name = 'My Application';
+app.Description = 'A custom application';
 await app.Save();
 ```
 
-(continuing in next command due to size...)
-
-## Artifact Extraction System
-
-The artifact extraction system enables declarative extraction of structured attributes from artifact content with hierarchical inheritance.
-
-### Overview
-
-Artifacts in MemberJunction can have **extract rules** defined in their `ArtifactType` that specify how to extract attributes from the artifact content. These rules:
-- Are stored as JSON in the `ArtifactType.ExtractRules` column
-- Support hierarchical inheritance (child types inherit and override parent rules)
-- Execute JavaScript code in a controlled environment
-- Map extracted values to standard properties (name, description, display formats)
-- Are automatically executed when artifact versions are saved
-
-### Defining Extract Rules
-
-Extract rules are defined in the `ArtifactType.ExtractRules` JSON field:
-
-```json
-[
-  {
-    "name": "subject",
-    "description": "Email subject line",
-    "type": "string",
-    "standardProperty": "name",
-    "extractor": "const parsed = JSON.parse(content); return parsed.subject || 'Untitled';"
-  },
-  {
-    "name": "recipientCount",
-    "description": "Number of recipients",
-    "type": "number",
-    "extractor": "const parsed = JSON.parse(content); return parsed.recipients?.length || 0;"
-  }
-]
+### Loading Collections with RunView
+
+Use `RunView` with generics for loading collections of entity records:
+
+```typescript
+import { RunView } from '@memberjunction/core';
+import { ActionEntity } from '@memberjunction/core-entities';
+
+const rv = new RunView();
+const result = await rv.RunView<ActionEntity>({
+    EntityName: 'Actions',
+    ExtraFilter: `Status='Active'`,
+    OrderBy: 'Name',
+    ResultType: 'entity_object'
+});
+
+if (result.Success) {
+    for (const action of result.Results) {
+        console.log(action.Name, action.Status);
+    }
+}
 ```
 
-### Extract Rule Properties
+### Using the UserViewEntityExtended
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | string | Unique identifier for this rule |
-| `description` | string | Human-readable description |
-| `type` | string | TypeScript type (e.g., `'string'`, `'Array<{x: number}>'`) |
-| `standardProperty` | string? | Maps to: `'name'`, `'description'`, `'displayMarkdown'`, `'displayHtml'` |
-| `extractor` | string | JavaScript code that receives `content` and returns value |
+The extended User View entity parses JSON state columns into structured objects and generates SQL WHERE clauses:
 
-### Using the ArtifactExtractor
+```typescript
+import { Metadata } from '@memberjunction/core';
+import { UserViewEntityExtended, ViewInfo } from '@memberjunction/core-entities';
+
+// Load a view by name using the convenience class
+const view = await ViewInfo.GetViewEntityByName('Active Contacts');
+
+// Access parsed column and filter info
+const columns = view.Columns;       // ViewColumnInfo[]
+const filters = view.Filter;        // ViewFilterInfo[]
+const sortInfo = view.ViewSortInfo;  // ViewSortInfo[]
+
+// Check user permissions
+if (view.UserCanEdit) {
+    view.Name = 'Updated View Name';
+    await view.Save(); // Auto-regenerates WhereClause from FilterState
+}
+```
+
+### Using Singleton Engines
+
+All engines follow the same pattern: get the singleton instance, call `Config()` to load data, then access cached properties.
+
+```typescript
+import {
+    UserInfoEngine,
+    DashboardEngine,
+    ResourcePermissionEngine
+} from '@memberjunction/core-entities';
+
+// UserInfoEngine -- notifications, favorites, settings, applications
+const userEngine = UserInfoEngine.Instance;
+await userEngine.Config(false, contextUser);
+const notifications = userEngine.UnreadNotifications;
+const favorites = userEngine.UserFavorites;
+
+// Debounced settings (batches rapid updates)
+userEngine.SetSettingDebounced('ui-preference/theme', 'dark');
+
+// DashboardEngine -- dashboards, categories, permissions
+const dashEngine = DashboardEngine.Instance;
+await dashEngine.Config(false, contextUser);
+const accessible = dashEngine.GetAccessibleDashboards(userId);
+const canEdit = dashEngine.CanUserEditDashboard(dashboardId, userId);
+
+// ResourcePermissionEngine -- role-based resource access
+const permEngine = ResourcePermissionEngine.Instance;
+await permEngine.Config(false, contextUser);
+const level = permEngine.GetUserResourcePermissionLevel(resourceTypeId, recordId, user);
+// Returns 'View' | 'Edit' | 'Owner' | null
+```
+
+### Artifact Extraction
+
+Extract structured attributes from artifact content using declarative rules:
 
 ```typescript
 import { ArtifactExtractor } from '@memberjunction/core-entities';
 
-// Resolve extract rules with inheritance
-const rules = ArtifactExtractor.ResolveExtractRules(artifactTypeChain);
+// Resolve extract rules with inheritance from parent types
+const rules = ArtifactExtractor.ResolveExtractRules([
+    childArtifactType,   // Most specific (overrides parent rules by name)
+    parentArtifactType   // Least specific
+]);
 
 // Extract attributes from content
 const result = await ArtifactExtractor.ExtractAttributes({
-    content: artifactContent,
+    content: '{"subject": "Q4 Campaign", "body": "..."}',
     extractRules: rules,
     throwOnError: false,
     timeout: 5000
 });
 
-// Get standard properties
+// Access extracted values
 const name = ArtifactExtractor.GetStandardProperty(result.attributes, 'name');
 const description = ArtifactExtractor.GetStandardProperty(result.attributes, 'description');
+
+// Serialize for database storage
+const serialized = ArtifactExtractor.SerializeForStorage(result.attributes);
 ```
 
-### Automatic Extraction with ArtifactVersionExtended
+### Encryption Metadata
+
+The `EncryptionEngineBase` provides cached access to encryption keys, algorithms, and key sources:
 
 ```typescript
-import { ArtifactVersionExtended } from '@memberjunction/core-entities';
-import { Metadata } from '@memberjunction/core';
+import { EncryptionEngineBase } from '@memberjunction/core-entities';
 
-const md = new Metadata();
-const version = await md.GetEntityObject<ArtifactVersionExtended>('MJ: Artifact Versions');
-version.NewRecord();
-version.Content = JSON.stringify({ subject: "Q4 Campaign", body: "..." });
-
-// Save triggers automatic extraction:
-// 1. Calculates SHA-256 hash → ContentHash
-// 2. Resolves extract rules from ArtifactType hierarchy
-// 3. Extracts attributes → Name and Description
-// 4. Creates ArtifactVersionAttribute records
-await version.Save();
-
-console.log(version.Name); // "Q4 Campaign" (extracted)
-console.log(version.ContentHash); // "a3f7e2..." (SHA-256)
+const engine = EncryptionEngineBase.Instance;
+await engine.Config(false, contextUser);
+
+// Validate a key is usable
+const validation = engine.ValidateKey(keyId);
+if (!validation.isValid) {
+    console.error(validation.error);
+}
+
+// Get full key configuration (key + algorithm + source)
+const config = engine.GetKeyConfiguration(keyId);
+```
+
+## API Reference
+
+### Generated Entity Classes
+
+Every generated entity class provides:
+
+| Member | Description |
+|---|---|
+| `Load(ID, relationships?)` | Load a record by primary key |
+| `Save(options?)` | Persist changes to the database |
+| `Delete(options?)` | Delete the record |
+| `NewRecord()` | Initialize a blank record for creation |
+| `Validate()` | Run Zod schema validation |
+| Typed getters/setters | One per database column, with JSDoc annotations |
+
+### UserViewEntityExtended
+
+| Member | Type | Description |
+|---|---|---|
+| `Filter` | `ViewFilterInfo[]` | Parsed filter state from JSON |
+| `Columns` | `ViewColumnInfo[]` | Parsed column configuration from JSON |
+| `ViewSortInfo` | `ViewSortInfo[]` | Parsed sort state |
+| `OrderByClause` | `string` | SQL ORDER BY clause |
+| `ViewEntityInfo` | `EntityInfo` | Metadata for the view's entity |
+| `ParsedDisplayState` | `ViewDisplayState \| null` | View mode and display preferences |
+| `UserCanEdit` | `boolean` | Whether current user can edit this view |
+| `UserCanView` | `boolean` | Whether current user can view this view |
+| `UserCanDelete` | `boolean` | Whether current user can delete this view |
+| `SetDefaultsFromEntity(e)` | method | Initialize columns from entity metadata |
+| `UpdateWhereClause()` | method | Regenerate WHERE clause from filter state |
+
+### ViewInfo (Static Utility)
+
+| Method | Description |
+|---|---|
+| `GetViewsForUser(entityId?, contextUser?)` | Load all views for a user |
+| `GetViewID(viewName)` | Look up a view ID by name |
+| `GetViewEntity(viewId, contextUser?)` | Get a cached view by ID |
+| `GetViewEntityByName(viewName, contextUser?)` | Get a cached view by name |
+
+### UserInfoEngine
+
+| Member | Description |
+|---|---|
+| `UserNotifications` | Notifications for current user (newest first) |
+| `UnreadNotifications` | Unread notifications only |
+| `Workspaces` | User's workspaces |
+| `UserApplications` | Installed applications (sorted by sequence) |
+| `UserFavorites` | Favorited records (newest first) |
+| `UserRecordLogs` | Recent record access history |
+| `UserSettings` | User settings key-value pairs |
+| `GetSetting(key)` | Get a setting value by key |
+| `SetSetting(key, value)` | Create or update a setting |
+| `SetSettingDebounced(key, value)` | Debounced setting update for rapid UI changes |
+| `FlushPendingSettings()` | Force-save all debounced settings |
+| `InstallApplication(appId)` | Install an application for the user |
+| `DisableApplication(appId)` | Disable (but not delete) an application |
+| `CreateDefaultApplications()` | Create records for default-for-new-user apps |
+| `NotificationPreferences` | User's notification preferences |
+
+### DashboardEngine
+
+| Member | Description |
+|---|---|
+| `Dashboards` | All cached dashboards |
+| `DashboardCategories` | All dashboard categories |
+| `DashboardPartTypes` | Dashboard widget/part types |
+| `GetDashboardPermissions(id, userId)` | Get effective permissions (owner/direct/category) |
+| `CanUserReadDashboard(id, userId)` | Check read access |
+| `CanUserEditDashboard(id, userId)` | Check edit access |
+| `CanUserDeleteDashboard(id, userId)` | Check delete access |
+| `GetAccessibleDashboards(userId)` | All dashboards user can read |
+| `GetSharedDashboards(userId)` | Dashboards shared with user (not owned) |
+| `GetAccessibleCategories(userId)` | Categories user can access |
+
+### ResourcePermissionEngine
+
+| Member | Description |
+|---|---|
+| `ResourceTypes` | All resource type definitions |
+| `Permissions` | All resource permission records |
+| `GetResourcePermissions(typeId, recordId)` | Get all permissions for a resource |
+| `GetUserResourcePermissionLevel(typeId, recordId, user)` | Get highest permission level (View/Edit/Owner/null) |
+| `GetUserAvailableResources(user, typeId?)` | Get all resources a user can access |
+
+### UserViewEngine
+
+| Member | Description |
+|---|---|
+| `AllViews` | All cached views |
+| `GetViewById(id)` | Look up view by ID |
+| `GetViewByName(name)` | Look up view by name |
+| `GetViewsForEntity(entityId)` | Views for a specific entity |
+| `GetViewsForCurrentUser()` | Views owned by current user |
+| `GetAccessibleViewsForEntity(entityId)` | Owned + shared views with permission checks |
+| `GetDefaultViewForEntity(entityId)` | Default view for an entity |
+
+### ArtifactExtractor
+
+| Method | Description |
+|---|---|
+| `ResolveExtractRules(typeChain)` | Resolve rules with hierarchical inheritance |
+| `ExtractAttributes(config)` | Execute extraction rules against content |
+| `SerializeForStorage(attributes)` | Convert attributes to database-storable format |
+| `DeserializeFromStorage(stored)` | Convert stored attributes back to runtime objects |
+| `GetStandardProperty(attributes, prop)` | Find a standard property value (name/description/etc.) |
+
+### Other Engines
+
+| Engine | Purpose |
+|---|---|
+| `EncryptionEngineBase` | Caches encryption keys, algorithms, and key sources |
+| `FileStorageEngine` | Caches file storage accounts and providers |
+| `MCPEngine` | Caches MCP servers, connections, and tools |
+| `ComponentMetadataEngine` | Caches component definitions, libraries, and registries |
+| `ArtifactMetadataEngine` | Caches artifact type definitions |
+| `TypeTablesCache` | Caches entity relationship display components |
+
+## Permission Model
+
+The package implements a layered permission model used across views, dashboards, and resources:
+
+```mermaid
+flowchart TD
+    subgraph Check["Permission Resolution Order"]
+        direction TB
+        OWN["1. Ownership Check<br/>Record owner gets full access"]
+        ADM["2. Admin Check<br/>System admins get full access"]
+        DIR["3. Direct Permission<br/>User-specific grants"]
+        CAT["4. Category Permission<br/>Inherited from categories"]
+        ROL["5. Role Permission<br/>Granted through user roles"]
+    end
+
+    OWN -->|"Not owner"| ADM
+    ADM -->|"Not admin"| DIR
+    DIR -->|"No direct grant"| CAT
+    CAT -->|"No category grant"| ROL
+    ROL -->|"No role grant"| DENY["Access Denied"]
+
+    style Check fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style DENY fill:#64748b,stroke:#475569,color:#fff
 ```
 
-For complete documentation, see the [Implementation Summary](../../IMPLEMENTATION_SUMMARY_v2.105.md).
+Permission levels are hierarchical: **Owner** > **Edit** > **View**. The engine returns the highest applicable level across all sources (direct user grants and role-based grants).
+
+## View Filter Architecture
+
+The `UserViewEntityExtended` converts structured filter JSON into SQL WHERE clauses:
+
+```mermaid
+flowchart LR
+    subgraph Input["Filter State (JSON)"]
+        FS["{ logic: 'and',<br/>filters: [...] }"]
+    end
+
+    subgraph Process["UserViewEntityExtended"]
+        PARSE["Parse FilterState<br/>JSON column"]
+        GEN["GenerateWhereClause()<br/>Recursive group processing"]
+        SQL["SQL WHERE clause"]
+    end
+
+    subgraph Modes["Filter Modes"]
+        STD["Standard Filter<br/>UI-driven FilterState"]
+        SMART["Smart Filter<br/>AI-generated from prompt"]
+        CUSTOM["Custom Filter<br/>Admin-set WhereClause"]
+    end
+
+    FS --> PARSE --> GEN --> SQL
+    Modes --> GEN
+
+    style Input fill:#b8762f,stroke:#8a5722,color:#fff
+    style Process fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Modes fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+Supported filter operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `startswith`, `endswith`, `contains`, `doesnotcontain`, `isnull`, `isempty`, `isnotnull`, `isnotempty`. Filters support arbitrary nesting with `and`/`or` logic groups.
+
+## Important: CodeGen and This Package
 
-## Best Practices
+This package's `src/generated/entity_subclasses.ts` file is **entirely auto-generated** by the MemberJunction CodeGen system. Key implications:
 
-1. **Always use Metadata for entity creation**: Never instantiate entity classes directly
-2. **Use RunView for bulk operations**: More efficient than loading entities individually
-3. **Leverage TypeScript types**: Use exported types for function parameters
-4. **Handle validation errors**: Wrap entity operations in try-catch blocks
-5. **Use extended classes**: When available, use extended versions for additional functionality
-6. **Import artifacts from core-entities**: Artifact extraction utilities are in this package
+- **Never edit generated files** -- changes will be overwritten on the next CodeGen run.
+- **Custom logic goes in `src/custom/`** -- create an extended class with `@RegisterClass` to override the generated base.
+- **Entity names matter** -- some entities use the `MJ: ` prefix (e.g., `MJ: Components`, `MJ: Environments`). Always verify names in the generated file's `@RegisterClass` decorators.
+- **Zod schemas are authoritative** -- they reflect the exact database constraints including value lists, nullable fields, and default values.
 
 ## Dependencies
 
-- `@memberjunction/core`: Core MemberJunction functionality
-- `@memberjunction/global`: Global utilities and decorators
-- `zod`: Runtime type validation
+- [@memberjunction/core](../MJCore/README.md) -- Base entity classes, metadata system, RunView, BaseEngine
+- [@memberjunction/global](../MJGlobal/README.md) -- `@RegisterClass` decorator, global utilities
+- [@memberjunction/ai](../AI/README.md) -- AI integration types (used by some engine classes)
+- [@memberjunction/interactive-component-types](../InteractiveComponentTypes/README.md) -- ComponentSpec type for component entity extensions
+- [zod](https://zod.dev/) -- Runtime schema validation
 
-## License
+## Related Packages
 
-ISC - See LICENSE file for details
+- [@memberjunction/core](../MJCore/README.md) -- Framework foundation this package builds on
+- [@memberjunction/core-entities-server](../MJCoreEntitiesServer/README.md) -- Server-side extensions of entities defined here (e.g., smart filter AI implementation)
+- [@memberjunction/server](../MJServer/README.md) -- Server that uses these entities for API operations
 
-## Support
+## Contributing
 
-For issues, questions, or contributions, visit the [MemberJunction GitHub repository](https://github.com/MemberJunction/MJ).
+See the [MemberJunction Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.