devendra-skill-package 1.0.2

package/.github/skills/validation-engine-builder/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: validation-engine-builder
+description: Apply centralized form validation to any screen, page, component, or widget across React Native, React (web), Angular, or Flutter. AI detects the target platform, reads the file, identifies every input field, reasons about the correct validation rules for each field, updates the central messages/regex/schema templates, and rewires the file with that platform's native form-validation mechanism (react-hook-form+Yup for React Native/React, Angular Reactive Forms Validators for Angular, TextFormField.validator for Flutter). All error messages in one file, all regex in one file, one shared schema template drives every platform. Use this skill when the user wants to add validation to a screen, page, form, login, signup, OTP, profile, address, or any input-based UI on any of the 4 supported platforms.
+---
+
+# Validation Engine — Multi-Platform (AI-Driven)
+
+This skill is AI-driven. The agent detects the platform, reads the target file, reasons about each
+field, and applies validation directly. Do NOT rely on a script to analyze or wire an existing
+screen/page/component/widget — the AI does the field analysis and file integration.
+
+The scripts in this skill are for:
+1. Detecting which of the 4 supported platforms the target project is
+2. Installing compatible dependencies (React Native / React only — Angular and Flutter need none)
+3. Regenerating the platform's validation output files after templates are updated
+
+---
+
+## Supported platforms
+
+| Platform | Detection signal | Reference file |
+|---|---|---|
+| React Native | `package.json` has a `react-native` dependency | `references/platform-react-native.md` |
+| React (web) | `package.json` has `react` + `react-dom`, no `react-native` | `references/platform-react.md` |
+| Angular | `angular.json` at the project root | `references/platform-angular.md` |
+| Flutter | `pubspec.yaml` with a `flutter:` SDK entry | `references/platform-flutter.md` |
+
+Do not generate for a platform outside this list — there is no reference file for it, and
+generating from memory for an unsupported platform (Vue, native Android/iOS, a backend framework)
+is exactly the kind of unverified assumption this skill exists to avoid. Say so explicitly instead.
+
+## When this skill applies
+
+- User asks to add validation to a screen, page, form, or component
+- User provides a file path to a screen/page/component/widget, or has one open
+- User mentions fields like email, password, phone, OTP, name, address, date
+- User wants form error messages centralized so they can be changed in one place
+
+---
+
+## STOP — READ REFERENCE FILES BEFORE ANY CODE
+
+Always read, in this order:
+
+```
+.github/skills/validation-engine-builder/references/core.md
+.github/skills/validation-engine-builder/references/platform-[detected-platform].md
+```
+
+- `core.md` — platform-agnostic: field-type detection quick-reference, available regex/message/
+  schema keys, golden rules. Applies identically on every platform, always read first.
+- Exactly **one** `platform-*.md` file — the concrete wiring pattern (Controller vs `register()`
+  vs `FormGroup` vs `TextFormField.validator`), dependency table, and per-field props for the
+  platform detected below.
+
+---
+
+## Full AI workflow (follow every step in order)
+
+### Step 1 — Detect the platform
+
+Check, in this order, and stop at the first match:
+
+1. `pubspec.yaml` at the project root with a `flutter:` entry under `dependencies` → **Flutter**
+2. `angular.json` at the project root → **Angular**
+3. `package.json`: `react-native` in `dependencies`/`devDependencies` → **React Native**
+4. `package.json`: `react` + `react-dom` present, `react-native` absent → **React (web)**
+
+If more than one signal matches (a monorepo containing more than one app) or none match, **ask the
+user** which platform this request targets — never guess. State the detected (or confirmed)
+platform before proceeding, and load exactly that one `platform-*.md` file for the rest of this
+request.
+
+### Step 2 — Read the target file
+
+Read the screen/page/component/widget file the user provided or currently has open. Identify every
+input field:
+- React Native: `TextInput` components
+- React (web): `<input>`/`<select>`/`<textarea>` elements
+- Angular: template `<input>` elements bound via `formControlName`, or the component's
+  `FormGroup`/`FormControl` declarations
+- Flutter: `TextFormField` widgets
+
+For each, record the variable/control name, placeholder/label text, and surrounding context
+(label, comment). Build a field list:
+```
+fieldName | placeholder/label | inferred type
+email     | "Email address"   | email
+password  | "Password"        | password
+phone     | "Mobile number"   | phone
+```
+Use `core.md`'s field-type detection quick-reference table for the inference — it is identical on
+every platform.
+
+### Step 3 — Check / install dependencies (platform-conditional)
+
+**React Native / React (web)**: read `package.json`. Check if `react-hook-form`,
+`@hookform/resolvers`, `yup` are present. If any are missing, run:
+```powershell
+node .github/skills/validation-engine-builder/scripts/install-deps.js --projectPath <path> --platform <react-native|react>
+```
+The script installs version-compatible packages — see `platform-react-native.md`'s dependency
+table (React web uses the same table with no RN-version gate).
+
+**Angular / Flutter**: nothing to install. Angular's Reactive Forms ships with `@angular/forms`;
+Flutter's `TextFormField.validator` needs no package. Confirm this and move on — do not run
+`install-deps.js` for these two platforms (it will no-op with an explanatory message if run anyway).
+
+### Step 4 — Determine validation rules for each field
+
+For every field identified in Step 2, decide the rules using `core.md`'s field-type table:
+
+| Field type | Rules to apply |
+|---|---|
+| `email` | required, regex: email |
+| `password` | required, min: 8 — add `regex: password` + `regexMessage: passwordStrength` for signup/register screens; omit regex for login |
+| `confirmPassword` | required, min: 8 — note: must match password (see the platform file's cross-field section — this is never expressible in `schemas.json`) |
+| `phone` / `mobile` | required, regex: phone (10 digits) |
+| `otp` | required, regex: otp (6 digits) |
+| `name` / `fullName` / `firstName` / `lastName` | required, min: 2, regex: name |
+| `postalCode` / `zipCode` | required, regex: postalCode (generic 6-digit, allows leading zero) |
+| `pincode` (India) | required, regex: pincode (6-digit, non-zero start — use this instead of postalCode for Indian pincodes) |
+| `url` / `website` | optional, regex: url |
+| `alphanumeric` field | required, regex: alphanumeric |
+| `date` / `dob` / `dateOfBirth` | required, regex: date |
+| Generic required text | required, min: 2 |
+| Generic optional text | nullable |
+| Number input | type: number, required |
+
+Cross-reference `templates/regex.json` — only reference regex keys that exist there.
+Cross-reference `templates/messages.json` — only reference message keys that exist there.
+If a new regex or message is needed, add it to the templates first (Step 5).
+
+This step is identical across all 4 platforms — the field-rule shape (`type`/`required`/`min`/
+`max`/`regex`/`regexMessage`/`nullable`/`label`) is the shared contract that every platform's
+generator compiles from.
+
+### Step 5 — Update templates if needed
+
+**Only** update templates when a new validation type is needed that is not already covered by an
+existing key — check `core.md`'s available-keys tables first.
+
+#### 5a. Add missing message to `templates/messages.json`
+Add the new message key with a clear string value. Never duplicate existing keys.
+For required-field messages, use `{{field}}` placeholder, e.g. `"required": "{{field}} is required"`.
+
+#### 5b. Add missing regex to `templates/regex.json`
+Add the new regex key with a valid JSON-escaped regex string. Use double-escaped backslashes (`\\d`
+for `\d`). Never duplicate existing keys. The same pattern string compiles into every platform's
+target language (`RegExp` in TS, `RegExp` in Dart) — verify it doesn't rely on a JS-only regex
+feature Dart's engine lacks if adding something unusual (lookahead/lookbehind are both fine; Dart
+supports them).
+
+#### 5c. Add or update schema in `templates/schemas.json`
+
+Check if a schema already exists that matches the target fields — reuse the key if so. Field
+definition format:
+
+```json
+"screenNameForm": {
+  "email": { "type": "string", "required": true, "regex": "email", "label": "Email" },
+  "password": { "type": "string", "required": true, "min": 8, "label": "Password" }
+}
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `type` | `"string"` or `"number"` | Base type |
+| `required` | `boolean` | Field must have a value |
+| `min` | `number` | Minimum length (string) or minimum value (number) |
+| `max` | `number` | Maximum length (string) or maximum value (number) |
+| `regex` | `string` | Key from `regex.json` |
+| `regexMessage` | `string` | Key from `messages.json` for the regex error (defaults to the regex key name) |
+| `nullable` | `boolean` | Field may be empty/absent |
+| `label` | `string` | Human-readable field name (used in the required message) |
+
+### Step 6 — Regenerate the validation output
+
+```powershell
+node .github/skills/validation-engine-builder/scripts/apply-to-project.js --projectPath <path> --platform <react-native|react|angular|flutter>
+```
+
+This regenerates the platform's validation output only (see the platform file for the exact output
+location and file list) — it does not scaffold or rewrite the target screen/page/component itself.
+
+### Step 7 — Rewire the target file with validation wired
+
+Rewrite the file using the wiring pattern documented in the detected platform's reference file:
+
+- **React Native**: `Controller` from `react-hook-form` + `useValidatedForm` + `ValidationError` — see `platform-react-native.md`
+- **React (web)**: `register()` from `react-hook-form` (not `Controller` — native `<input>` doesn't need it) + `useValidatedForm` + `ValidationError` — see `platform-react.md`
+- **Angular**: `FormBuilder`/`FormGroup` built in the constructor body (never a field initializer — see the ordering warning in `platform-angular.md`) + `Validators` + `<app-validation-error>` — see `platform-angular.md`
+- **Flutter**: `TextFormField.validator` pointing at the matching static validator method, wrapped in a `Form` + `GlobalKey<FormState>` — see `platform-flutter.md`
+
+Each platform file's "optional screen/page scaffold generator" section documents a `generateScreen()`
+helper for brand-new files; for an existing file, wire it by hand following the same pattern instead
+of overwriting it.
+
+---
+
+## Strict rules (MUST follow — every platform)
+
+1. Never hardcode any error message string in a component — all strings from the generated
+   messages module (`VALIDATION_MESSAGES` in TS, `ValidationMessages` in Dart).
+2. Never hardcode any regex in a component — all patterns from the generated regex module
+   (`VALIDATION_REGEX` in TS, `ValidationRegex` in Dart).
+3. Reuse existing schemas — check `templates/schemas.json` before creating a new schema key.
+4. Never edit the generated output files directly — edit `templates/*.json` and re-run
+   `apply-to-project.js`. The one documented exception is a cross-field validator (confirmPassword,
+   etc.) — see the platform file for where that goes; each platform has its own answer since none
+   of them can express cross-field rules in the shared JSON template.
+5. Never duplicate a schema — if an existing schema key covers the fields, reuse it.
+6. Adjust relative import paths based on the target file's actual location — compute this from the
+   real project structure (see the platform file's generator notes), never a fixed assumption.
+7. See the loaded platform file for additional platform-specific strict rules (e.g. always use
+   `Controller` on React Native; never build a `FormGroup` in an Angular field initializer).
+
+---
+
+## Reusing validation across multiple screens/pages/components
+
+If two files share the same fields (e.g. two login screens, an admin login and a user login), use
+the same schema key for both — do not create a duplicate schema. The validation rules and messages
+are identical and stay in sync automatically. See the platform file's "Reusing the same validation"
+section for the exact syntax on that platform.
+
+---
+
+## After applying validation, verify
+
+Universal (every platform):
+1. No hardcoded error strings remain in the target file.
+2. Every input field has validation wired and a corresponding error-message display (or, on
+   Flutter, relies on `TextFormField`'s own built-in error rendering — no separate widget needed).
+3. The submit action is gated on the form's validity state.
+
+Platform-specific — see the matching section in the platform file:
+- **React Native**: every `TextInput` wrapped in `Controller`; submit calls `handleSubmit(onSubmit)`; `isValid` gates the submit button.
+- **React (web)**: every `<input>` uses `register()`; submit calls `handleSubmit(onSubmit)`; `isValid` gates the submit button.
+- **Angular**: `FormGroup` built in the constructor body (not a field initializer); submit checks `this.form.invalid` and calls `markAllAsTouched()` on failure.
+- **Flutter**: every `TextEditingController` is disposed in `dispose()`; submit calls `_formKey.currentState!.validate()`.

package/.github/skills/validation-engine-builder/references/core.md

@@ -0,0 +1,158 @@
+# Validation Engine — Core Reference (all platforms)
+
+This file is platform-agnostic — everything here applies identically whether the target project is
+React Native, React (web), Angular, or Flutter. Read this first, then read exactly one
+`platform-*.md` file for the platform-specific wiring syntax (Controller vs `register()` vs
+`FormGroup` vs `TextFormField.validator`).
+
+---
+
+## Field type detection quick-reference
+
+When reading a screen/page/component/widget file, infer the field type from variable names,
+placeholder text, and surrounding context — this inference is identical on every platform:
+
+| Clue in code | Inferred field type |
+|---|---|
+| `email`, `emailAddress`, `userEmail` | email |
+| `password`, `pwd`, `pass` | password |
+| `confirmPassword`, `repeatPassword`, `rePassword` | confirmPassword |
+| `phone`, `mobile`, `phoneNumber`, `mobileNumber` | phone |
+| `otp`, `verificationCode`, `pinCode` | otp |
+| `name`, `fullName`, `firstName`, `lastName`, `displayName` | name |
+| `postalCode`, `zipCode`, `zip` | postalCode |
+| `pincode` (India) | pincode (use regex key `pincode`, not `postalCode` — non-zero start enforced) |
+| `url`, `website`, `link`, `profileUrl` | url (optional) |
+| `dob`, `dateOfBirth`, `birthDate` | date |
+| `address`, `addressLine1`, `street` | generic required string, min: 5 |
+| `city`, `state`, `country` | generic required string, min: 2, regex: name |
+| `age` | number, min: 18 |
+| `quantity`, `count`, `amount` | number, min: 0 |
+| `message`, `bio`, `description`, `notes` | string, optional or required, min: 10 |
+
+---
+
+## Available regex keys (from templates/regex.json)
+
+| Key | Pattern | Use for |
+|---|---|---|
+| `email` | `^[^\s@]+@[^\s@]+\.[^\s@]+$` | email fields |
+| `phone` | `^[0-9]{10}$` | 10-digit phone/mobile |
+| `otp` | `^[0-9]{6}$` | 6-digit OTP |
+| `name` | `^[a-zA-Z ]+$` | name fields (letters + spaces only) |
+| `postalCode` | `^[0-9]{6}$` | 6-digit postal code |
+| `password` | uppercase + lowercase + digit + special char, min 8 | strong password |
+| `url` | `^https://...` | URL / website fields |
+| `alphanumeric` | `^[a-zA-Z0-9]+$` | alphanumeric-only fields |
+| `numericOnly` | `^[0-9]+$` | digits-only fields |
+| `date` | `^\d{2}/\d{2}/\d{4}$` | date in DD/MM/YYYY |
+| `panCard` | PAN card format | India PAN |
+| `aadhaar` | 12-digit Aadhaar | India Aadhaar |
+| `ifsc` | IFSC bank code | India IFSC |
+| `pincode` | 6-digit, non-zero start | India pincode |
+
+All 14 patterns are plain ECMAScript-compatible regex source strings, stored once in
+`templates/regex.json` and compiled into whichever target language the platform needs
+(`RegExp` in TS for React Native/React/Angular, `RegExp` in Dart for Flutter — Dart's regex engine
+supports the same lookahead syntax used by the `password` pattern, so no pattern needed to change).
+
+## Available message keys (from templates/messages.json)
+
+| Key | Message |
+|---|---|
+| `required` | {{field}} is required |
+| `email` | Please enter a valid email address |
+| `phone` | Please enter a valid 10-digit phone number |
+| `minLength` | Must be at least {{min}} characters |
+| `maxLength` | Cannot exceed {{max}} characters |
+| `minNumber` | Must be at least {{min}} |
+| `maxNumber` | Cannot exceed {{max}} |
+| `passwordMatch` | Passwords do not match |
+| `passwordStrength` | Password must contain uppercase, lowercase, number and special character |
+| `url` | Please enter a valid URL starting with https:// |
+| `otp` | Please enter a valid 6-digit OTP |
+| `name` | Please enter a valid name (letters and spaces only) |
+| `postalCode` | Please enter a valid 6-digit postal code |
+| `alphanumeric` | Only letters and numbers are allowed |
+| `numericOnly` | Only numbers are allowed |
+| `date` | Please enter a valid date |
+| `minAge` | You must be at least {{min}} years old |
+| `fileSize` | File size must not exceed {{max}} MB |
+| `invalidFormat` | Invalid format |
+| `panCard` | Please enter a valid PAN number (e.g. ABCDE1234F) |
+
+## Available schemas (from templates/schemas.json)
+
+Before creating a new schema, check if one of these already covers the screen/page/component's
+fields — the same `templates/schemas.json` entry drives the generated output on every platform
+(a Yup schema on React Native/React, an Angular `Validators[]` map, a Dart validator class):
+
+| Schema key | Fields |
+|---|---|
+| `login` | email, password |
+| `signup` | name, email, phone, password |
+| `forgotPassword` | email |
+| `resetPassword` | password, confirmPassword |
+| `otp` | otp |
+| `profileUpdate` | name, phone, email |
+| `mobileLogin` | phoneNumber |
+| `address` | addressLine1, city, postalCode, state |
+| `enterPanForm` | pan |
+| `addNomineeForm` | firstName, middleName, lastName, dob |
+| `addBankDetailsForm` | accountNumber |
+
+---
+
+## Golden rules (every platform)
+
+1. **Never edit generated files** — edit `templates/*.json` and re-run
+   `node .github/skills/validation-engine-builder/scripts/apply-to-project.js`.
+2. **Never hardcode an error message string** in a component/page/widget — all strings must come
+   from the generated messages module (`VALIDATION_MESSAGES` in TS, `ValidationMessages` in Dart).
+3. **Never hardcode a regex pattern** in a component/page/widget — all patterns must come from the
+   generated regex module (`VALIDATION_REGEX` in TS, `ValidationRegex` in Dart).
+4. **Reuse schemas across screens/pages/components** — add the schema once to `schemas.json`, use
+   the same key everywhere. Two login-like screens with identical fields share one schema key.
+5. **Cross-field validation (e.g. confirmPassword) is never expressible in `schemas.json`** — the
+   field-definition shape is per-field only. Each platform file documents the correct place to add
+   this by hand after generation (a Yup `.oneOf()`, an Angular `FormGroup`-level validator, a Dart
+   `TextEditingController` comparison) — see that platform's file.
+
+## Adding a new validation rule
+
+1. Add the error message to `templates/messages.json`.
+2. Add the regex pattern to `templates/regex.json` (if needed).
+3. Add or update the schema in `templates/schemas.json` using the new message/regex key.
+4. Re-run:
+   ```powershell
+   node .github/skills/validation-engine-builder/scripts/apply-to-project.js --projectPath <path>
+   ```
+   The script detects the platform automatically (or pass `--platform <react-native|react|angular|flutter>`
+   explicitly if the target has more than one platform in the same repo).
+5. The generated validation files are updated automatically. Existing screens/pages/components
+   still need AI wiring (or manual integration) if they don't already use the shared validation
+   layer.
+
+## Import path calculation
+
+The generated validation module always lives at a fixed location per platform (see the platform
+file for the exact path). Never hand-count directory levels for the relative import — the
+generator computes the correct relative path from the actual screen/page file location to the
+actual validation output directory using the real filesystem structure, not a naming assumption.
+If wiring a screen manually without running the generator's scaffold, use the same approach: count
+from the file's own directory to the validation output directory using the project's real folder
+structure.
+
+## Adding a new screen/page/component with validation
+
+Use the AI workflow in `SKILL.md` to detect the platform and wire the new screen/page/component.
+The supported script command per platform is:
+
+```powershell
+node .github/skills/validation-engine-builder/scripts/apply-to-project.js --projectPath <path> --platform <platform>
+```
+
+That command regenerates the validation output only. It does not scaffold or rewrite an existing
+screen — screen/page/component wiring is the AI's job (see SKILL.md Execution Steps), using the
+`generateScreen()` export from the matching `generate-<platform>.js` module as an optional scaffold
+helper for a brand-new file.

package/.github/skills/validation-engine-builder/references/platform-angular.md

@@ -0,0 +1,166 @@
+# Platform File — Angular
+
+Read `core.md` first. Angular cannot use react-hook-form at all — it is a React library and has no
+Angular equivalent. This platform targets Angular's own framework-native Reactive Forms
+(`@angular/forms`: `FormBuilder`, `FormGroup`, `Validators`) instead of porting the Yup pattern.
+
+---
+
+## Dependencies
+
+None to install — Reactive Forms ships as part of `@angular/forms`, which every Angular project
+already depends on. `scripts/shared/npm-deps.js` no-ops for this platform (prints an explanatory
+message) rather than trying to install anything.
+
+Confirm the target uses (or add) `provideHttpClient`/`ReactiveFormsModule` availability — for a
+standalone component, `imports: [ReactiveFormsModule]` on the component itself is enough (see the
+generated scaffold below); no root-level module registration is required.
+
+## Generated files
+
+`node scripts/apply-to-project.js --platform angular` writes to `src/app/validation/`:
+
+| File | Role |
+|---|---|
+| `validation-messages.ts` | `VALIDATION_MESSAGES` const + `msg` interpolation helpers — identical shape to the RN/React `messages.ts`, zero Angular imports |
+| `validation-regex.ts` | `VALIDATION_REGEX` const — identical shape to RN/React `regex.ts` |
+| `pattern-with-message.validator.ts` | A `ValidatorFn` factory that reports a specific `VALIDATION_MESSAGES` key on failure (Angular's built-in `Validators.pattern` only reports a generic `pattern` error key, which can't carry which message to show) |
+| `validators.ts` | Per-schema `Validators[]` arrays — this replaces `schemas.ts`; there is no Yup schema on this platform |
+| `validation-error.component.ts` | A standalone `<app-validation-error>` component that reads a control's `.errors` and looks up the matching message |
+
+There is no generated "hook" file on this platform — Angular's own `FormBuilder` (injected via
+constructor) already serves that role; see the scaffold pattern below.
+
+## Why Angular needs its own DI-aware approach
+
+A TypeScript `interface` (or a `type`) has no runtime representation, so Angular's dependency
+injector cannot use one as a lookup token. `patternWithMessage()` and `Validators.*` are plain
+functions, not classes, so this doesn't come up for validators themselves — but if this project
+also uses `clean-architecture-generator`'s Angular repository pattern (abstract-class-as-token),
+the same principle applies there too; it's not specific to forms.
+
+## `FormGroup` wiring per field type
+
+```ts
+import { Component } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, type FormGroup } from '@angular/forms';
+import { validators } from '../../validation/validators';
+import { ValidationErrorComponent } from '../../validation/validation-error.component';
+
+@Component({
+  selector: 'app-login-page',
+  standalone: true,
+  imports: [ReactiveFormsModule, ValidationErrorComponent],
+  templateUrl: './login-page.component.html',
+  styleUrl: './login-page.component.scss',
+})
+export class LoginPageComponent {
+  // Built in the constructor body, not as a field initializer — a field
+  // initializer runs before constructor parameter properties are assigned,
+  // so 'this.fb' would still be undefined if used at the field-declaration site.
+  readonly form: FormGroup;
+
+  constructor(private readonly fb: FormBuilder) {
+    this.form = this.fb.group({
+      email: ['', validators.login.email],
+      password: ['', validators.login.password],
+    });
+  }
+
+  onSubmit(): void {
+    if (this.form.invalid) {
+      this.form.markAllAsTouched();
+      return;
+    }
+    // TODO: submit logic
+  }
+}
+```
+
+```html
+<form [formGroup]="form" (ngSubmit)="onSubmit()">
+  <div class="field">
+    <label for="email">Email</label>
+    <input id="email" type="email" formControlName="email" />
+    <app-validation-error [control]="form.get('email')" label="Email"></app-validation-error>
+  </div>
+  <button type="submit">Submit</button>
+</form>
+```
+
+**Never** put `this.fb.group(...)` in a field initializer (`readonly form = this.fb.group(...)`
+directly on the class body) — constructor parameter properties (`private readonly fb: FormBuilder`)
+are assigned inside the constructor body, and TypeScript emits class field initializers to run
+*before* that assignment completes. Referencing `this.fb` from a field initializer reads it as
+`undefined` and throws at runtime. Always build the `FormGroup` inside the constructor body.
+
+### Per-field `type` attribute
+
+| Field type | `type` attribute |
+|---|---|
+| password / confirmPassword | `password` |
+| number fields | `number` |
+| everything else | `text` |
+
+## How `ValidationErrorComponent` maps errors to messages
+
+Angular's built-in validators set well-known, lowercase error keys on `control.errors`:
+`required`, `minlength` (with `{ requiredLength, actualLength }`), `maxlength`, `min`, `max`. The
+generated `patternWithMessage()` validator instead sets `{ [yourMessageKey]: true }` directly, so
+the component can look the key straight up in `VALIDATION_MESSAGES` without a translation table.
+`ValidationErrorComponent` checks the built-in keys first, then falls back to any custom message
+key it finds. Only show an error once the control is `dirty` or `touched`, matching react-hook-form's
+`mode: 'onBlur'` behavior on the other platforms.
+
+## confirmPassword / cross-field validation
+
+Angular's per-field `Validators[]` array (same as `patternWithMessage`) cannot express "this field
+must equal another field in the same group" — that requires a **`FormGroup`-level validator**
+instead of a per-control one:
+
+```ts
+import type { ValidatorFn } from '@angular/forms';
+
+export function passwordsMatch(): ValidatorFn {
+  return (group) => {
+    const password = group.get('password')?.value;
+    const confirmPassword = group.get('confirmPassword')?.value;
+    return password === confirmPassword ? null : { passwordMatch: true };
+  };
+}
+
+// wiring:
+this.form = this.fb.group(
+  { password: ['', validators.resetPassword.password], confirmPassword: ['', validators.resetPassword.confirmPassword] },
+  { validators: [passwordsMatch()] },
+);
+```
+
+Read the group-level error (`this.form.errors?.['passwordMatch']`) in the template, since a
+group-level error doesn't attach to either individual control.
+
+## Reusing the same validation on multiple pages
+
+```ts
+// login-page.component.ts
+this.form = this.fb.group({ email: ['', validators.login.email], password: ['', validators.login.password] });
+
+// admin-login-page.component.ts
+this.form = this.fb.group({ email: ['', validators.login.email], password: ['', validators.login.password] }); // same validators, different page
+```
+
+## Page scaffold generator (optional)
+
+`generate-angular.js` exports `generateScreen(projectRoot, pageName, schemaKey, pagePath, schemasRaw)`
+— writes a starter `[pageName]/[pageName].component.ts` + `.html` + `.scss` wired with `FormBuilder`
+and `<app-validation-error>` for every field in the given schema. `pageName` must be kebab-case, per
+Angular's own naming convention (see `clean-architecture-generator`'s Angular platform file for the
+same rule applied to other artifact types).
+
+## Angular Material projects
+
+If the target project uses Angular Material (`@angular/material` in `package.json`), prefer
+`<mat-form-field>` + `<mat-error>` over the plain `<input>` + `<app-validation-error>` pair shown
+above — `<mat-error>` already integrates with Material's own error-display timing. In that case,
+still source the error text from `ValidationErrorComponent`'s `message` getter logic (or import
+`VALIDATION_MESSAGES` directly) rather than hardcoding text inside `<mat-error>`.