@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,852 @@
-# Temporary Holding Version
+# @team-codeme/crud-forge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```text
+  ____ ____  _   _ ____  _____                     _      ___ 
+ / ___|  _ \| | | |  _ \|  ___|__  _ __ __ _  ___  | |    |_ _|
+| |   | |_) | | | | | | | |_ / _ \| '__/ _` |/ _ \ | |     | | 
+| |___|  _ <| |_| | |_| |  _| (_) | | | (_| |  __/ | |___  | | 
+ \____|_| \_\___/|____/|_|  \___/|_|  \__, |\___| |_____|___|
+                                      |___/                  
+                  Developed by TeamCodeMe
+                  Official Website: https://crudforge.teamcodeme.com/
+                  Documentation: https://crudforge-cli-doc.vercel.app
+```
+
+![CRUDForge poster](https://lh3.googleusercontent.com/kTtVlTPXl9b8qEU7VXoz8u6eRtiAXjcnLIMVPlWnsJKUEI5Xx_EbjiAcH1afwmV-1sho3l_JPjNphGAC5Oszr1rA0V2uvdBs9mhLkK8Z=s960)
+
+<div align="center">
+
+[![Official Website](https://img.shields.io/badge/Official%20Website-crudforge.teamcodeme.com-blue?style=for-the-badge&logo=googlechrome&logoColor=white)](https://crudforge.teamcodeme.com/)
+[![Documentation](https://img.shields.io/badge/Documentation-crudforge--cli--doc.vercel.app-success?style=for-the-badge&logo=vercel&logoColor=white)](https://crudforge-cli-doc.vercel.app)
+[![npm version](https://img.shields.io/npm/v/@team-codeme/crud-forge?style=for-the-badge&color=cb3837&logo=npm)](https://www.npmjs.com/package/@team-codeme/crud-forge)
+
+</div>
+
+CRUDForge CLI is a high-performance, developer-configurable Angular Material CRUD code generator. It maps JDL (JHipster Domain Language) or GDL schemas directly into high-fidelity standalone Angular 17+ components, types, services, and routes.
+
+- 🌐 **Official Website:** [https://crudforge.teamcodeme.com/](https://crudforge.teamcodeme.com/)
+- 📖 **Documentation:** [https://crudforge-cli-doc.vercel.app](https://crudforge-cli-doc.vercel.app)
+- 🏢 **Organization:** [@team-codeme](https://www.npmjs.com/org/team-codeme)
+
+**Product docs (deployable Starlight site):** Available live at [crudforge-cli-doc.vercel.app](https://crudforge-cli-doc.vercel.app) (source in sibling repo [`crud-fordge-doc`](../crud-fordge-doc)) — splash uses the same poster; Features / Customization galleries with screenshots. Capture shots: `npm run e2e:serve` then `cd ../crud-fordge-doc && npm run shots:capture` (IAM: `e2e:serve:iam` + `shots:capture:iam`).
+
+---
+
+## 📂 Layout Structure
+
+CRUDForge structures entity templates under a responsibility-based directory layout:
+
+```text
+src/templates/angular/
+└── entity/
+    ├── _entity_.model.ts.ejs                # Angular domain models
+    ├── _entity_.routes.ts.ejs               # Routing config
+    ├── service/
+    │   └── _entity_.service.ts.ejs          # REST client data services
+    ├── components/
+    │   ├── presentation/                    # Read-only UI layouts
+    │   │   ├── card/                        # Compact tile displays
+    │   │   ├── detail/                      # Detailed properties sheet
+    │   │   └── list/                        # Central pagination table
+    │   ├── forms/                           # Input and update logic
+    │   │   ├── form/                        # Reusable form component
+    │   │   ├── form-page/                   # Independent route page
+    │   │   └── update/                      # Reactive FormGroup validation mapper
+    │   └── interaction/                     # Control actions & query filtering
+    │       ├── actions/                     # Action buttons and query filters toolbar
+    │       └── filter/                      # Advanced search/filter sidebar panel
+    └── shared/                              # (Generated inside each entity or centralized)
+        ├── base/                            # Centralized abstract base classes
+        │   ├── base-filter.component.ts.ejs # Shared filter logic & reactive forms
+        │   ├── base-form.component.ts.ejs   # Shared form state & error handling
+        │   ├── base-list.component.ts.ejs   # Shared pagination, export, & row states
+        │   └── filter-types.ts.ejs          # Shared filter types
+        ├── confirmation-dialog.component.ts.ejs # Generic confirmation dialog
+        ├── resizable.directive.ts.ejs       # Table column resizing directive
+        └── snackbar-styles.css.ejs          # Global snackbar theming
+```
+
+When code is generated, the target directory matches this structure to promote strict modularity and clean imports in the generated Angular application.
+
+---
+
+## 📦 Installation
+
+To install CRUDForge CLI globally on your system:
+
+```bash
+npm install -g @team-codeme/crud-forge
+```
+
+Or run directly without installation using `npx`:
+
+```bash
+npx @team-codeme/crud-forge init my-app
+```
+
+---
+
+## 🛠️ CLI Usage
+
+### Initialize → edit → generate
+
+Start with editable project inputs, before generating Angular:
+
+```bash
+crudforge init crudforge-app
+cd crudforge-app
+# Edit config/crudforge.config.yml and gdl/example.gdl
+crudforge generate
+npm install
+npm run dev
+```
+
+`init` creates only these two files in a new or empty directory:
+
+```text
+crudforge-app/
+├── config/
+│   └── crudforge.config.yml
+└── gdl/
+    └── example.gdl
+```
+
+The default sample uses the supported GDL syntax (type before field name):
+
+```gdl
+entity Book {
+  string title required
+  bigDecimal price
+}
+```
+
+Supported entity annotations (GDL):
+
+| Annotation | Effect |
+|---|---|
+| `@Audited` | Injects configured audit fields (`createdBy`, `createdDate`, …) |
+| `@Searchable` | Marks the entity for list search; searchable columns prefer text/enum fields |
+| `@ActiveStatus` | Injects `bool isActive` on the model (skipped if already declared); enables list activate/deactivate |
+
+JDL equivalents: `@EnableAudit`, `@Searchable`, `@ActiveStatus`. Other annotations (e.g. `@SoftDelete`) still fail validation.
+
+The generated configuration includes the existing project settings and these workflow defaults:
+
+```yaml
+input:
+  type: gdl
+  file: ./gdl/example.gdl          # single schema (legacy)
+  # Or multiple GDL/JDL files per backend service:
+  # sources:
+  #   - name: identity-access
+  #     file: ./GDL/identity-access.gdl
+  #     microservice: identity-access-module
+  #   - name: inventory
+  #     file: ./GDL/inventory.gdl
+  #     microservice: inventory-service
+# Enums: src/app/domains/admin/modules/apps/micro-functions/<service-folder>/enum/
+# Every service keeps enum/ with a .gitkeep, even without enum definitions.
+# Generated entities: src/app/domains/admin/modules/apps/micro-functions/<service-folder>/entities/<entity>/
+# sources[].folder can preserve module names such as identityAccessModule.
+# Single-schema module folders use api.microservice; multi-source folders use sources[].folder or name.
+output:
+  directory: .
+  overwritePolicy: fail
+fuse:
+  enabled: true
+  rendering: spa
+  cleanLayout: true
+  includePrebuilt: false
+  theme:
+    scheme: system          # system | light | dark
+    primary: "#0D1E3A"      # default navy — buttons / accents via root fuseTheme
+    error: "#dc2626"
+api:
+  microservice: book-service      # fallback when a source omits microservice
+auth:
+  provider: none
+```
+
+`input.sources[]` generates one nav group and `apps/<folder>/` tree per service (`name`),
+and each entity’s HTTP client uses that source’s `microservice`. Entity names must stay unique
+across all listed files. Prefer `sources` for multi-backend apps; keep `input.file` for one schema.
+
+Update entities, relationships, the microservice identifier, and any supported settings before
+running `crudforge generate`. It finds the project's configuration, validates it and the
+referenced schema, and adds the Fuse application directly into the same folder:
+
+```text
+crudforge-app/
+├── config/
+│   └── crudforge.config.yml
+├── gdl/
+│   └── example.gdl
+├── src/
+├── angular.json
+├── package.json
+└── ...
+```
+
+The source configuration and GDL remain unchanged, including comments. There is no nested
+application folder. `input.file`, `input.sources[].file`, and `output.directory` are relative to the project root,
+not `config/`. Without a positional schema, `--preferences /path/to/app/config/crudforge.config.yml`
+also anchors relative paths at `/path/to/app`; a root-level config anchors at its containing
+directory. Moving the whole initialized project therefore needs no path edits.
+
+Discovery checks `config/crudforge.config.yml`, `config/crudforge.config.yaml`,
+`crudforge.config.yml`, `crudforge.config.yaml`, `config/config.yml`, then `crudforge.config.json`.
+An explicit `--preferences` takes precedence. Missing or malformed inputs fail with file paths
+before project files are written; invalid config no longer silently falls back to defaults.
+
+On regeneration, differing existing application files require an overwrite policy. The CLI
+honors `output.overwritePolicy`, with an explicit flag taking precedence; the fallback is `fail`.
+Fuse starter files and generated files follow the same policy. Source configuration and schema
+files are protected even with `overwrite`. No stale or unrelated files are automatically deleted.
+
+```bash
+crudforge generate --dry-run                 # preview without changing project files
+crudforge generate --overwrite-policy ask    # resolve each conflict interactively
+crudforge generate --overwrite-policy skip   # keep differing existing files
+crudforge generate --overwrite-policy merge  # preserve matching cforge custom-code zones
+crudforge generate --overwrite-policy overwrite # explicitly replace generated application files
+```
+
+`merge` preserves marked custom-code zones, not arbitrary edits; binary conflicts require
+`ask`, `skip`, or `overwrite`. `ask` fails on conflicts in noninteractive CI. `--yes` does not
+authorize overwriting files. `fail` checks all differing files before applying changes.
+
+### Optional PMB development testing preset
+
+Use Node 24+ for the generated application. Import the PMB development settings once:
+
+```bash
+crudforge init crudforge-app --preset pmb-test --source /path/to/PMB/pmb-admin
+cd crudforge-app
+# Optional: edit config/crudforge.config.yml and gdl/example.gdl
+crudforge generate
+npm install
+npm run dev -- --port 4200
+```
+
+Open `http://localhost:4200/auth/sign-in` and enter your existing PMB login. The CLI prints
+the actual port extracted from PMB's development settings. If that port is occupied, pass
+a free port to `npm run dev -- --port <port>`. `npm start` selects the production build;
+use the printed `npm run dev` command for this testing workflow.
+
+The first command only creates the editable config and sample GDL. It reads PMB without
+executing its scripts or modifying its files. The importer follows the development Angular
+environment replacement and serve/proxy settings, checks the public-client token flow,
+and maps the Province model/client to its reference-module route. Unsupported dynamic
+settings or a changed authentication contract produce actionable errors instead of guesses.
+
+The reusable preset is stored at `${XDG_CONFIG_HOME:-~/.config}/crudforge/presets/pmb-test/`:
+
+```text
+pmb-test/
+├── config.yml
+├── example.gdl
+└── metadata.json
+```
+
+The metadata records source-file hashes, the source location, import time, sample endpoint,
+and verification limitations. The source location is not copied into the generated app.
+Configuration and schema paths in the app remain project-relative. The app does not need
+access to the registry or PMB source after initialization.
+
+After deleting a disposable generated app, recreate it without re-entering backend settings:
+
+```bash
+crudforge init crudforge-app --preset pmb-test
+cd crudforge-app
+crudforge generate
+npm install
+npm run dev -- --port 4200
+```
+
+Refresh the saved preset when the PMB source changes:
+
+```bash
+crudforge preset refresh pmb-test --source /path/to/PMB/pmb-admin
+```
+
+Refresh validates the new settings before replacing the preset, retains a timestamped backup
+beside it, and leaves existing apps unchanged. Initial import refuses to replace an existing
+preset; use `refresh` explicitly. Normal `crudforge init <directory>` remains independent of PMB.
+
+The preset maps real public-client login, refresh and logout, PMB admin roles, idle timeout,
+service targets and aliases. It includes `proxy.routes` for explicit proxy entries and
+`devServer.port` for the development server. Explicit proxy routes override auto-generated
+entries and apply to the files selected by `proxy.write`; specific routes precede catch-all
+prefixes. Supported entry fields are `target`, `secure`, `changeOrigin`, `ws`, `logLevel`, and
+`pathRewrite`. Headers, cookies, credentials and executable proxy hooks are not imported.
+Both proxy files in this testing preset intentionally target PMB development services.
+
+The sample `Province` uses PMB's frontend model and reference API path. Authentication and
+API reachability still require runtime verification. Arbitrary new GDL entities do not create
+backend endpoints. The importer does not copy DAD secondary-login credentials, confidential
+internal clients, account passwords, or tokens; it never provisions or restarts services.
+Live sign-in forms do not inherit `KEYCLOAK_ADMIN_*` credentials from the CLI environment.
+
+Privileged IAM management screens are disabled by this preset. PMB's non-admin screen
+permissions, profile/business context, and backend write constraints are not reproduced
+by a frontend preset and require separate verification for the intended account. Automated
+live checks should use only read-only API requests; a successful build is not proof of login
+or backend permissions.
+
+Validation commands for contributors:
+
+```bash
+npm test          # includes isolated preset import/reuse/refresh and generation checks
+npm run test:auth # Node 24+: refresh/retry and session-error behavior
+```
+
+### Existing commands
+
+Explicit schema/output generation remains supported. Explicit CLI paths and config-relative
+paths in this legacy form resolve from the current working directory:
+
+```bash
+crudforge generate <path-to-schema.jdl> <target-output-folder> [options]
+```
+
+The existing `init-config` command still creates `crudforge.config.yml`, `example.jdl`, and
+`example.gdl` in the current directory, skipping existing files. Use `init <directory>` for
+the project-owned input workflow:
+
+```bash
+crudforge init-config
+```
+
+Validate a schema blueprint against generation rules without writing files:
+
+```bash
+crudforge validate <path-to-schema.jdl>
+```
+
+Bootstrap Keycloak resources (client, roles, initial users) without generating an app. **Does not run during `generate`.**
+
+```bash
+crudforge bootstrap --preferences ./crudforge.config.yml --env-file ./.env.qa
+crudforge bootstrap --dry-run --preferences ./crudforge.config.yml --env-file ./.env.qa
+crudforge bootstrap --cleanup --preferences ./crudforge.config.yml --env-file ./.env.qa
+```
+
+### Options
+* `-m, --microservice`      : Explicit microservice name for API route prefixes.
+* `-p, --preferences`       : Path to a custom config file (YAML/JSON) overriding defaults.
+* `-d, --dry-run`           : Preview files to be created and diff modifications without writing to disk.
+* `-w, --overwrite-policy`  : Overwrite policy for existing files (overwrite, skip, fail, ask, merge).
+* `--fuse`                  : Scaffold and generate the entities into a Fuse Angular starter project layout.
+* `--fuse-path`             : Path to a local Fuse starter pack directory (if overriding the bundled default).
+* `--clean-layout`          : Hide all pre-built Fuse UI components (banners, alerts) for a minimal dashboard.
+* `--sidebar-theme`         : Configures sidebar navigation theme style ('white' or 'dark').
+* `--folder-type`           : Navigation/ACL group name (generated service modules live under `micro-functions`).
+* `--keycloak`              : Enable Keycloak when config `auth.provider` is still `none`.
+* `--kc-*`                  : Optional overrides for server URL, middleware URL, client ID, realm, credentials.
+* `--proxy-write`           : Which Fuse proxy file(s) to update for services/Keycloak (`both` | `prod` | `dev`).
+* `--yes` / `-y`            : Skip interactive prompts (microservice / proxy-write).
+* `--env-file`              : (`bootstrap`) Load a gitignored env file for admin / seed-user credentials.
+* `--cleanup`               : (`bootstrap`) Delete only resources tracked in the provision state file.
+
+---
+
+## 🔐 Keycloak auth and IAM
+
+Defaults keep `auth.provider: none` and `auth.provision.enabled: false`. Turn Keycloak on only when the app needs real identity. Do **not** model User or Role as JDL entities; IAM is an overlay (`iam.enabled`). Generated packs live under **`src/app/core/auth/`** (services / guards / interceptors + `AGENT_README.md`) and **`src/app/core/user-management/`** (Users, Roles, role/user screen matrices + `AGENT_README.md`). Product docs: [IAM overlay](../crud-fordge-doc/src/content/docs/features/iam.md) and [Users, roles & screen access](../crud-fordge-doc/src/content/docs/guides/iam-access.md).
+
+Every Fuse generate also ships **access-control-tools** at `src/app/domains/admin/modules/apps/shared/access-control-tools/` (README + `AGENT_README.md` / `AGENT_MEMORY.md`). Use it after adding custom pages to stamp `SCREEN` / `accessCtrl` / QA ids and refresh `public/assets/screen-components.csv`:
+
+```bash
+npm run access-control:sync    # dry-run
+npm run access-control:apply   # write
+```
+
+Component ids follow semantic verbs (`create`, `open-filter`, `toggle-view`, `open-columns`). Entity `SCREEN` stays `{folder}/{entity}` (nav-aligned). Runtime aliases keep older Keycloak grants (`new`↔`create`, etc.) working.
+
+**Permission matrices** and **Role / User Management** accents follow root `fuse.theme.primary` (default navy `#0D1E3A`) via Tailwind `primary-*` / `--theme-color-primary-*` — not hardcoded emerald. Matrices keep sticky scrollable grids (`matrix-table` → `width: max-content`), per-toggle busy lock, holder sync after role writes, grant/revoke sounds on permission matrices, confirm dialog + assigned/available role cards on user access (no sounds there). System roles (`offline_access`, `uma_authorization`, `default-roles-*`) are hidden.
+
+**Role Management** (`roles/role-list`) follows PMB `role-management`: master-detail list with search/pagination, create role form, duplicate, Sync holders, Assign Users bottom-sheet, inheritance flow, and a screen-permissions summary panel that deep-links to the role matrix. Catalog is CSV-only (`public/assets/screen-components.csv`); no Access Control DB or PMB approval/region exclusions.
+
+```yaml
+auth:
+  provider: keycloak          # or none
+  serverUrl: ""               # Keycloak base, e.g. http://host:30080 (not the /admin/... console deep-link)
+  realm: CRUD-FORDGE
+  clientId: crudforge-client-QA
+  useMockAuth: false          # true for deterministic Playwright / offline demos
+  forwardedProto: https       # X-Forwarded-Proto when Keycloak requires HTTPS behind HTTP
+  adminRoles: [ROLE_ADMIN, ADMIN, ROLE_SUPER_ADMIN]
+  # Session: idleTimeoutMs 0 = stay signed in until explicit logout (default).
+  session:
+    idleTimeoutMs: 0              # set e.g. 900000 for 15-minute idle logout
+    persistAcrossReload: true
+    crossTabSync: true            # sign out this tab when another tab clears tokens
+    refreshOnFocus: true          # refresh access token when the tab becomes visible
+    statusProbeIntervalMs: 60000  # refresh-if-due probe when disabledAccount.enabled
+  disabledAccount:
+    enabled: false                # true → freeze shell + countdown overlay, then sign out
+    countdownSeconds: 20
+    message: "Your account has been disabled. Please contact your administrator."
+    sound: false
+  provision:
+    enabled: false            # must be true for `crudforge bootstrap` only
+    adapter: keycloak-admin-rest   # or admin-service (middleware wrapper)
+    adminServiceUrl: ""       # Keycloak middleware / admin service, e.g. http://host:31740/
+    adminUsernameEnv: KEYCLOAK_ADMIN_USERNAME
+    adminPasswordEnv: KEYCLOAK_ADMIN_PASSWORD
+    clientId: crudforge-client-QA
+```
+
+Session pack defaults keep the user signed in across reloads. Token refresh only clears the session on **terminal** auth errors (invalid/expired refresh); network blips and 5xx keep the session. When `disabledAccount.enabled` is true, an explicit Keycloak “account disabled” grant error shows a root overlay (wired into Fuse `app.ts`) and signs out after the countdown — never on generic `invalid_grant` alone.
+### Developer generate with Keycloak
+
+Fill Keycloak in **`crudforge.config.yml`** (not CLI prompts). Bootstrap operator passwords stay in a local **`.env`** via `adminUsernameEnv` / `adminPasswordEnv`. Live QA may also set `auth.signInPrefill` so the Angular login form is pre-bound to `crud` / `crud`.
+
+```yaml
+auth:
+  provider: keycloak
+  serverUrl: http://62.84.188.166:31740   # Admin Service gateway (not Keycloak :30080)
+  realm: CRUD-FORDGE
+  clientId: crudforge-client-QA
+  forwardedProto: https
+  signInPrefill:
+    username: crud
+    password: crud
+  provision:
+    adapter: admin-service
+    adminServiceUrl: http://62.84.188.166:31740/
+    adminUsernameEnv: KEYCLOAK_ADMIN_USERNAME
+    adminPasswordEnv: KEYCLOAK_ADMIN_PASSWORD
+
+api:
+  microservice: book-service
+  services:
+    identityaccessmodule: http://62.84.188.166:30084
+    # Optional per-env targets:
+    # book-service:
+    #   prod: http://host:30084
+    #   dev: http://host:31704
+    #   pathRewrite: /book-service
+
+proxy:
+  write: both   # both | prod (proxy.conf.json) | dev (proxy.dev.conf.json)
+```
+
+Generate writes Keycloak + `api.services` into `src/environments/environment*.ts` (relative `/services/{name}` paths) and updates the chosen Fuse proxy file(s) with absolute targets. When `api.services` is set and you are on a TTY, generate asks **dev / prod / both** unless `proxy.write` or `--proxy-write` / `--yes` is set.
+
+```bash
+# .env (gitignored) next to the project or output app
+KEYCLOAK_ADMIN_USERNAME=crud
+KEYCLOAK_ADMIN_PASSWORD=crud
+
+crudforge generate ./domain.jdl ./my-app --fuse --clean-layout --preferences ./crudforge.config.yml
+crudforge bootstrap --preferences ./my-app/config/crudforge.config.yml --env-file ./my-app/.env
+```
+
+The admin console URL (`…/admin/master/console/#/…`) is a **UI link only** — use the Keycloak base URL for APIs.
+
+Passwords and admin credentials stay in the CLI process via `passwordEnv` / `admin*Env`. They are never written into Angular `environment.ts`, browser bundles, or committed fixtures. Generated SPAs use a **public** client (no confidential `clientSecret` in the browser).
+
+Live Fuse apps proxy `/realms` (OIDC token) and `/services/keycloak-admin` to either the [Keycloak Admin Service](http://62.84.188.166:31740/) middleware (`useKeycloakAdminService: true` → `/api/v1/*`) or native Keycloak Admin REST (`useKeycloakAdminService: false` → `/admin/realms/...` via the same `/services/keycloak-admin` prefix). Broader `/auth` and `/admin` are **never** proxied so the Angular SPA shell stays intact — bare `/admin/realms` calls hit Fuse `index.html`. Details: [QA/KEYCLOAK-BOOTSTRAP.md](QA/KEYCLOAK-BOOTSTRAP.md).
+
+Structural backlog (session stay-signed-in, disabled-account overlay from PMB patterns, IAM registry, optional packs): see [Todo.md](Todo.md).
+
+---
+
+## 🧪 QA and CI
+
+```bash
+# Mock (no remote Keycloak mutations)
+./test-run.sh mock
+npm test
+npm run e2e:prepare && npm run test:e2e
+npm run e2e:prepare:iam && npm run test:e2e:iam
+
+# Live Keycloak (requires gitignored .env.qa — copy from .env.qa.example for seeded user passwords only)
+# Endpoints + operator crud/crud are hardcoded in test-run.sh and e2e/crudforge.iam-live.yml:
+#   Keycloak Admin Service http://62.84.188.166:31740/  realm CRUD-FORDGE  client crudforge-client-QA
+# `./test-run.sh` (mock) runs mock Playwright, then regenerates the shared testing-area app
+# on LIVE middleware wiring so `npm start` has:
+#   proxy `/realms` + `/services/keycloak-admin` → :31740
+#   environment.ts live links + sign-in prefill crud/crud (passwords stay in .env, not proxy)
+./test-run.sh live
+npm run e2e:prepare:iam:live
+npm run test:e2e:iam:live
+```
+
+`test-run.sh` resolves paths from its own location (any cwd), refuses unsafe cleanup paths, and distinguishes mock vs live. By default it writes **one** Fuse app under:
+
+`/Users/abdulla/Work/CRUD-FORDGE-SETUP/crud-fordge-testing-area/crudforge-app`
+
+Mock CRUD, mock IAM, and live IAM all regenerate that same folder (no parallel `.mock-app` / `.iam-app` trees). Override with `CRUDFORGE_TESTING_AREA` / `CRUDFORGE_E2E_APP_DIR`. Local prepares default to that external sandbox whenever `CRUD-FORDGE-SETUP` exists (or `.env.qa` sets the path). Set `CRUDFORGE_USE_IN_REPO_E2E=1` to force the historical in-repo `e2e/.app` (CI without the external tree).
+
+### Generated Fuse root extras (default on)
+
+When `fuse.enabled` is true, generate also:
+
+- Writes **`config/crudforge.config.yml`** (dated header, section comments, secrets stripped)
+- Seeds **GO-DUCK-style agent docs** (each stamped **Generated by `@crudforge/cli`**): root `AGENT_README.md`, `docs/ai/README.md` + topic maps (`ENTITIES.md` uses real `fieldName`/`fieldType` + relationship index), pack-level auth/IAM `AGENT_README.md`, `.crudforge/config.yaml`
+- Stamps **`@generated by @crudforge/cli`** on generated Fuse sources written through the engine (`.ts` / `.html` / `.scss` / `.css` / utils / IAM / shared / docs) — skip binary + JSON; regenerate instead of hand-editing as source of truth
+- Seeds keep-team folders: `.cursor/agents/`, `.codex/agents/`, `.agents/agents/` + `.agents/rules/` (Antigravity), `.vscode/extensions/` (+ `extensions.json`)
+- If `project.repositoryUrl` is set: `git init` (if needed) and `git remote add origin <url>` (never pushes; will not overwrite an existing different origin)
+
+```yaml
+project:
+  repositoryUrl: "https://github.com/org/my-app.git"  # optional
+output:
+  embedConfig: true
+  aiDocs:
+    enabled: true
+  teamPack:
+    enabled: true
+    cursorAgents: true
+    codexAgents: true
+    antigravityAgents: true   # Google Antigravity: .agents/agents + .agents/rules
+    vscodeExtensions: true
+```
+
+`loadConfig` prefers `config/crudforge.config.yml` inside a generated app.
+
+### Branding
+
+The Fuse starter ships the navy/blue/orange CRUDForge wordmark at `public/images/logo/logo.png` and the forged-C mark at `logo-mark.png`. Sidebar header and sign-in use the wordmark; favicon uses the mark. With Keycloak auth, the sidebar footer user chip matches PMB (avatar / initials icon, Super Admin badge when ACL admin, name + email, emerald power-button logout with confirm). Default Material primary is navy `#0D1E3A` via root `fuseTheme` / `fuse.theme.primary` — override in config, do not hardcode entity colors. Unused Fuse stock folders (`photos`, `cards`, `pages`, `apps`, `ui`) are not shipped.
+
+Keep-team specialist agents live under `.cursor/agents/`, `.codex/agents/`, and Antigravity `.agents/` (when `teamPack.antigravityAgents` is on).
+
+Latest local run notes: see [QA/KEYCLOAK-BOOTSTRAP.md](QA/KEYCLOAK-BOOTSTRAP.md).
+
+| Workflow | When | What |
+|---|---|---|
+| `.github/workflows/qa.yml` | PR / push | Generator tests + mock Playwright |
+| `.github/workflows/qa-live.yml` | Manual / weekly | Bootstrap + live Keycloak (secrets via GitHub environment `keycloak-qa`) |
+
+---
+
+## ⚙️ Configuration Preferences
+
+CRUDForge accepts a configuration file (e.g. `crudforge.config.yml`). You can scaffold a default configuration via the `init-config` command:
+
+```yaml
+# Options matrix
+fuse:
+  enabled: false
+
+generate:
+  models: true
+  services: true
+  formServices: true
+  routes: true
+  enums: true
+  relationships: true
+  components:
+    list: true
+    card: true
+    detail: true
+  forms:
+    form: true
+    formPage: true
+    update: true
+    validators: true
+    mappers: true
+  interaction:
+    actions: true
+    filter: true
+  globals:
+    constants: true
+    tests: false
+    sharedAssets: true
+  registrations:
+    navigation: true
+    routes: true
+
+output:
+  structure: "shared-central" # 'shared-central' (unified) or 'entity-folder' (duplicated)
+  directory: "./src/app"
+
+formBehavior:
+  uppercaseInputs: false
+  showErrorMessages: true
+
+ui:
+  viewMode: "table" # default fallback view
+  formMode: "sidebar" # sidebar drawer or page — new and edit share one mode
+  searchMode: "field" # field.contains by default; use global only when API accepts query
+  cardBreakpointPx: 640
+  gridCols:
+    tablet: 2
+    desktop: 3
+
+auth:
+  provider: none
+  provision:
+    enabled: false
+
+iam:
+  enabled: false
+```
+
+### Generated list and form state
+
+Audit columns (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`)
+start unchecked in **Column Preferences**. They remain available to select.
+`fields.audit.hideInLists: false` opts into showing them initially. Saved browser
+column selections take precedence; **Reset** applies the configured defaults.
+
+Technical plumbing fields (`debug`, `refType`, `refId`) are hidden from all UI
+surfaces by default via `fields.technical` (list, form, detail, card, filter,
+search). They remain on the TypeScript model and form group for API round-trips.
+Set `fields.technical.enabled: false` (or clear `names`) to show them.
+
+With Fuse Keycloak authentication, the shared `AuditUserNamePipe` displays audit
+UUIDs as first + last name in lists, cards, and details using the configured user
+middleware. Lookups are cached in memory; existing names pass through, and missing
+or inaccessible users retain their original ID. Entity values and write payloads
+are unchanged. Applications without a configured directory retain the ID.
+
+Lists observe their available width and use cards below `ui.cardBreakpointPx`
+(default `640`). Actions saves the explicit card/table preference in localStorage;
+widening the list restores that preference. New/Edit drawer openings mount a fresh
+form, and closing clears its selected entity. Late edit responses cannot replace a
+newer form session.
+
+Regression checks: `npm run test:ui-state` (Node 24+). Browser checks live in
+`e2e/tests/list-state.spec.js`; run them against a generated **mock** app, never a
+live backend. For an isolated server on port 4201, use
+`npx playwright test --config=playwright.list-state.config.js`. Set
+`CRUDFORGE_BROWSER_CHANNEL=chrome` to use installed Chrome, or install Playwright's
+Chromium with `npm run test:e2e:install`.
+
+### Per-field input formatting and audit inputs
+
+Configure exact GDL/JDL entity and field names in the project's
+`config/crudforge.config.yml`, then run `crudforge generate` using the existing
+file-overwrite policy. For example, with `Province.provinceCode` and
+`Province.provinceName` defined as strings:
+
+```yaml
+fields:
+  entities:
+    Province:
+      fields:
+        provinceCode: { inputFormat: uppercase }
+        provinceName: { inputFormat: lowercase }
+        index: { inputFormat: none }
+  audit:
+    hideInForms: true
+    hideInFilters: true
+    hideInSearch: true
+  technical:
+    enabled: true
+    names: [debug, refType, refId]
+```
+
+`uppercase` and `lowercase` change typed/pasted values, create defaults, loaded
+edit values and outgoing service payloads. `none` preserves case and is the
+default. Only editable `String` and `TextBlob` fields support these preferences;
+unknown entities/fields, enum/number/date/UUID/audit/technical fields and unsupported options
+are rejected before generation. Existing validators still run on the formatted
+value. The shared text accessor preserves cursor/selection positions and waits
+for composition input to finish. Null values remain null, and partial payloads
+retain only their original keys.
+
+The generator emits the resolved `fields` map into each entity's existing
+`settings/settings.config.ts`. Edit the YAML source to retain preferences across
+regeneration. Legacy `formBehavior.uppercaseInputs: true` supplies uppercase for
+otherwise unconfigured text fields; an explicit per-field `none` overrides it.
+
+Audit controls, filter entries and search-field choices are hidden by default.
+These flags can independently opt them back in with `false`. Hidden controls do
+not erase existing audit model values. A saved search-field choice that is no
+longer available resets to the first supported choice. Global search continues
+to use the backend's existing `query` contract; its server-side search scope is
+not redefined by these UI preferences.
+
+### Authenticated Fuse identity
+
+Keycloak builds bind the shared Fuse user menu and optional Account settings page
+to `AuthService.profile`, derived from the configured provider's authenticated
+JWT claims. Display-name priority is `name`, `given_name` + `family_name`, username,
+then email. The `picture` claim supplies an avatar when present; otherwise initials
+are shown. Missing email stays blank. UTF-8 names are decoded correctly. Profile
+state updates on token hydration/refresh and clears on logout, with no sample-user
+fallback for real authentication. Demo claims are used only by `auth.useMockAuth`.
+No additional profile endpoint or client secret is required.
+
+Run `npm run test:field-preferences` for field/profile behavior checks (Node 24+).
+For browser regressions, generate an isolated fixture with
+`npm run e2e:prepare:field-profile`, start it on port 4201, then run
+`npx playwright test --config=playwright.field-profile.config.js`.
+Set `CRUDFORGE_BROWSER_CHANNEL=chrome` to use installed Chrome. These tests intercept
+authentication and backend calls, verify profile refresh/account switching and
+formatted payloads, and attach complete console errors/stacks to their results.
+They do not replace verification with real accounts.
+
+## Generated application performance and rendering
+
+Fuse applications default to a client-side SPA. `npm start` uses the development
+configuration; `npm run build` creates production browser assets for the supplied
+Nginx Dockerfile. Strict TypeScript and Angular template checks remain enabled.
+
+To explicitly generate a Node SSR application, set these project inputs before generation:
+
+```yaml
+fuse:
+  enabled: true
+  rendering: ssr
+  ssrAllowedHosts: [localhost, 127.0.0.1, admin.example.com]
+```
+
+Use `crudforge generate`, `npm ci`, `npm run build`, then `npm run serve:ssr`
+(default port 4000). The generated Dockerfile uses Node for SSR. Configure your
+actual deployment host in `ssrAllowedHosts`. Browser-stored authentication remains
+a browser flow; SSR does not acquire the user's browser session on the server.
+Switching rendering modes requires reviewing generated deployment/package changes
+and reinstalling dependencies. Old server files are not automatically deleted from
+existing projects, but are excluded from SPA compilation.
+
+Entity screens and relationship dialogs load on demand. Shared confirmation dialogs,
+resizing, base classes and list styles are generated once. For non-Fuse output, add
+`shared/styles/list-styles.css` and `shared/styles/snackbar-styles.css` to the host's
+global styles. `generate.globals.sharedAssets: false` means you supply the shared
+files yourself. Existing legacy copies are not deleted automatically.
+
+For an existing initialized project, run `crudforge generate --dry-run` first and
+review conflicts. The normal overwrite policy still applies; use explicit overwrite
+only after preserving custom changes. Per-entity list SCSS remains a customization
+hook. Generated lists retain server pagination; relationship selects request the
+first 50 options, so large relationships still need a searchable/paged selector.
+
+See [the performance investigation and reproducible measurements](docs/performance/README.md)
+for the PMB audit comparison, exact benchmark commands and verification limits.
+Run `npm run test:performance` for generator regressions.
+
+---
+
+## 🔍 Stronger Schema & GDL Validation
+
+CRUDForge validates schemas before any application code is generated. Run validation directly:
+
+```bash
+crudforge validate gdl/example.gdl
+crudforge validate gdl/example.gdl --json
+crudforge validate gdl/example.gdl -p config/crudforge.config.yml
+```
+
+### Diagnostics Checks
+- **Syntax & Declarations:** Unclosed braces, invalid directives, malformed field or relationship declarations.
+- **Naming & Identifier Safety:** Duplicate entity/field/enum names, invalid TypeScript reserved words, and output path collisions (e.g. `FooBar` vs `Foo_Bar` both mapping to `foo-bar`).
+- **Types & Field Rules:** Unsupported primitives, enum type existence, valid regex syntax for `pattern(...)`, numeric vs string validation constraints (`min`, `max`, `minlength`, `maxlength`), and inverted ranges (`min > max`).
+- **Relationships:** Undefined source or target entities, undefined relationship display fields, and collisions with scalar/foreign-key fields.
+- **Backend Metadata & Interoperability:** Backend labels (`backend.kind: go-duck | jhipster | custom`) are reported with clear diagnostics without forcing specific vendor naming conventions on custom backends.
+- **Annotations:** Supported entity annotations are `@Audited` / `@EnableAudit`, `@Searchable`, and `@ActiveStatus` (`isActive` injection). Unimplemented annotations (e.g. `@SoftDelete`) produce clear diagnostics rather than silently discarding behavior.
+- **List / IAM tables:** Generated lists follow the tw-hipster / PMB approval layout (slate header band, overlapping white card, outline search toolbar, sticky Actions that match the header band, visible empty state). ACL screen ids match navigation (`micro-functions/{entity}`); button component ids are semantic (`create`, `open-filter`, …). Custom-page stamping: `shared/access-control-tools/` + `npm run access-control:*`. **User Management** matches the PMB IAM list (live count, rocker enabled toggle, pin/flag state, column prefs, skeleton rows); accents use root `fuseTheme` / `fuse.theme.primary` (`primary-*` tokens), not hardcoded emerald. User Details drawer uses a navy identity band, consistent account rows, formatted role chips (system roles hidden), and sticky footer actions.
+
+---
+
+## 🩺 Project Diagnostics (`crudforge doctor`)
+
+Run `doctor` to diagnose local environment, project setup, dependencies, ports, and configuration consistency:
+
+```bash
+crudforge doctor
+crudforge doctor --json
+crudforge doctor --live
+```
+
+### Local Checks (Offline)
+- **Node & Engine Compatibility:** Validates the active Node version against `package.json` engines or starter requirements.
+- **Configuration & Schema:** Verifies configuration syntax, project root anchoring, and schema accessibility.
+- **Lockfile & Dependencies:** Detects lockfile drift between `package.json` and `package-lock.json`, checks for missing `node_modules`, and supports Yarn PnP.
+- **Port Availability:** Tests IPv4 loopback binding for the configured development server port (`devServer.port`, default `4200`).
+- **Service Targets & Proxy Routes:** Ensures valid HTTP(S) URLs, verifies Keycloak authentication fields (`realm`, `clientId`, `serverUrl`), and checks proxy routes.
+- **Secret Redaction:** Automatically redacts passwords, tokens, client secrets, and authorization values from diagnostic output.
+
+### Live Checks (`--live`)
+Optional probe mode for configured `doctor.endpoints`:
+```yaml
+doctor:
+  timeoutMs: 3000
+  endpoints:
+    - url: "http://62.84.188.166:31698/realms/PMB-DEV/.well-known/openid-configuration"
+      description: "Keycloak OIDC Discovery"
+```
+
+### Troubleshooting `crudforge: command not found`
+If `crudforge` is not in your shell's `PATH`:
+1. **Run directly via Node:**
+   ```bash
+   node /path/to/crud-fordge/cli.js <command>
+   ```
+2. **Install globally:**
+   ```bash
+   npm install -g /path/to/crud-fordge
+   # or
+   npm link
+   ```
+3. **Verify npm global bin path:** Ensure `$(npm bin -g)` or `$(npm config get prefix)/bin` is in your shell `PATH` in `~/.zshrc` or `~/.bashrc`.
+
+---
+
+## 🧪 Generated Application Tests & CI
+
+CRUDForge can generate a standalone Playwright smoke suite and CI configuration inside the generated Fuse Angular application:
+
+```yaml
+generate:
+  globals:
+    tests: true
+
+testing:
+  ci: true
+  fixtures:
+    Farmer:
+      referenceCode: "AB12" # Required for regex/pattern-constrained fields
+```
+
+### Generated Smoke Test Suite
+- **Directory Structure:**
+  - `tests/generated/`: Generator-managed mock server (`mock.cjs`), Playwright config (`playwright.config.cjs`), and smoke test cases (`smoke.spec.cjs`).
+  - `tests/custom/`: Dedicated developer test folder. Files placed in `tests/custom/*.spec.cjs` are preserved and never overwritten.
+- **Mock Backend Isolation:** Intercepts all API calls and Keycloak authentication locally using synthetic fixtures. Unmapped outgoing network requests are blocked with `blockedbyclient` to prevent accidental requests to real backends.
+- **Coverage:** Tests application startup, entity navigation, server-side pagination, required-field form validation, create/edit flows, error banner display, loading animations, and Keycloak profile refresh.
+- **Running Smoke Tests in the Generated App:**
+  ```bash
+  npm ci
+  npm run test:smoke:install   # Installs Playwright Chromium
+  npm run test:smoke           # Runs headless Playwright test suite
+  ```
+
+### Continuous Integration (GitHub Actions)
+When `testing.ci: true`, CRUDForge generates `.github/workflows/crudforge-smoke.yml` using `tests/generated/ci.cjs`:
+- Supports `npm`, `pnpm`, and `yarn` based on lockfile detection.
+- Installs frozen dependencies (`npm ci` / `pnpm install --frozen-lockfile` / `yarn install --immutable`).
+- Runs strict production Angular build (`npm run build`).
+- Installs Playwright browser dependencies and executes `test:smoke`.
+- Uploads test failure reports and screenshots as artifacts on test failure without exposing secrets.
+
+
+## Application tests, validation and setup diagnostics
+
+Enable `generate.globals.tests: true` to generate isolated Playwright smoke tests.
+Set `testing.ci: true` to also generate a GitHub Actions build/test workflow. Custom
+tests belong in `tests/custom/`; normal regeneration conflict policies remain in effect.
+
+```bash
+crudforge validate gdl/example.gdl --json
+crudforge doctor
+crudforge doctor --live --json # only explicitly configured read-only endpoints
+crudforge generate
+npm ci
+npm run test:smoke:install
+npm run build
+npm run test:smoke
+```
+
+Validation now uses the same fail-fast pipeline for validate and generate, including
+unsupported annotations and relationship/name collisions. `validation: false` no
+longer permits invalid schemas to generate files. Doctor is read-only; local checks
+work without HTTP access, and live checks require explicit configured endpoints.
+
+See [quality features and exact configuration](docs/quality/README.md) for test
+isolation, custom tests, package managers/CI, diagnostic exit codes, backend contract
+limits, and recovery when the shell cannot find `crudforge`.