@xrmforge/devkit 0.6.1 → 0.7.0

package/dist/templates/AGENT.md

@@ -1,450 +1,534 @@
-# XrmForge - AI Agent Instructions
-
-This file helps AI coding assistants write optimal Dynamics 365 form scripts.
-
-## Packages
-
-- `@xrmforge/typegen` - Generates typed declarations from Dataverse metadata
-- `@xrmforge/helpers` - Browser-safe runtime: select(), parseLookup(), typedForm(), Xrm constants, Action executors
-- `@xrmforge/testing` - Type-safe form mocks: createFormMock(), fireOnChange()
-- `@xrmforge/devkit` - esbuild IIFE bundles via xrmforge build
-- `@xrmforge/eslint-plugin` - D365-specific ESLint rules
-
-## Generated Types (generated/ directory)
-
-Run `xrmforge generate` to create:
-- `generated/forms/{entity}.ts` - Form interface + Fields/Tabs/Sections/Subgrids enums
-- `generated/optionsets/{entity}.ts` - OptionSet const enums
-- `generated/entities/{entity}.ts` - Entity interface
-- `generated/fields/{entity}.ts` - Entity Fields enum for type-safe $select queries
-- `generated/entity-names.ts` - EntityNames const enum
-- `generated/form-mapping.json` - Entity to form interface mapping (read after generate!)
-- `generated/index.ts` - Barrel file with `export * from` re-exports
-
-**After generate:** Read `generated/form-mapping.json` for the mapping of entity logical
-names to form interface names. Do NOT guess interface names from entity names.
-Fields enum member names are based on the **primary language label** (often German),
-not the logical field name. Always read the generated files to get correct names.
-
-**Large projects (50+ entities):** `form-mapping.json` can be large. Do NOT grep through
-all generated files to find interface names. Read `form-mapping.json` once, then use
-the mapping for all imports. This saves time and avoids wrong guesses.
-
-## Rules: MANDATORY (every violation is a bug)
-
-1. **Fields Enum** for ALL getAttribute/getControl calls. Never raw strings.
-   ```typescript
-   import { AccountMainFormFieldsEnum as Fields } from '../generated/forms/account.js';
-   form.getAttribute(Fields.Name)  // CORRECT
-   form.getAttribute("name")       // BUG - raw string
-   ```
-
-2. **OptionSet Enum** for ALL value comparisons. Never magic numbers.
-   ```typescript
-   import { StatusCode } from '../generated/optionsets/invoice.js';
-   if (status === StatusCode.Active) // CORRECT
-   if (status === 0)                 // BUG - magic number
-   ```
-
-3. **FormContext Cast** to generated form interface in every onLoad:
-   ```typescript
-   import type { AccountMainForm } from '../generated/forms/account.js';
-   const form = ctx.getFormContext() as AccountMainForm;
-   ```
-
-4. **EntityNames Enum** in ALL Xrm.WebApi calls — no exceptions, even for system entities:
-   ```typescript
-   import { EntityNames } from '../generated/entity-names.js';
-   Xrm.WebApi.retrieveRecord(EntityNames.Account, id)
-   ```
-   If an entity is not in EntityNames, extend the generation (`--entities` flag) to include it.
-
-5. **Lookup helpers** from @xrmforge/helpers for ALL lookup value access:
-   ```typescript
-   import { formLookup, formLookupId, parseLookup } from '@xrmforge/helpers';
-   // Form lookups (getAttribute on FormContext):
-   const customer = formLookup(form.getAttribute(Fields.CustomerId));
-   const customerId = formLookupId(form.getAttribute(Fields.CustomerId));
-   // Web API response lookups (_fieldname_value + OData annotations):
-   const parent = parseLookup(apiResponse, 'parentaccountid');
-   ```
-   **NEVER** access lookup values directly:
-   ```typescript
-   // BUG - never do this:
-   form.getAttribute(Fields.CustomerId).getValue()[0].id.replace('{','')
-   // CORRECT:
-   formLookupId(form.getAttribute(Fields.CustomerId))
-   ```
-
-6. **select()** from @xrmforge/helpers for ALL $select queries:
-   ```typescript
-   import { select } from '@xrmforge/helpers';
-   // Simple query:
-   Xrm.WebApi.retrieveRecord(EntityNames.Account, id, select(Fields.Name, Fields.Revenue))
-   // Combined with $filter:
-   Xrm.WebApi.retrieveMultipleRecords(EntityNames.Account,
-     `${select(Fields.Name, Fields.Revenue)}&$filter=statecode eq 0`)
-   ```
-   **Signature:** `select(...fields: string[])` takes REST parameters, NOT an array.
-   ```typescript
-   select(Fields.Name, Fields.Revenue)           // CORRECT
-   select([Fields.Name, Fields.Revenue])          // WRONG - array argument
-   select('account', Fields.Name)                 // WRONG - first arg is not entity name
-   ```
-
-7. **wrapHandler()** around EVERY exported async event handler:
-   ```typescript
-   import { createLogger } from '../shared/logger';
-   import { wrapHandler } from '../shared/error-handler';
-   const logger = createLogger('Namespace.Entity');
-   export const onLoad = wrapHandler('Namespace.Entity.onLoad', logger, async (ctx) => {
-     // handler code
-   });
-   ```
-
-8. **createFormMock()** from @xrmforge/testing for ALL form tests:
-   ```typescript
-   import { createFormMock, fireOnChange, setupXrmMock } from '@xrmforge/testing';
-   ```
-
-9. **Module exports** (not window/global assignments). esbuild globalName handles namespacing.
-
-10. **Structured Logger** instead of console.* (except in logger.ts itself):
-    ```typescript
-    import { createLogger } from '../shared/logger';
-    const logger = createLogger('Namespace.Entity');
-    logger.info('Form loaded', { recordId });
-    ```
-
-## Rules: NEVER (every occurrence is a bug)
-
-- Never `getAttribute("raw_string")` when Fields enum exists
-- Never magic numbers for OptionSet values (use OptionSet enums)
-- Never `Xrm.Page` (deprecated since D365 v9.0)
-- Never synchronous XMLHttpRequest
-- Never `eval()`
-- Never `window.X = ...` (use module exports)
-- Never `console.log/warn/error` in form scripts (use shared logger)
-- Never export async handlers without wrapHandler()
-- Never `Xrm.WebApi.retrieveRecord("account", ...)` with raw entity name (use EntityNames, no exceptions even for system entities)
-- Never `"?$select=name,revenue"` as raw string (use select() from @xrmforge/helpers)
-- Never `.getValue()[0].id` or `.getValue()[0].id.replace(...)` for lookups (use formLookup/formLookupId from @xrmforge/helpers)
-- Never build your own lookup helper (getLookupValueId, firstLookupValue, etc.) when formLookup/formLookupId exists
-- Never `import ... from '@xrmforge/typegen'` in browser code. @xrmforge/typegen is a Node.js CLI tool. Use `@xrmforge/helpers` for browser-safe runtime functions (select, parseLookup, formLookup, createUnboundAction, etc.)
-
-## Subagent Handoff (when delegating to sub-agents)
-
-Copy these MANDATORY rules into every sub-agent prompt:
-
-```
-1. Fields Enum for ALL getAttribute/getControl (never raw strings)
-2. OptionSet Enum for ALL value comparisons (never magic numbers)
-3. EntityNames for ALL Xrm.WebApi calls (never raw entity names, no exceptions)
-4. formLookup/formLookupId for ALL lookup access (never .getValue()[0].id)
-5. select() for ALL $select queries (never raw "$select=" strings)
-6. wrapHandler() around EVERY exported async handler
-7. createLogger() instead of console.* (except logger.ts)
-```
-
-## Mandatory Shared Utilities
-
-Every XrmForge project MUST have these in `src/shared/`:
-
-### logger.ts
-```typescript
-export interface Logger { debug(msg: string, data?: unknown): void; info(...); warn(...); error(...); }
-export function createLogger(namespace: string): Logger;
-// Only file allowed to use console.*
-```
-
-### error-handler.ts
-```typescript
-export function wrapHandler<T>(name: string, logger: Logger, handler: T): T;
-// Catches sync+async errors, shows form notification, never rethrows
-```
-
-### constants.ts
-```typescript
-export const NOTIFICATION_IDS = { ... } as const;
-export const MESSAGES = { ... } as const;
-```
-
-## Before/After Examples
-
-### Field Access
-```typescript
-// BEFORE: formContext.getAttribute("name").getValue()
-// AFTER:
-import { AccountMainFormFieldsEnum as Fields } from '../generated/forms/account.js';
-import type { AccountMainForm } from '../generated/forms/account.js';
-const form = ctx.getFormContext() as AccountMainForm;
-form.getAttribute(Fields.AccountName).getValue();  // StringAttribute, typed
-```
-
-### OptionSet Comparison
-```typescript
-// BEFORE: if (status.getValue() === 595300002) { ... }
-// AFTER:
-import { StatusCode } from '../generated/optionsets/invoice.js';
-if (status.getValue() === StatusCode.Gebucht) { ... }
-```
-
-### Testing (onLoad + onChange)
-```typescript
-import { createFormMock, setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
-
-beforeEach(() => setupXrmMock());
-afterEach(() => teardownXrmMock());
-
-// onLoad test:
-const mock = createFormMock<AccountMainForm>({ name: 'Test', statuscode: 0 });
-onLoad(mock.asEventContext());
-expect(mock.getControl(Fields.Revenue).getVisible()).toBe(true);
-
-// onChange test (MANDATORY for every onChange handler):
-mock.setValue(Fields.Revenue, 500000);
-mock.fireOnChange(Fields.Revenue);
-expect(mock.getControl(Fields.CreditLimit).getVisible()).toBe(true);
-expect(mock.getValue(Fields.CreditOnHold)).toBe(true);
-```
-
-**Test quality rule:** At least 30% of tests MUST use `fireOnChange` or WebApi mock
-assertions. Pure smoke tests (`onLoad` + `not.toThrow`) do NOT count as behavior tests.
-Tests that only check `getOnChangeHandlers().length > 0` are registration tests, not
-behavior tests. Every onChange handler MUST have a `fireOnChange` test.
-
-**attr.controls:** Since @xrmforge/testing 0.2.3, `createFormMock()` automatically links
-each attribute to its control. `mock.getControl(Fields.Name)` works out of the box.
-No need to mock controls separately.
-
-## File Structure
-
-```
-src/forms/{entity}-form.ts       - Form scripts (one per entity)
-src/shared/{name}.ts             - Shared utilities
-generated/                       - Generated types (do not edit manually)
-tests/forms/{entity}.test.ts     - Tests
-xrmforge.config.json             - Build config
-```
-
-## Pattern Recognition: Legacy to XrmForge
-
-When you see these patterns in legacy code, apply the XrmForge replacement:
-
-| Legacy Pattern | XrmForge Replacement |
-|---|---|
-| `getAttribute("name")` | `getAttribute(Fields.Name)` |
-| `getControl("name")` | `getControl(Fields.Name)` |
-| `getValue() === 595300000` | `getValue() === OptionSets.StatusCode.Active` |
-| `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
-| `"?$select=name,revenue"` | `select(Fields.Name, Fields.Revenue)` (from @xrmforge/helpers) |
-| `value[0].id.replace("{","")...` | `formLookupId(form.getAttribute(Fields.X))` for forms, `parseLookup(response, 'field')` for Web API |
-| `Xrm.Page.getAttribute(...)` | `formContext.getAttribute(...)` |
-| `var formContext` (global) | `const form = ctx.getFormContext()` (parameter) |
-| `function form_OnLoad(ctx)` | `export function onLoad(ctx: Xrm.Events.EventContext)` |
-| `.then(success, error)` | `async/await with try/catch` |
-
-### Creating OptionSet Enums from Legacy Magic Numbers
-
-When you find magic numbers like `getValue() === 105710002` in legacy code:
-1. Search the file for ALL numeric comparisons with getValue()
-2. Create a const enum in generated/optionsets/ with descriptive names
-3. Import and use the enum instead of the number
-
-Example:
-```typescript
-// generated/optionsets/invoice.ts
-export const enum InvoiceStatusCode {
-  Neu = 1,
-  Versendet = 105710000,
-  Abgeschlossen = 105710001,
-  Gebucht = 105710002,
-}
-
-// In the form script:
-import { InvoiceStatusCode } from '../../generated/optionsets/invoice.js';
-if (status.getValue() === InvoiceStatusCode.Gebucht) { ... }
-```
-
-## Testing with Global Xrm Mock
-
-Use `setupXrmMock()` from @xrmforge/testing to mock the global Xrm namespace:
-```typescript
-import { createFormMock, setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
-
-beforeEach(() => setupXrmMock());
-afterEach(() => teardownXrmMock());
-
-// Override specific WebApi methods:
-setupXrmMock({
-  webApiOverrides: {
-    retrieveMultipleRecords: async () => ({ entities: [{ name: 'Test' }] }),
-  },
-});
-```
-
-## Build
-
-```bash
-npx xrmforge build               # IIFE bundles for D365
-npx xrmforge build --watch        # Watch mode (~10ms rebuilds)
-```
-
-## @types/xrm Pitfalls (known issues)
-
-When creating manual typings without `xrmforge generate`:
-
-1. **Form Interface:** Do NOT use `interface extends Xrm.FormContext` (getAttribute overload conflicts).
-   Use `Omit` pattern instead:
-   ```typescript
-   interface AccountMainForm extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {
-     getAttribute(name: Fields.AccountName): Xrm.Attributes.StringAttribute;
-     getAttribute(name: string): Xrm.Attributes.Attribute;
-     // ...
-   }
-   ```
-
-2. **AlertDialogResponse** does NOT exist in @types/xrm. Use `Xrm.Async.PromiseLike<void>`.
-
-3. **ConfirmDialogResponse** does NOT exist. Use `Xrm.Navigation.ConfirmResult`.
-
-4. **setNotification()** requires 2 arguments: (message, uniqueId).
-
-5. **openFile()** requires `fileSize` property in FileDetails.
-
-6. **const enum in .d.ts files** cannot be imported at runtime by test frameworks.
-   Since v0.8.0, XrmForge generates `.ts` files, so this is no longer an issue.
-   For manual typings, use regular `enum` in `.ts` files (not `.d.ts`).
-
-## Self-Check (MANDATORY before Tests)
-
-After converting ALL scripts, run these checks. Fix every violation before proceeding to tests.
-Document results in SESSION-GEDAECHTNIS.md (violation count per category).
-
-**Platform note:** The checks below use bash/grep syntax. On Windows PowerShell, use
-`Select-String` instead of `grep`. Example:
-```powershell
-# PowerShell equivalent of: grep -rn "getAttribute('" src/forms/ --include="*.ts"
-Get-ChildItem -Recurse src/forms -Filter *.ts | Select-String "getAttribute\('" | Where-Object { $_.Line -notmatch 'Fields\.' }
-```
-
-### Pattern Compliance (all must be 0, or documented exception)
-
-```bash
-# 1. Raw field strings in getAttribute/getControl (must use Fields Enum)
-grep -rn "getAttribute('" src/forms/ --include="*.ts" | grep -v "Fields\."
-grep -rn "getControl('" src/forms/ --include="*.ts" | grep -v "Fields\."
-
-# 2. Magic numbers in OptionSet comparisons (must use OptionSet Enum)
-grep -rn "getValue() ===" src/ --include="*.ts" | grep -E "[0-9]{3,}"
-
-# 3. Direct _value access instead of parseLookup (in Web API responses)
-grep -rn "_value\b" src/ --include="*.ts" | grep -v "generated/" | grep -v "parseLookup" | grep -v "getValue"
-
-# 4. Raw entity names in WebApi calls (must use EntityNames, no exceptions)
-grep -rn "retrieveRecord\|retrieveMultipleRecords\|deleteRecord\|createRecord\|updateRecord" src/ --include="*.ts" | grep "'[a-z]" | grep -v "EntityNames"
-# Every match is a violation. If entity is missing from EntityNames, extend generation.
-
-# 5. Missing select() - no raw "$select=" strings anywhere in src/
-grep -rn '\$select' src/ --include="*.ts" | grep -v "select(" | grep -v "generated/"
-
-# 6. Missing FormContext Cast in onLoad (must have "as <Generated>Form")
-grep -rn "getFormContext()" src/forms/ --include="*.ts" | grep -v " as "
-
-# 7. Exported handlers without wrapHandler
-grep -rn "^export const\|^export async function\|^export function" src/forms/ --include="*.ts" | grep -v "wrapHandler"
-
-# 8. Entity-level FieldsEnums not used (generated/fields/ should be imported)
-echo "Fields imports from generated/fields/:"
-grep -rn "from.*generated/fields/" src/ --include="*.ts" | wc -l
-```
-
-### Code Quality (all must be 0)
-
-```bash
-# console.* outside logger.ts (exclude JSDoc comments)
-grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts" | grep -v "^\s*\*" | grep -v "^\s*//"
-
-# Xrm.Page (deprecated since D365 v9.0, exclude JSDoc comments)
-grep -rn "Xrm\.Page" src/ --include="*.ts" | grep -v "^\s*\*" | grep -v "^\s*//"
-
-# var declarations
-grep -rnE "^\s*var " src/ --include="*.ts"
-
-# eval()
-grep -rn "\beval(" src/ --include="*.ts"
-
-# XMLHttpRequest
-grep -rn "XMLHttpRequest" src/ --include="*.ts"
-
-# as any without eslint-disable comment explaining why
-grep -rn "as any" src/ --include="*.ts" | grep -v "eslint-disable"
-```
-
-### Documentation (all must pass)
-
-```bash
-# Files without JSDoc header (first line must be /**)
-for f in src/forms/*.ts src/shared/*.ts; do
-  head -1 "$f" | grep -q "^/\*\*" || echo "No header: $f"
-done
-
-# Exported functions without JSDoc
-grep -rn -B1 "^export " src/ --include="*.ts" | grep -E "^[^*]*export" | grep -v "/\*\*"
-```
-
-### Test Completeness
-
-```bash
-# Every form script needs a test file
-for f in src/forms/*.ts; do
-  base=$(basename "$f" .ts)
-  test -f "tests/forms/${base}.test.ts" || echo "No test: $f"
-done
-
-# Every test file must use setupXrmMock
-for f in tests/**/*.test.ts; do
-  grep -q "setupXrmMock" "$f" || echo "No setupXrmMock: $f"
-done
-
-# Every test file needs at least 2 test cases
-for f in tests/**/*.test.ts; do
-  count=$(grep -c "it(" "$f" 2>/dev/null || echo 0)
-  [ "$count" -lt 2 ] && echo "Only $count tests: $f"
-done
-```
-
-### Test Gap Analysis (after writing tests)
-
-Before declaring tests complete, verify coverage gaps:
-
-```bash
-# 1. onChange handlers without fireOnChange test
-for f in tests/**/*.test.ts; do
-  has_onchange=$(grep -c "onChange\|on_change\|OnChange" "$(echo $f | sed 's|tests/|src/|;s|.test.ts|.ts|')" 2>/dev/null || echo 0)
-  has_fire=$(grep -c "fireOnChange" "$f" 2>/dev/null || echo 0)
-  [ "$has_onchange" -gt 0 ] && [ "$has_fire" -eq 0 ] && echo "Missing fireOnChange: $f"
-done
-
-# 2. WebApi calls without mock assertions
-grep -rln "Xrm.WebApi\|retrieveRecord\|retrieveMultiple" src/forms/ --include="*.ts" | while read f; do
-  test_f="tests/forms/$(basename "$f" .ts).test.ts"
-  [ -f "$test_f" ] && ! grep -q "retrieveRecord\|retrieveMultiple\|webApiOverrides" "$test_f" && echo "No WebApi mock: $test_f"
-done
-
-# 3. Behavior test ratio (target: >= 30%)
-total=$(grep -rc "it(" tests/ --include="*.test.ts" 2>/dev/null | awk -F: '{s+=$2}END{print s}')
-behavior=$(grep -rc "fireOnChange\|retrieveRecord\|retrieveMultiple\|expect.*getValue\|expect.*getVisible" tests/ --include="*.test.ts" 2>/dev/null | awk -F: '{s+=$2}END{print s}')
-echo "Behavior tests: $behavior / $total (target: >= 30%)"
-```
-
-### Exceptions
-
-Some checks have legitimate exceptions:
-- **Raw field strings in helpers**: Generic helper functions that accept `fieldName: string` parameters cannot use Fields Enums. Document these.
-- **System entities not in EntityNames**: Entities not in the Solution (e.g. `annotation`, `transactioncurrency`, `systemuser`) may use string literals. Document which ones.
-- **as any for Grid.refresh()**: `@types/xrm` does not type `Grid.refresh()`. Requires eslint-disable with explanation.
-
-## Full Migration Guide
-
-See: https://www.npmjs.com/package/@xrmforge/typegen (MIGRATION.md)
+# XrmForge - AI Agent Instructions
+
+This file helps AI coding assistants write optimal Dynamics 365 form scripts.
+
+## Packages
+
+- `@xrmforge/typegen` - Generates typed declarations from Dataverse metadata (Node.js CLI only, NEVER import in browser code)
+- `@xrmforge/helpers` - Browser-safe runtime: typedForm(), select(), parseLookup(), formLookup(), Xrm constants, Action executors
+- `@xrmforge/testing` - Type-safe form mocks: createFormMock(), fireOnChange(), setupXrmMock()
+- `@xrmforge/devkit` - esbuild IIFE bundles via xrmforge build
+- `@xrmforge/eslint-plugin` - D365-specific ESLint rules
+
+## Generated Types (generated/ directory)
+
+Run `xrmforge generate` to create:
+- `generated/forms/{entity}.ts` - Form interface + Fields/Tabs/Sections/Subgrids enums
+- `generated/optionsets/{entity}.ts` - OptionSet const enums
+- `generated/entities/{entity}.ts` - Entity interface (for Web API response typing)
+- `generated/fields/{entity}.ts` - Entity Fields enum for type-safe $select queries
+- `generated/entity-names.ts` - EntityNames const enum
+- `generated/actions/global.ts` - Custom API Action executors (typed params + results)
+- `generated/functions/global.ts` - Custom API Function executors
+- `generated/form-mapping.json` - Entity to form interface mapping (read after generate!)
+- `generated/index.ts` - Barrel file with `export * from` re-exports
+
+**After generate:** Read `generated/form-mapping.json` for the mapping of entity logical
+names to form interface names. Do NOT guess interface names from entity names.
+Fields enum member names are based on the **primary language label** (often German),
+not the logical field name. Always read the generated files to get correct names.
+
+**System entities:** If a form script needs an entity NOT in the generated EntityNames
+(e.g. transactioncurrency, pricelevel, uom, systemuser), re-run generate with
+`--entities transactioncurrency,pricelevel,...` to include them. NEVER create a local
+`SystemEntities` object with raw strings as a workaround.
+
+## Rules: MANDATORY (every violation is a bug)
+
+### 1. typedForm() for ALL field access (primary pattern)
+
+Use `typedForm<FormInterface>(formContext)` from `@xrmforge/helpers` to create a
+typed proxy. Access fields as direct properties instead of getAttribute chains.
+
+```typescript
+import { typedForm } from '@xrmforge/helpers';
+import type { AccountLMFirmaForm } from '../../generated/forms/account.js';
+import { AccountLMFirmaFormFieldsEnum as Fields } from '../../generated/forms/account.js';
+
+export const onLoad = wrapHandler('LM.Account.onLoad', logger, (ctx) => {
+  const form = typedForm<AccountLMFirmaForm>(ctx.getFormContext());
+
+  // Direct field access - fully typed, IDE autocomplete works
+  const name = form.name.getValue();              // string | null
+  form.revenue.setValue(150000);                   // NumberAttribute
+  const parent = form.parentaccountid.getValue();  // LookupValue[] | null
+
+  // Control access
+  form.$control('name').setDisabled(true);
+
+  // Full FormContext for ui, data, tabs, addOnChange
+  form.$context.ui.setFormNotification('OK', FormNotificationLevel.Info, 'id');
+  form.$context.getAttribute(Fields.Name).addOnChange(() => { ... });
+});
+```
+
+**When to use `form.$context.getAttribute(Fields.X)` instead of `form.fieldname`:**
+- `addOnChange()`, `removeOnChange()` (event registration on the attribute)
+- `setRequiredLevel()`, `setSubmitMode()` (attribute-level settings)
+- `getControl()` with typed control access (use `form.$control(Fields.X)`)
+
+**When to use `form.fieldname` (the typedForm proxy):**
+- `getValue()`, `setValue()` (reading and writing values)
+- Any read-only access to field values
+
+### 2. Fields Enum for ALL getAttribute/getControl AND select() calls
+
+Two types of Fields enums exist:
+- **Form-level**: `AccountLMFirmaFormFieldsEnum` (from `generated/forms/`) - for getAttribute/getControl on the form
+- **Entity-level**: `AccountFields` (from `generated/fields/`) - for Web API $select queries
+
+```typescript
+// Form field access (form-level Fields):
+import { AccountLMFirmaFormFieldsEnum as Fields } from '../../generated/forms/account.js';
+form.$context.getAttribute(Fields.Name).addOnChange(() => { ... });
+
+// Web API queries (entity-level Fields):
+import { AccountFields } from '../../generated/fields/account.js';
+Xrm.WebApi.retrieveRecord(EntityNames.Account, id,
+  select(AccountFields.Name, AccountFields.WebsiteUrl));
+```
+
+**NEVER use raw strings in select():**
+```typescript
+select('name', 'websiteurl')                     // BUG - raw strings
+select(AccountFields.Name, AccountFields.WebsiteUrl) // CORRECT
+```
+
+### 3. OptionSet Enum for ALL value comparisons AND FetchXML
+
+Never use magic numbers. Not in comparisons, not in FetchXML, not anywhere.
+
+```typescript
+import { InvoiceStatusCode } from '../../generated/optionsets/invoice.js';
+
+// Comparisons:
+if (status === InvoiceStatusCode.Gebucht) { ... }     // CORRECT
+if (status === 105710002) { ... }                       // BUG
+
+// FetchXML:
+`<condition attribute='${InvoiceFields.Statuscode}' operator='in'>
+  <value>${InvoiceStatusCode.Aktiv}</value>
+  <value>${InvoiceStatusCode.Gebucht}</value>
+</condition>`                                          // CORRECT
+
+`<condition attribute='statuscode' operator='in'>
+  <value>1</value><value>105710002</value>
+</condition>`                                          // BUG - raw strings AND magic numbers
+```
+
+### 4. EntityNames Enum in ALL Xrm.WebApi calls
+
+No exceptions, even for system entities. If missing, extend generation.
+
+```typescript
+import { EntityNames } from '../../generated/entity-names.js';
+Xrm.WebApi.retrieveRecord(EntityNames.Account, id, query);
+```
+
+### 5. Lookup helpers from @xrmforge/helpers
+
+```typescript
+import { formLookup, formLookupId, parseLookup } from '@xrmforge/helpers';
+// Form (via typedForm proxy):
+const customer = formLookup(form.parentaccountid);
+const customerId = formLookupId(form.parentaccountid);
+// Web API response (use NavigationProperties enum, NOT raw strings):
+import { AccountNavigationProperties as AccountNav } from '../../generated/entities/account.js';
+const parent = parseLookup(apiResponse, AccountNav.ParentAccountId);
+```
+
+### 6. select(), $filter, $expand, $orderby with Fields Enums
+
+ALL OData query parts must use entity-level Fields Enums. No raw field name strings anywhere.
+
+```typescript
+import { select, selectExpand } from '@xrmforge/helpers';
+import { AccountFields } from '../../generated/fields/account.js';
+
+// $select:
+select(AccountFields.Name, AccountFields.Revenue)
+
+// $filter (field names via template literal):
+`${select(AccountFields.Name)}&$filter=${AccountFields.Statecode} eq 0`
+
+// $expand (navigation properties):
+selectExpand(
+  [AccountFields.Name, AccountFields.Revenue],
+  `primarycontactid($select=${ContactFields.Fullname})`,
+)
+
+// $orderby:
+`${select(AccountFields.Name)}&$orderby=${AccountFields.Name} asc`
+```
+
+### 6b. Web API response typing with generated Entity interfaces
+
+Always type Web API responses with generated Entity interfaces. Never access properties with `as string` casts.
+
+```typescript
+import type { Account } from '../../generated/entities/account.js';
+
+const result = await Xrm.WebApi.retrieveRecord(
+  EntityNames.Account, id, select(AccountFields.Name)
+) as Account;
+result.name  // typed as string | null, no cast needed
+```
+
+### 7. wrapHandler() around EVERY exported handler
+
+```typescript
+export const onLoad = wrapHandler('Namespace.Entity.onLoad', logger, async (ctx) => {
+  const form = typedForm<MyForm>(ctx.getFormContext());
+  // ...
+});
+```
+
+### 8. Custom API Executors from generated/actions/
+
+Never build your own ExecuteFunctionCall wrapper. Use the generated executors:
+
+```typescript
+import { CreateEMailFromInvoice } from '../../generated/actions/global.js';
+import { withProgress } from '@xrmforge/helpers';
+
+const result = await withProgress(
+  CreateEMailFromInvoice.execute({ InvoiceId: recordId }),
+  { title: 'E-Mail wird erstellt...' }
+);
+// result.EmailId is typed as string
+```
+
+### 9. Named constants for ALL non-obvious values
+
+```typescript
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+form.lm_zahlungsziel.setValue(new Date(date.getTime() + days * MS_PER_DAY));
+// NEVER: new Date(date.getTime() + days * 86400000)
+```
+
+### 10. Localized UI strings via pickLang()
+
+All user-visible strings MUST go through `pickLang()` in constants.ts:
+
+```typescript
+// constants.ts:
+export const MESSAGES = {
+  de: { titlePlaceholder: '[Kurzbeschreibung der Anfrage]' },
+  en: { titlePlaceholder: '[Brief description]' },
+} as const;
+export function pickLang<K extends string>(languageId: number, table: { de: Record<K, string>; en: Record<K, string> }): Record<K, string>;
+
+// form script:
+import { MESSAGES, pickLang } from '../shared/constants.js';
+const lang = pickLang(Xrm.Utility.getGlobalContext().userSettings.languageId, MESSAGES);
+form.title.setValue(lang.titlePlaceholder);
+```
+
+### 11. Tabs, Sections, Subgrids via generated enums
+
+Never use raw strings for tab, section, or subgrid names:
+
+```typescript
+import { AccountLMFirmaFormTabs as Tabs } from '../../generated/forms/account.js';
+import { AccountLMFirmaFormSUMMARYTABSections as SummarySections } from '../../generated/forms/account.js';
+import { AccountLMFirmaFormSubgrids as Subgrids } from '../../generated/forms/account.js';
+
+form.$context.ui.tabs.get(Tabs.SUMMARYTAB).setVisible(true);
+form.$context.ui.tabs.get(Tabs.SUMMARYTAB).sections.get(SummarySections.General).setVisible(false);
+(form.$context.getControl(Subgrids.Orders) as Xrm.Controls.GridControl).refresh();
+```
+
+### 12. Notification IDs from NOTIFICATION_IDS
+
+All notification unique IDs must be in `constants.ts`, never inline raw strings:
+
+```typescript
+// constants.ts:
+export const NOTIFICATION_IDS = {
+  genericError: 'lmapp.notification.generic-error',
+  saveWarning: 'lmapp.notification.save-warning',
+  addressMissing: 'lmapp.notification.address-missing',
+} as const;
+
+// form script:
+form.$context.ui.setFormNotification(msg, FormNotificationLevel.Error, NOTIFICATION_IDS.genericError);
+```
+
+### 13. Xrm constants from @xrmforge/helpers for ALL Xrm enum values
+
+Never use raw strings or magic numbers for Xrm API constants:
+
+```typescript
+import { SaveMode, FormNotificationLevel, RequiredLevel, SubmitMode, DisplayState } from '@xrmforge/helpers';
+
+// Save mode:
+if (ctx.getEventArgs().getSaveMode() === SaveMode.AutoSave) { ... }  // not === 70
+
+// Form type (const enum from @types/xrm, works at runtime):
+if (form.$context.ui.getFormType() === XrmEnum.FormType.Create) { ... }  // not === 1
+
+// Display state:
+if (tab.getDisplayState() === DisplayState.Expanded) { ... }  // not === 'expanded'
+
+// Required level:
+form.$context.getAttribute(Fields.Name).setRequiredLevel(RequiredLevel.Required);  // not 'required'
+
+// Submit mode:
+form.$context.getAttribute(Fields.Name).setSubmitMode(SubmitMode.Always);  // not 'always'
+
+// Notification level:
+form.$context.ui.setFormNotification(msg, FormNotificationLevel.Error, id);  // not 'ERROR'
+```
+
+### 14. EntityNames in openForm and ALL entity references
+
+```typescript
+// openForm:
+Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  // not "account"
+
+// openWebResource, openUrl, etc.: use EntityNames wherever an entity name appears
+```
+
+### 15. Module exports, Structured Logger, createFormMock
+
+- Module exports (not window/global assignments). esbuild globalName handles namespacing.
+- `createLogger()` instead of console.* (except in logger.ts itself)
+- `createFormMock()` from @xrmforge/testing for ALL form tests
+
+## Rules: NEVER (every occurrence is a bug)
+
+**Field/Entity/Resource names:**
+- Never raw strings in `getAttribute()`, `getControl()`, `select()`, `$filter`, `$expand`, `$orderby`, `parseLookup()`, FetchXML `attribute=`, or any function that takes a field name
+- Never raw entity name strings in `Xrm.WebApi`, `Xrm.Navigation.openForm`, or anywhere an entity name appears (use `EntityNames`)
+- Never raw tab/section/subgrid names (use generated Tabs/Sections/Subgrids enums)
+- Never raw notification IDs (use `NOTIFICATION_IDS` from constants.ts)
+- Never create `SystemEntities` objects with raw strings (extend generation with `--entities`)
+
+**Magic values:**
+- Never magic numbers for OptionSet values, status codes, or FetchXML `<value>` (use OptionSet Enums)
+- Never magic numbers for time calculations (use named constants like `MS_PER_DAY`)
+- Never `getSaveMode() === 70` (use `SaveMode.AutoSave` from @xrmforge/helpers)
+- Never `getFormType() === 1` (use `XrmEnum.FormType.Create`)
+- Never `'expanded'`/`'collapsed'` (use `DisplayState` from @xrmforge/helpers)
+- Never `'ERROR'`/`'INFO'`/`'WARNING'` (use `FormNotificationLevel`)
+- Never `'none'`/`'required'`/`'recommended'` (use `RequiredLevel`)
+- Never `'always'`/`'dirty'` (use `SubmitMode`)
+
+**Web API responses:**
+- Never access WebApi response properties with `as string` casts (use generated Entity interfaces)
+- Never `.getValue()[0].id` for lookups (use `formLookup`/`formLookupId`)
+- Never raw strings in `parseLookup()` (use NavigationProperties enum)
+
+**Code quality:**
+- Never `Xrm.Page` (deprecated since D365 v9.0)
+- Never `eval()`, never synchronous XMLHttpRequest
+- Never `window.X = ...` (use module exports)
+- Never `console.log/warn/error` in form scripts (use shared logger)
+- Never export handlers without `wrapHandler()`
+- Never unlokalized UI strings (use `pickLang()` from constants.ts)
+- Never build your own getValue/setFieldValue/setDisabled/addOnChange helpers (use `typedForm` + native Xrm API)
+- Never `import ... from '@xrmforge/typegen'` in browser code (use `@xrmforge/helpers`)
+- Never `as any` without eslint-disable comment explaining why
+- Never untyped `catch (error)` (always `catch (error: unknown)`)
+
+## Subagent Handoff (when delegating to sub-agents)
+
+Copy these MANDATORY rules into every sub-agent prompt:
+
+```
+1. typedForm<FormType>(ctx.getFormContext()) for ALL field access
+2. Entity-level Fields Enums in ALL select(), $filter, $expand, $orderby, FetchXML attribute=
+3. OptionSet Enum for ALL value comparisons AND FetchXML <value> (never magic numbers)
+4. EntityNames for ALL Xrm.WebApi calls AND openForm (never raw entity names)
+5. formLookup/formLookupId for ALL lookup access (never .getValue()[0].id)
+6. parseLookup with NavigationProperties enum (never raw nav property strings)
+7. Generated Entity interfaces for ALL WebApi response typing (never as string casts)
+8. Tabs/Sections/Subgrids enums for ALL UI structure access (never raw strings)
+9. SaveMode/FormType/DisplayState/RequiredLevel/SubmitMode/FormNotificationLevel constants
+10. wrapHandler() around EVERY exported handler
+11. createLogger() instead of console.* (except logger.ts)
+12. Custom API Executors from generated/actions/ (never build your own)
+13. NOTIFICATION_IDS from constants.ts for all notification unique IDs
+14. Named constants for non-obvious values (never magic numbers like 86400000)
+15. pickLang() for all user-visible strings (never hardcoded German/English)
+```
+
+## Mandatory Shared Utilities
+
+Every XrmForge project MUST have these in `src/shared/`:
+
+### logger.ts
+```typescript
+export interface Logger { debug(msg: string, data?: unknown): void; info(...); warn(...); error(...); }
+export function createLogger(namespace: string): Logger;
+// Only file allowed to use console.*
+```
+
+### error-handler.ts
+```typescript
+export function wrapHandler(name: string, logger: Logger, handler: EventHandler): EventHandler;
+export function wrapCommand(name: string, logger: Logger, handler: CommandHandler): CommandHandler;
+// Catches sync+async errors, shows form notification via FormNotificationLevel.Error
+```
+
+### constants.ts
+```typescript
+export const NOTIFICATION_IDS = { ... } as const;
+export const MESSAGES = { de: { ... }, en: { ... } } as const;
+export function pickLang<K extends string>(languageId: number, table: ...): Record<K, string>;
+```
+
+## Before/After Examples
+
+### Field Access (primary pattern: typedForm)
+```typescript
+// BEFORE (legacy):
+formContext.getAttribute("name").getValue()
+// BEFORE (getAttribute + Fields):
+form.getAttribute(Fields.Name).getValue()
+// AFTER (typedForm - preferred):
+const form = typedForm<AccountForm>(ctx.getFormContext());
+form.name.getValue()
+```
+
+### Web API Query
+```typescript
+// BEFORE:
+Xrm.WebApi.retrieveRecord("account", id, "?$select=name,revenue")
+// AFTER:
+import { AccountFields } from '../../generated/fields/account.js';
+Xrm.WebApi.retrieveRecord(EntityNames.Account, id,
+  select(AccountFields.Name, AccountFields.Revenue))
+```
+
+### OptionSet Comparison
+```typescript
+// BEFORE: if (status.getValue() === 595300002) { ... }
+// AFTER:
+import { StatusCode } from '../../generated/optionsets/invoice.js';
+if (form.statuscode.getValue() === StatusCode.Gebucht) { ... }
+```
+
+### FetchXML
+```typescript
+// BEFORE:
+`<condition attribute='statuscode' operator='in'><value>1</value><value>105710000</value></condition>`
+// AFTER:
+import { LmBestellungFields } from '../../generated/fields/lm_bestellung.js';
+import { LmBestellungStatusCode } from '../../generated/optionsets/lm_bestellung.js';
+`<condition attribute='${LmBestellungFields.Statuscode}' operator='in'>
+  <value>${LmBestellungStatusCode.Aktiv}</value>
+  <value>${LmBestellungStatusCode.InArbeit}</value>
+</condition>`
+```
+
+### Lookup Access
+```typescript
+// BEFORE: form.getAttribute("customerid").getValue()[0].id.replace("{","").replace("}","")
+// AFTER:
+const customerId = formLookupId(form.customerid);
+```
+
+### Custom API Call
+```typescript
+// BEFORE: ExecuteFunctionCall("CancelInvoice", { InvoiceId: id })
+// AFTER:
+import { CancelInvoice } from '../../generated/actions/global.js';
+const result = await withProgress(
+  CancelInvoice.execute({ InvoiceId: id }),
+  { title: 'Rechnung wird storniert...' }
+);
+```
+
+### Date Calculation
+```typescript
+// BEFORE: new Date(date.getTime() + nettotage * 86400000)
+// AFTER:
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+new Date(date.getTime() + nettotage * MS_PER_DAY)
+```
+
+### UI Strings
+```typescript
+// BEFORE: form.title.setValue('[Kurzbeschreibung der Anfrage]')
+// AFTER:
+const lang = pickLang(Xrm.Utility.getGlobalContext().userSettings.languageId, MESSAGES);
+form.title.setValue(lang.titlePlaceholder);
+```
+
+## Testing (onLoad + onChange)
+
+```typescript
+import { createFormMock, setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
+
+beforeEach(() => setupXrmMock());
+afterEach(() => teardownXrmMock());
+
+// onLoad test:
+const mock = createFormMock<AccountMainForm>({ name: 'Test', statuscode: 0 });
+onLoad(mock.asEventContext());
+expect(mock.getControl(Fields.Revenue).getVisible()).toBe(true);
+
+// onChange test (MANDATORY for every onChange handler):
+mock.setValue(Fields.Revenue, 500000);
+mock.fireOnChange(Fields.Revenue);
+expect(mock.getControl(Fields.CreditLimit).getVisible()).toBe(true);
+```
+
+**Test quality rule:** At least 30% of tests MUST use `fireOnChange` or WebApi mock
+assertions. Pure smoke tests (`onLoad` + `not.toThrow`) do NOT count.
+Every onChange handler MUST have a `fireOnChange` test.
+
+**attr.controls:** Since @xrmforge/testing 0.2.3, `createFormMock()` automatically links
+each attribute to its control. `mock.getControl(Fields.Name)` works out of the box.
+
+## Pattern Recognition: Legacy to XrmForge
+
+| Legacy Pattern | XrmForge Replacement |
+|---|---|
+| `getAttribute("name")` | `form.name` (via typedForm) or `getAttribute(Fields.Name)` |
+| `getControl("name")` | `form.$control(Fields.Name)` |
+| `getValue() === 595300000` | `form.statuscode.getValue() === StatusCode.Active` |
+| `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
+| `"?$select=name,revenue"` | `select(AccountFields.Name, AccountFields.Revenue)` |
+| `value[0].id.replace("{","")` | `formLookupId(form.customerid)` |
+| `Xrm.Page.getAttribute(...)` | `form.fieldname` (via typedForm) |
+| `var formContext` (global) | `const form = typedForm<MyForm>(ctx.getFormContext())` |
+| `function form_OnLoad(ctx)` | `export const onLoad = wrapHandler(...)` |
+| `ExecuteFunctionCall("name", ...)` | `import { Name } from '../../generated/actions/global.js'` |
+| `setFormNotification(msg, 'ERROR', id)` | `setFormNotification(msg, FormNotificationLevel.Error, id)` |
+| `86400000` | `const MS_PER_DAY = 24 * 60 * 60 * 1000` |
+| `'[Kurzbeschreibung]'` | `pickLang(languageId, MESSAGES).placeholder` |
+
+## @types/xrm Pitfalls (known issues)
+
+1. **Form Interface:** Do NOT use `interface extends Xrm.FormContext`. Use `Omit` pattern.
+2. **AlertDialogResponse** does NOT exist. Use `Xrm.Async.PromiseLike<void>`.
+3. **ConfirmDialogResponse** does NOT exist. Use `Xrm.Navigation.ConfirmResult`.
+4. **setNotification()** requires 2 arguments: (message, uniqueId).
+5. **openFile()** requires `fileSize` property in FileDetails.
+6. **Grid.refresh()** requires `(grid as any).refresh()` with eslint-disable comment.
+
+## Build
+
+```bash
+npx xrmforge build               # IIFE bundles for D365
+npx xrmforge build --watch        # Watch mode (~10ms rebuilds)
+```
+
+## File Structure
+
+```
+src/forms/{entity}-form.ts       - Form scripts (one per entity)
+src/shared/logger.ts             - Structured logger (only file with console.*)
+src/shared/error-handler.ts      - wrapHandler + wrapCommand
+src/shared/constants.ts          - NOTIFICATION_IDS, MESSAGES, pickLang
+generated/                       - Generated types (do not edit manually)
+tests/forms/{entity}.test.ts     - Tests
+xrmforge.config.json             - Build config
+scripts/validate-form.mjs        - Quality gate (run after each batch)
+```
+
+## Self-Check (MANDATORY before Tests)
+
+Run `node scripts/validate-form.mjs` after every batch. Must report 0 violations.