@xrmforge/typegen 0.8.4 → 0.8.5

package/docs/architecture/00-README.md

@@ -1,26 +1,26 @@
-# XrmForge Architecture
-
-> **Status:** Living document describing the current implementation state.
-> **Last updated:** 2026-04-04 (Session 10)
-> **Version:** 7 packages, 666+ tests across all packages.
-
-## Chapters
-
-1. [Executive Summary](01-executive-summary.md)
-2. [Package Architecture](02-packages.md)
-3. [Generated Types](03-generated-types.md)
-4. [CLI Commands](04-cli.md)
-5. [Build Architecture](05-build.md)
-6. [Incremental Generation](06-incremental.md)
-7. [HTTP Client](07-http-client.md)
-8. [Authentication](08-authentication.md)
-9. [Testing Framework](09-testing.md)
-10. [ESLint Plugin](10-eslint-plugin.md)
-11. [AGENT.md System](11-agent-md.md)
-12. [@types/xrm Pitfalls](12-xrm-pitfalls.md)
-13. [@xrmforge/helpers Package](13-helpers.md)
-14. [Showcases](14-showcases.md)
-15. [CI/CD](15-ci-cd.md)
-16. [Technical Debt](16-technical-debt.md)
-17. [Roadmap](17-roadmap.md)
-18. [Design Principles](18-design-principles.md)
+# XrmForge Architecture
+
+> **Status:** Living document describing the current implementation state.
+> **Last updated:** 2026-04-04 (Session 10)
+> **Version:** 7 packages, 666+ tests across all packages.
+
+## Chapters
+
+1. [Executive Summary](01-executive-summary.md)
+2. [Package Architecture](02-packages.md)
+3. [Generated Types](03-generated-types.md)
+4. [CLI Commands](04-cli.md)
+5. [Build Architecture](05-build.md)
+6. [Incremental Generation](06-incremental.md)
+7. [HTTP Client](07-http-client.md)
+8. [Authentication](08-authentication.md)
+9. [Testing Framework](09-testing.md)
+10. [ESLint Plugin](10-eslint-plugin.md)
+11. [AGENT.md System](11-agent-md.md)
+12. [@types/xrm Pitfalls](12-xrm-pitfalls.md)
+13. [@xrmforge/helpers Package](13-helpers.md)
+14. [Showcases](14-showcases.md)
+15. [CI/CD](15-ci-cd.md)
+16. [Technical Debt](16-technical-debt.md)
+17. [Roadmap](17-roadmap.md)
+18. [Design Principles](18-design-principles.md)

package/docs/architecture/01-executive-summary.md

@@ -1,11 +1,11 @@
-# Executive Summary
-
-XrmForge is an open-source TypeScript toolkit for type-safe Dynamics 365 / Dataverse WebResource development. It generates TypeScript declarations from live Dataverse metadata, turning runtime string errors into compile-time type errors.
-
-**Core value proposition:** Every field name, OptionSet value, tab name, entity name, and subgrid name becomes a typed constant with IDE autocomplete and compile-time validation.
-
-**Target audience:** D365 developers who write form scripts (WebResources) in JavaScript/TypeScript and want compile-time safety, zero magic strings, and modern tooling (esbuild, vitest, ESLint).
-
-**Tech stack:** TypeScript, pnpm monorepo with Turborepo, esbuild for IIFE bundles, vitest for testing, @azure/identity for authentication, fast-xml-parser for FormXml parsing.
-
-**npm organization:** [@xrmforge](https://www.npmjs.com/org/xrmforge)
+# Executive Summary
+
+XrmForge is an open-source TypeScript toolkit for type-safe Dynamics 365 / Dataverse WebResource development. It generates TypeScript declarations from live Dataverse metadata, turning runtime string errors into compile-time type errors.
+
+**Core value proposition:** Every field name, OptionSet value, tab name, entity name, and subgrid name becomes a typed constant with IDE autocomplete and compile-time validation.
+
+**Target audience:** D365 developers who write form scripts (WebResources) in JavaScript/TypeScript and want compile-time safety, zero magic strings, and modern tooling (esbuild, vitest, ESLint).
+
+**Tech stack:** TypeScript, pnpm monorepo with Turborepo, esbuild for IIFE bundles, vitest for testing, @azure/identity for authentication, fast-xml-parser for FormXml parsing.
+
+**npm organization:** [@xrmforge](https://www.npmjs.com/org/xrmforge)

package/docs/architecture/02-packages.md

@@ -1,110 +1,110 @@
-# Package Architecture
-
-## Package Overview
-
-| Package | Version | Tests | Description |
-|---------|---------|-------|-------------|
-| @xrmforge/typegen | 0.8.0 | 444 | Core: type generation engine, metadata client, HTTP client, helpers |
-| @xrmforge/cli | 0.4.2 | 10 | CLI: generate, build, init commands |
-| @xrmforge/testing | 0.2.0 | 76 | Test utilities: createFormMock, fireOnChange, setupXrmMock |
-| @xrmforge/helpers | 0.1.0 | 59 | Browser-safe runtime: select(), parseLookup(), typedForm(), Xrm constants, Action executors |
-| @xrmforge/webapi | 0.1.0 | 45 | Type-safe Xrm.WebApi client with QueryBuilder |
-| @xrmforge/devkit | 0.4.0 | 42 | Build orchestration, scaffolding, AGENT.md generation |
-| @xrmforge/eslint-plugin | 0.2.0 | 32 | 5 D365-specific ESLint rules |
-
-**Total:** 708 tests across 7 packages.
-
-## Dependency Graph
-
-```
-@xrmforge/cli
-  |-- @xrmforge/typegen (generate command)
-  |-- @xrmforge/devkit  (build + init commands)
-  '-- commander (CLI framework)
-
-@xrmforge/typegen
-  |-- @azure/identity  (authentication)
-  '-- fast-xml-parser  (FormXml parsing)
-
-@xrmforge/devkit
-  '-- esbuild (IIFE bundling)
-
-@xrmforge/testing     (no runtime deps)
-@xrmforge/helpers     (no runtime deps)
-@xrmforge/webapi      (no runtime deps)
-@xrmforge/eslint-plugin (ESLint peer dep)
-```
-
-## Package Details
-
-### @xrmforge/typegen
-
-The core package. Contains:
-
-- **TypeGenerationOrchestrator** - Coordinates the entire generation pipeline
-- **MetadataClient** - Queries Dataverse metadata (entities, forms, OptionSets, Custom APIs)
-- **DataverseHttpClient** - Resilient REST client with retry, rate limiting, concurrency control
-- **ChangeDetector** - Incremental generation via RetrieveMetadataChanges
-- **MetadataCache** - Filesystem-based caching with version stamps
-- **Generators** - Entity interfaces, form interfaces, OptionSet enums, Fields enums, EntityNames, Navigation Properties, Action/Function executors
-- **Helpers** - select(), parseLookup(), parseFormattedValue() (moved to @xrmforge/helpers)
-- **Xrm Constants** - DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState (moved to @xrmforge/helpers)
-- **Authentication** - createCredential() factory for 4 auth methods
-- **Logging** - Scoped loggers with pluggable sinks (Console, JSON, Silent)
-- **Errors** - Structured error hierarchy with ErrorCode enum (AUTH_1xxx, API_2xxx, META_3xxx, GEN_4xxx, CONFIG_5xxx)
-
-### @xrmforge/cli
-
-Command-line interface built with commander.js. Three commands:
-- `xrmforge generate` - Orchestrates TypeGenerationOrchestrator
-- `xrmforge build` - Delegates to devkit build()
-- `xrmforge init` - Delegates to devkit scaffoldProject()
-
-### @xrmforge/testing
-
-FormContext mocking for unit tests:
-- `createFormMock<TForm>(values)` - Creates a complete mock from simple key-value pairs
-- `MockAttribute` - getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
-- `MockControl` - visible, disabled, label, notifications
-- `MockUi` - Form notifications, tab/section stubs
-- `MockEntity` - Entity ID, name, primary attribute
-- `fireOnChange(fieldName)` - Triggers registered onChange handlers
-- `setupXrmMock(options)` / `teardownXrmMock()` - Global Xrm mock with WebApi/Navigation stubs
-
-### @xrmforge/helpers
-
-Consolidates all browser-safe runtime code. Zero Node.js dependencies. Contains:
-- **Web API helpers** - select(), parseLookup(), parseFormattedValue()
-- **Xrm constants** - DisplayState, SubmitMode, RequiredLevel, SaveMode, ClientType, ClientState, FormNotificationLevel, OperationType
-- **Action/Function executors** - createBoundAction(), executeRequest(), withProgress()
-- **typedForm() proxy** - Proxy-based FormContext wrapper where `form.name` delegates to `getAttribute('name')`
-
-### @xrmforge/webapi
-
-Type-safe wrapper around Xrm.WebApi:
-- `retrieve<T>(entityName, id, query)` - Single record
-- `retrieveMultiple<T>(entityName, query, options)` - With pagination (maxPages)
-- `create(entityName, data)` - Returns record ID
-- `update(entityName, id, data)` - Void
-- `remove(entityName, id)` - Void
-- `QueryBuilder` - Fluent API: `.select().filter().orderBy().top().expand().build()`
-- `WebApiError` - Structured errors with statusCode, errorCode, innerMessage
-
-### @xrmforge/devkit
-
-Build orchestration and project scaffolding:
-- `build(config)` - Parallel esbuild IIFE builds via Promise.allSettled
-- `watch(config)` - esbuild watch mode with rebuild callbacks
-- `scaffoldProject(config)` - Generates 11 project files from templates
-- `validateBuildConfig(config)` / `resolveBuildConfig(config)` - Config validation
-- `BuildError` with codes: CONFIG_INVALID, ENTRY_NOT_FOUND, BUILD_FAILED, WATCH_ERROR
-- Template system: 7 text templates in `src/scaffold/templates/`, loaded via `template-loader.ts`
-
-### @xrmforge/eslint-plugin
-
-5 rules for D365 form scripts (ESLint v9 flat config):
-- `no-xrm-page` (error) - Forbids deprecated Xrm.Page API
-- `no-magic-optionset` (warn) - Forbids magic numbers in OptionSet comparisons
-- `no-sync-webapi` (error) - Forbids synchronous XMLHttpRequest
-- `require-error-handling` (warn) - Requires try/catch in async on* event handlers
-- `require-namespace` (warn) - Forbids window/globalThis assignments
+# Package Architecture
+
+## Package Overview
+
+| Package | Version | Tests | Description |
+|---------|---------|-------|-------------|
+| @xrmforge/typegen | 0.8.0 | 444 | Core: type generation engine, metadata client, HTTP client, helpers |
+| @xrmforge/cli | 0.4.2 | 10 | CLI: generate, build, init commands |
+| @xrmforge/testing | 0.2.0 | 76 | Test utilities: createFormMock, fireOnChange, setupXrmMock |
+| @xrmforge/helpers | 0.1.0 | 59 | Browser-safe runtime: select(), parseLookup(), typedForm(), Xrm constants, Action executors |
+| @xrmforge/webapi | 0.1.0 | 45 | Type-safe Xrm.WebApi client with QueryBuilder |
+| @xrmforge/devkit | 0.4.0 | 42 | Build orchestration, scaffolding, AGENT.md generation |
+| @xrmforge/eslint-plugin | 0.2.0 | 32 | 5 D365-specific ESLint rules |
+
+**Total:** 708 tests across 7 packages.
+
+## Dependency Graph
+
+```
+@xrmforge/cli
+  |-- @xrmforge/typegen (generate command)
+  |-- @xrmforge/devkit  (build + init commands)
+  '-- commander (CLI framework)
+
+@xrmforge/typegen
+  |-- @azure/identity  (authentication)
+  '-- fast-xml-parser  (FormXml parsing)
+
+@xrmforge/devkit
+  '-- esbuild (IIFE bundling)
+
+@xrmforge/testing     (no runtime deps)
+@xrmforge/helpers     (no runtime deps)
+@xrmforge/webapi      (no runtime deps)
+@xrmforge/eslint-plugin (ESLint peer dep)
+```
+
+## Package Details
+
+### @xrmforge/typegen
+
+The core package. Contains:
+
+- **TypeGenerationOrchestrator** - Coordinates the entire generation pipeline
+- **MetadataClient** - Queries Dataverse metadata (entities, forms, OptionSets, Custom APIs)
+- **DataverseHttpClient** - Resilient REST client with retry, rate limiting, concurrency control
+- **ChangeDetector** - Incremental generation via RetrieveMetadataChanges
+- **MetadataCache** - Filesystem-based caching with version stamps
+- **Generators** - Entity interfaces, form interfaces, OptionSet enums, Fields enums, EntityNames, Navigation Properties, Action/Function executors
+- **Helpers** - select(), parseLookup(), parseFormattedValue() (moved to @xrmforge/helpers)
+- **Xrm Constants** - DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState (moved to @xrmforge/helpers)
+- **Authentication** - createCredential() factory for 4 auth methods
+- **Logging** - Scoped loggers with pluggable sinks (Console, JSON, Silent)
+- **Errors** - Structured error hierarchy with ErrorCode enum (AUTH_1xxx, API_2xxx, META_3xxx, GEN_4xxx, CONFIG_5xxx)
+
+### @xrmforge/cli
+
+Command-line interface built with commander.js. Three commands:
+- `xrmforge generate` - Orchestrates TypeGenerationOrchestrator
+- `xrmforge build` - Delegates to devkit build()
+- `xrmforge init` - Delegates to devkit scaffoldProject()
+
+### @xrmforge/testing
+
+FormContext mocking for unit tests:
+- `createFormMock<TForm>(values)` - Creates a complete mock from simple key-value pairs
+- `MockAttribute` - getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
+- `MockControl` - visible, disabled, label, notifications
+- `MockUi` - Form notifications, tab/section stubs
+- `MockEntity` - Entity ID, name, primary attribute
+- `fireOnChange(fieldName)` - Triggers registered onChange handlers
+- `setupXrmMock(options)` / `teardownXrmMock()` - Global Xrm mock with WebApi/Navigation stubs
+
+### @xrmforge/helpers
+
+Consolidates all browser-safe runtime code. Zero Node.js dependencies. Contains:
+- **Web API helpers** - select(), parseLookup(), parseFormattedValue()
+- **Xrm constants** - DisplayState, SubmitMode, RequiredLevel, SaveMode, ClientType, ClientState, FormNotificationLevel, OperationType
+- **Action/Function executors** - createBoundAction(), executeRequest(), withProgress()
+- **typedForm() proxy** - Proxy-based FormContext wrapper where `form.name` delegates to `getAttribute('name')`
+
+### @xrmforge/webapi
+
+Type-safe wrapper around Xrm.WebApi:
+- `retrieve<T>(entityName, id, query)` - Single record
+- `retrieveMultiple<T>(entityName, query, options)` - With pagination (maxPages)
+- `create(entityName, data)` - Returns record ID
+- `update(entityName, id, data)` - Void
+- `remove(entityName, id)` - Void
+- `QueryBuilder` - Fluent API: `.select().filter().orderBy().top().expand().build()`
+- `WebApiError` - Structured errors with statusCode, errorCode, innerMessage
+
+### @xrmforge/devkit
+
+Build orchestration and project scaffolding:
+- `build(config)` - Parallel esbuild IIFE builds via Promise.allSettled
+- `watch(config)` - esbuild watch mode with rebuild callbacks
+- `scaffoldProject(config)` - Generates 11 project files from templates
+- `validateBuildConfig(config)` / `resolveBuildConfig(config)` - Config validation
+- `BuildError` with codes: CONFIG_INVALID, ENTRY_NOT_FOUND, BUILD_FAILED, WATCH_ERROR
+- Template system: 7 text templates in `src/scaffold/templates/`, loaded via `template-loader.ts`
+
+### @xrmforge/eslint-plugin
+
+5 rules for D365 form scripts (ESLint v9 flat config):
+- `no-xrm-page` (error) - Forbids deprecated Xrm.Page API
+- `no-magic-optionset` (warn) - Forbids magic numbers in OptionSet comparisons
+- `no-sync-webapi` (error) - Forbids synchronous XMLHttpRequest
+- `require-error-handling` (warn) - Requires try/catch in async on* event handlers
+- `require-namespace` (warn) - Forbids window/globalThis assignments

package/docs/architecture/03-generated-types.md

@@ -1,172 +1,172 @@
-# Generated Types
-
-Running `xrmforge generate` produces the following TypeScript ES modules:
-
-### 3.1 Entity Interfaces (`entities/{entity}.ts`)
-
-```typescript
-// generated/entities/account.ts
-/** Account | Konto */
-export interface Account {
-  /** Account Name | Kontoname */
-  name: string | null;
-  accountid: string | null;
-  revenue: number | null;
-  _parentaccountid_value: string | null;  // Lookup GUID
-  // ...
-}
-```
-
-**Type mapping:** String/Memo/EntityName to `string`, Integer/BigInt/Decimal/Double/Money to `number`, Boolean to `boolean`, DateTime/Uniqueidentifier/Lookup to `string`, Picklist/State/Status to `number`.
-
-### 3.2 Entity Fields Enums (`fields/{entity}.ts`)
-
-```typescript
-// generated/fields/account.ts
-export const enum AccountFields {
-  /** Account Name | Kontoname */
-  Name = 'name',
-  Telephone1 = 'telephone1',
-  Revenue = 'revenue',
-  // all entity attributes for $select queries
-}
-
-export const enum AccountNavigationProperties {
-  PrimaryContact = 'primarycontactid',
-  ContactCustomerAccounts = 'contact_customer_accounts',
-  // all lookup navigation properties
-}
-```
-
-Used for Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
-
-### 3.3 Navigation Properties (`fields/{entity}.ts`)
-
-Navigation property enums are co-located with the Fields enums in the same file (see 3.2 above). Example usage:
-
-```typescript
-import { AccountNavigationProperties } from '../generated/fields/account';
-// used for $expand queries
-```
-
-### 3.4 Form Interfaces (`forms/{entity}.ts`)
-
-```typescript
-// generated/forms/account.ts
-
-// Union type restricting valid field names
-export type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
-
-// Mapped type: field name to Xrm attribute type
-export type AccountMainFormAttributeMap = {
-  name: Xrm.Attributes.StringAttribute;
-  telephone1: Xrm.Attributes.StringAttribute;
-  revenue: Xrm.Attributes.NumberAttribute;
-};
-
-// Mapped type: field name to Xrm control type
-export type AccountMainFormControlMap = {
-  name: Xrm.Controls.StringControl;
-  telephone1: Xrm.Controls.StringControl;
-  revenue: Xrm.Controls.NumberControl;
-};
-
-// Fields enum for autocomplete
-export const enum AccountMainFormFieldsEnum {
-  /** Account Name | Kontoname */
-  AccountName = 'name',
-  Telephone1 = 'telephone1',
-  Revenue = 'revenue',
-}
-
-// Type-safe FormContext with overloaded getAttribute/getControl
-export interface AccountMainForm extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {
-  getAttribute<K extends AccountMainFormFields>(name: K): AccountMainFormAttributeMap[K];
-  getAttribute(index: number): Xrm.Attributes.Attribute;
-  getAttribute(): Xrm.Attributes.Attribute[];
-
-  getControl<K extends AccountMainFormFields>(name: K): AccountMainFormControlMap[K];
-  getControl(index: number): Xrm.Controls.Control;
-  getControl(): Xrm.Controls.Control[];
-}
-```
-
-**Special controls** are typed based on their FormXml ClassID:
-- Subgrid: `Xrm.Controls.GridControl`
-- Editable Grid: `Xrm.Controls.GridControl`
-- Quick View: `Xrm.Controls.QuickFormControl`
-- Web Resource / iFrame: `Xrm.Controls.IframeControl`
-
-### 3.5 Tabs/Sections/Subgrids/QuickViews Enums
-
-```typescript
-const enum AccountMainFormTabs { Summary = 'SUMMARY_TAB', Details = 'DETAILS_TAB' }
-const enum AccountMainFormSections { General = 'GENERAL', Address = 'ADDRESS' }
-const enum AccountMainFormSubgrids { Contacts = 'Contacts_Subgrid' }
-const enum AccountMainFormQuickViews { ContactPreview = 'ContactQuickView' }
-```
-
-### 3.6 OptionSet Enums (`optionsets/{entity}.ts`)
-
-```typescript
-// generated/optionsets/account.ts
-/** Account Category Code | Kontokategoriecode */
-export const enum AccountCategoryCode {
-  /** Preferred Customer | Bevorzugter Kunde */
-  PreferredCustomer = 1,
-  Standard = 2,
-}
-```
-
-Includes Picklist, Status, State, and MultiSelectPicklist attributes. Duplicate labels are disambiguated with `_{Value}` suffix.
-
-### 3.7 EntityNames Enum (`entity-names.ts`)
-
-```typescript
-// generated/entity-names.ts
-export const enum EntityNames {
-  Account = 'account',
-  Contact = 'contact',
-  // all entities in scope
-}
-```
-
-### 3.8 MockValues Types (in form interfaces)
-
-```typescript
-type AccountMainFormMockValues = {
-  name?: string | null;
-  telephone1?: string | null;
-  revenue?: number | null;
-};
-```
-
-Used with `createFormMock<AccountMainForm, AccountMainFormMockValues>({ name: 'Test' })`.
-
-### 3.9 Action/Function Executors (`actions/{entity|global}.ts`)
-
-```typescript
-// generated/actions/global.ts
-import { createUnboundAction } from '@xrmforge/helpers';
-
-export interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
-export interface NormalizePhoneResult { Normalized: string; Status: number; }
-
-export const NormalizePhone = createUnboundAction<NormalizePhoneParams, NormalizePhoneResult>(
-  'markant_NormalizePhone',
-  { Input: { typeName: 'String', structuralProperty: 1 } }
-);
-// Usage: const result = await NormalizePhone.execute({ Input: '123' });
-```
-
-Factory functions: `createBoundAction`, `createUnboundAction`, `createBoundFunction`, `createUnboundFunction`. Batch execution via `executeMultiple()`, progress UI via `withProgress()`.
-
-### 3.10 Dual-Language Labels
-
-All generated JSDoc comments support dual-language labels:
-```typescript
-/** Account Name | Kontoname */
-Name = 'name',
-```
-
-German umlauts are transliterated in identifiers: ae, oe, ue, ss (e.g. "Ubergeordnet" becomes `Uebergeordnet`).
+# Generated Types
+
+Running `xrmforge generate` produces the following TypeScript ES modules:
+
+### 3.1 Entity Interfaces (`entities/{entity}.ts`)
+
+```typescript
+// generated/entities/account.ts
+/** Account | Konto */
+export interface Account {
+  /** Account Name | Kontoname */
+  name: string | null;
+  accountid: string | null;
+  revenue: number | null;
+  _parentaccountid_value: string | null;  // Lookup GUID
+  // ...
+}
+```
+
+**Type mapping:** String/Memo/EntityName to `string`, Integer/BigInt/Decimal/Double/Money to `number`, Boolean to `boolean`, DateTime/Uniqueidentifier/Lookup to `string`, Picklist/State/Status to `number`.
+
+### 3.2 Entity Fields Enums (`fields/{entity}.ts`)
+
+```typescript
+// generated/fields/account.ts
+export const enum AccountFields {
+  /** Account Name | Kontoname */
+  Name = 'name',
+  Telephone1 = 'telephone1',
+  Revenue = 'revenue',
+  // all entity attributes for $select queries
+}
+
+export const enum AccountNavigationProperties {
+  PrimaryContact = 'primarycontactid',
+  ContactCustomerAccounts = 'contact_customer_accounts',
+  // all lookup navigation properties
+}
+```
+
+Used for Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
+
+### 3.3 Navigation Properties (`fields/{entity}.ts`)
+
+Navigation property enums are co-located with the Fields enums in the same file (see 3.2 above). Example usage:
+
+```typescript
+import { AccountNavigationProperties } from '../generated/fields/account';
+// used for $expand queries
+```
+
+### 3.4 Form Interfaces (`forms/{entity}.ts`)
+
+```typescript
+// generated/forms/account.ts
+
+// Union type restricting valid field names
+export type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
+
+// Mapped type: field name to Xrm attribute type
+export type AccountMainFormAttributeMap = {
+  name: Xrm.Attributes.StringAttribute;
+  telephone1: Xrm.Attributes.StringAttribute;
+  revenue: Xrm.Attributes.NumberAttribute;
+};
+
+// Mapped type: field name to Xrm control type
+export type AccountMainFormControlMap = {
+  name: Xrm.Controls.StringControl;
+  telephone1: Xrm.Controls.StringControl;
+  revenue: Xrm.Controls.NumberControl;
+};
+
+// Fields enum for autocomplete
+export const enum AccountMainFormFieldsEnum {
+  /** Account Name | Kontoname */
+  AccountName = 'name',
+  Telephone1 = 'telephone1',
+  Revenue = 'revenue',
+}
+
+// Type-safe FormContext with overloaded getAttribute/getControl
+export interface AccountMainForm extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {
+  getAttribute<K extends AccountMainFormFields>(name: K): AccountMainFormAttributeMap[K];
+  getAttribute(index: number): Xrm.Attributes.Attribute;
+  getAttribute(): Xrm.Attributes.Attribute[];
+
+  getControl<K extends AccountMainFormFields>(name: K): AccountMainFormControlMap[K];
+  getControl(index: number): Xrm.Controls.Control;
+  getControl(): Xrm.Controls.Control[];
+}
+```
+
+**Special controls** are typed based on their FormXml ClassID:
+- Subgrid: `Xrm.Controls.GridControl`
+- Editable Grid: `Xrm.Controls.GridControl`
+- Quick View: `Xrm.Controls.QuickFormControl`
+- Web Resource / iFrame: `Xrm.Controls.IframeControl`
+
+### 3.5 Tabs/Sections/Subgrids/QuickViews Enums
+
+```typescript
+const enum AccountMainFormTabs { Summary = 'SUMMARY_TAB', Details = 'DETAILS_TAB' }
+const enum AccountMainFormSections { General = 'GENERAL', Address = 'ADDRESS' }
+const enum AccountMainFormSubgrids { Contacts = 'Contacts_Subgrid' }
+const enum AccountMainFormQuickViews { ContactPreview = 'ContactQuickView' }
+```
+
+### 3.6 OptionSet Enums (`optionsets/{entity}.ts`)
+
+```typescript
+// generated/optionsets/account.ts
+/** Account Category Code | Kontokategoriecode */
+export const enum AccountCategoryCode {
+  /** Preferred Customer | Bevorzugter Kunde */
+  PreferredCustomer = 1,
+  Standard = 2,
+}
+```
+
+Includes Picklist, Status, State, and MultiSelectPicklist attributes. Duplicate labels are disambiguated with `_{Value}` suffix.
+
+### 3.7 EntityNames Enum (`entity-names.ts`)
+
+```typescript
+// generated/entity-names.ts
+export const enum EntityNames {
+  Account = 'account',
+  Contact = 'contact',
+  // all entities in scope
+}
+```
+
+### 3.8 MockValues Types (in form interfaces)
+
+```typescript
+type AccountMainFormMockValues = {
+  name?: string | null;
+  telephone1?: string | null;
+  revenue?: number | null;
+};
+```
+
+Used with `createFormMock<AccountMainForm, AccountMainFormMockValues>({ name: 'Test' })`.
+
+### 3.9 Action/Function Executors (`actions/{entity|global}.ts`)
+
+```typescript
+// generated/actions/global.ts
+import { createUnboundAction } from '@xrmforge/helpers';
+
+export interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
+export interface NormalizePhoneResult { Normalized: string; Status: number; }
+
+export const NormalizePhone = createUnboundAction<NormalizePhoneParams, NormalizePhoneResult>(
+  'markant_NormalizePhone',
+  { Input: { typeName: 'String', structuralProperty: 1 } }
+);
+// Usage: const result = await NormalizePhone.execute({ Input: '123' });
+```
+
+Factory functions: `createBoundAction`, `createUnboundAction`, `createBoundFunction`, `createUnboundFunction`. Batch execution via `executeMultiple()`, progress UI via `withProgress()`.
+
+### 3.10 Dual-Language Labels
+
+All generated JSDoc comments support dual-language labels:
+```typescript
+/** Account Name | Kontoname */
+Name = 'name',
+```
+
+German umlauts are transliterated in identifiers: ae, oe, ue, ss (e.g. "Ubergeordnet" becomes `Uebergeordnet`).