@mouryaamit/nx-polystack 0.0.0-stage → 1.0.1

package/USER-MANUAL.md

@@ -0,0 +1,1968 @@
+# @mouryaamit/nx-polystack — User Manual
+
+**Version:** v0.4.0  
+**CLI binary:** `pstack`  
+**Audience:** Developers installing or using the package from npm
+
+---
+
+## Table of contents
+
+1. [Overview](#1-overview)
+2. [Installation](#2-installation)
+3. [pstack CLI — quick reference](#3-pstack-cli--quick-reference)
+   - 3a. [pstack new — create a workspace](#3a-pstack-new--create-a-workspace)
+   - 3b. [pstack update — upgrade a workspace](#3b-pstack-update--upgrade-a-workspace)
+   - 3c. [pstack infra — repo docs, CI gates, quality checks](#3c-pstack-infra--repo-docs-ci-gates-quality-checks)
+4. [pstack preset — bootstrap a workspace](#4-pstack-preset--bootstrap-a-workspace)
+5. [pstack app — scaffold an application](#5-pstack-app--scaffold-an-application)
+6. [Nx plugin usage — generators](#6-nx-plugin-usage--generators)
+7. [Nx plugin usage — executors](#7-nx-plugin-usage--executors)
+8. [Helper modules](#8-helper-modules)
+9. [Release packaging](#9-release-packaging)
+10. [Troubleshooting](#10-troubleshooting)
+
+---
+
+## 1. Overview
+
+`@mouryaamit/nx-polystack` is a reusable Nx plugin for scaffolding multi-technology monorepos
+that target Angular, Ionic, Flutter, Android, and iOS from a single workspace. It ships:
+
+| Feature                                                                                                                                                          | Available |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| `pstack` CLI binary — `preset` and `app` commands                                                                                                                | v0.1.0    |
+| `:preset` generator — workspace root skeleton                                                                                                                    | v0.1.0    |
+| `:app --type=angular` generator — Angular 15 SPA shell                                                                                                           | v0.1.0    |
+| `:app --type=flutter` generator — Flutter project shell                                                                                                          | v0.1.0    |
+| `:build` executor — full Angular/Ionic build pipeline                                                                                                            | v0.1.0    |
+| `:flutter-build` executor — Flutter CLI wrapper                                                                                                                  | v0.1.0    |
+| `:flutter-export` executor — FlutterFlow export integration                                                                                                      | v0.1.0    |
+| Helper library — encrypt-env, inject-meta, inject-nonce, inject-sri, strip-exif, ci-resolve                                                                      | v0.1.0    |
+| Global install (GitHub release asset) with delegation to the workspace copy                                                                                      | v0.3.0    |
+| `pstack new <dir>` — create a workspace                                                                                                                          | v0.3.0    |
+| `pstack update` — bump the pinned tag and run migrations                                                                                                         | v0.3.0    |
+| Migration runner (`migrations.json`, hidden `pstack _migrate`)                                                                                                   | v0.3.0    |
+| Angular apps build: `build` = Angular builder, `release` = hardened pipeline                                                                                     | v0.4.0    |
+| Angular 15 (`~15.2.0`) added to `package.json` when the workspace has none                                                                                       | v0.4.0    |
+| `:build` executor options `buildTarget` / `buildConfiguration`, custom envs (QA)                                                                                 | v0.4.0    |
+| `angular-release-target` migration for apps generated by v0.3.x                                                                                                  | v0.4.0    |
+| Lint packages in new workspaces; missing Angular build/lint packages filled in per package                                                                       | v0.4.1    |
+| `:app --type=ionic` — Ionic 7 + Capacitor 5 app; `:capacitor` executor                                                                                           | v0.5.0    |
+| Release hardening: leak check, source-map guard, strip comments, drop console (UAT/PROD)                                                                         | v0.29.0   |
+| Opt-in obfuscation, SRI for every chunk, runtime integrity check, ngsw hashes; `pstack hardening`                                                                | v0.30.0   |
+| Obfuscation levels (light, medium, strong) and `obfuscateOptions` overrides                                                                                      | v0.31.0   |
+| `pstack build --env=<env>` for all apps with a summary; base href per configuration (`pstack app --base-href`, `pstack release`)                                 | v0.32.0   |
+| `pstack csp`: `.htaccess` and `nginx.conf` from `csp-allowlist.json`, strict CSP with a per-request nonce (Apache SSI, Nginx sub_filter)                         | v0.33.0   |
+| `pstack env --name=<env> --app=<a,b>\|--all`: add an environment later, copied from an existing one (placeholders for secrets, release config, Flutter, scripts) | v0.34.0   |
+| App options: free dev-server port / `--port`, `clean` target, shared assets and styles (`pstack shared`), `--env-layout=per-env`                                 | v0.35.0   |
+| Quality: `typecheck` target and CI step, import/unused-imports ESLint warnings, non-blocking lint-staged (`pstack infra --lint-staged`)                          | v0.36.0   |
+| Lib starters: `pstack lib --type=session` (idle/session timeout, cross-tab) and `--type=pii` (masking pipe and directive)                                        | v0.37.0   |
+| `pstack csp --import`: merge an existing policy (.htaccess, nginx.conf, header value, JSON) into csp-allowlist.json                                              | v0.38.0   |
+
+---
+
+## 2. Installation
+
+### Option A — global install (recommended)
+
+```bash
+npm i -g @mouryaamit/nx-polystack
+pstack --version
+pstack --help
+```
+
+Requires npm 7+, which installs the `nx` and `@nx/devkit` peer dependencies next to the global package.
+
+Note: `npm install` inside a new workspace (run by `pstack new`) downloads sharp's prebuilt binaries, so it needs network access.
+
+### Option B — npx (no install)
+
+```bash
+npx --package=@mouryaamit/nx-polystack pstack new my-workspace
+```
+
+### Option C — dev dependency in a workspace
+
+Add the plugin to an existing Nx workspace so Nx can discover its generators and executors:
+
+```bash
+npm install --save-dev --save-exact @mouryaamit/nx-polystack
+npx nx list @mouryaamit/nx-polystack
+```
+
+### System requirements
+
+| Requirement                 | Version |
+| --------------------------- | ------- |
+| Node                        | 20.x    |
+| npm                         | 10+     |
+| Nx (workspace install only) | 17.x    |
+
+---
+
+## 3. pstack CLI — quick reference
+
+```
+USAGE
+  pstack <command> [options]
+
+COMMANDS
+  new <dir>   Create a new polystack workspace in <dir> (installs deps, initialises git)
+  update      Upgrade this workspace's nx-polystack version and run its migrations
+  preset      Bootstrap a workspace root skeleton in the current directory
+  app         Scaffold a new application into an existing workspace
+  env         Add an environment to some or all apps later, copied from an existing one
+              (env file, build/serve/release configurations, Flutter env, npm scripts)
+  llm         Write or refresh the generated workspace block in CLAUDE.md, AGENTS.md and
+              .github/copilot-instructions.md (app/lib/env refresh it automatically)
+  migrate     Copy an existing project into the workspace, source never modified: a standalone
+              Angular CLI, Ionic/Capacitor or Flutter app (apps/<name>), the apps and libraries
+              of a multi-project Angular CLI repo (apps/, libs/), the Angular, Ionic and
+              Flutter projects of an Nx 15-17 workspace (same paths, names and aliases), or the
+              app and TypeScript library packages of an npm, Yarn or pnpm workspaces repo
+              (apps/, libs/)
+  infra       Add repo docs, CI gates (affected lint/test/build, dependency cycles), quality
+              checks (knip, pre-push audit + secret scan) and a dependency-upgrade workflow
+
+OPTIONS — new / preset
+  --npmScope=<scope>           npm scope for the workspace (default: mouryaamit)
+  --baseBranch=<branch>        Default git branch (default: master)
+  --infra=<parts>              Run pstack infra with these parts: docs,ci,quality,upgrades | all |
+                               none (default: all)
+  --ci=<providers>             CI for the infra ci part: github-actions | jenkins (comma-separated;
+                               default: github-actions)
+  --ci-cache, --flutter=<mode>, --upgrade-schedule=<s>, --upgrade-scope=<s>
+                               passed to pstack infra
+  --llm=<tools>                AI-assistant files, as pstack llm: claude | agents | copilot
+                               (codex, openai-gpt → agents; comma-separated)
+  --projectDescription=<text>  Short project description
+  --skipFormat                 Skip Prettier format pass
+  --skip-install               new only — do not run npm install
+  --skip-git                   new only — do not initialise git
+  --force                      new only — allow creating inside another Nx workspace
+
+OPTIONS — update
+  --to=<version>               Target version (default: this CLI's version)
+  --allow-dirty                Run with uncommitted changes
+  --force                      Allow downgrading
+
+OPTIONS — app
+  --type=<type>                App type: angular | ionic | flutter  (required)
+  --name=<name>                Application name (required)
+  --tags=<tags>                Comma-separated Nx tags
+  --cspConnectSrc=<url>        Angular only — pre-fill CSP connect-src in csp-allowlist.json
+  --dir=<path>                 Put the app in apps/<path>/<name> (v0.17.0+)
+  --port=<n>                   Dev-server port (default: the lowest free port from 4200; v0.35.0+)
+  --env-layout=<layout>        Angular/Ionic — default | per-env (v0.35.0+)
+
+OPTIONS — shared (--app or --all required; v0.35.0+)
+  --app=<a,b>                  Angular/Ionic apps to wire the shared assets and styles into
+  --all                        Every Angular/Ionic app
+
+OPTIONS — env
+  --name=<name>                Environment slug, e.g. qa, sit, staging (required)
+  --app=<a,b> | --all          Apps to add it to (one of them is required)
+  --from=<env>                 Environment to copy (default uat); secret values become
+                               ${APP_ENV_KEY} placeholders filled at build time
+  --api-url=<url>              API base URL of the new environment
+  --production[=false]         production flag of the new Angular env file (default: as --from)
+  --base-href=<path>           Base href of the new configuration (default: as --from)
+  --domains=<hosts>            aes-gcm domain lock of the new release configuration
+
+OPTIONS — migrate
+  --source=<path>              Project to migrate: its repo root (required; read only)
+  --name=<name>                App name, kebab-case (default: the Angular project name or
+                               the pubspec name); for workspace sources the report name
+  --adapter=<id>               Skip detection: angular-cli | flutter | nx-workspace | angular-workspace | ionic |
+                               npm-workspaces, or an adapter listed in nx.json
+  --min-confidence=<n>         Use the best adapter when it reaches n (0.50 to 1.00; default 0.80; v0.15.0+)
+  --dir=<path>                 Single-app sources: put the app in apps/<path>/<name> (v0.16.0+)
+  --detect                     Print the detection table (adapter, confidence, reasons) and
+                               exit; writes nothing, works outside a workspace
+  --projects=<a,b>             Workspace sources: projects to migrate (default: every supported one)
+  --no-deps                    Workspace sources: only the --projects named, not the libs they import
+  --prefix=<p>                 Workspace sources: rename projects to <p>-<name> (aliases kept)
+  --force-angular              Migrate even when the workspace and the source use different
+                               Angular majors (the report flags it)
+  --max-files=<n>              Fail when more than n files would be copied (default: 20000)
+  --no-rewrite-imports         Keep the copied imports as they were (v0.21.0+). By default,
+                               relative imports into another moved project, imports through the
+                               source baseUrl, @nrwl/* packages and relative SCSS paths are
+                               rewritten in the copies; the report lists each one
+  --rollback=<name>            Undo migration <name> (v0.13.0+): removes the files it created and
+                               reverts its package.json/tsconfig/nx.json changes; anything edited
+                               since is kept and listed in docs/migrations/<name>.rollback.md
+  --force                      With --rollback: remove or restore the edited items too
+  --config=<file>              Run the migrations listed in a JSON batch file (v0.14.0+), all or
+                               nothing: { "defaults": {...}, "migrations": [ { "source": ... } ] };
+                               relative sources are resolved from the file's folder
+  Writes docs/migrations/<name>.md and <name>.manifest.json (for --rollback). Without
+  --adapter the most confident adapter is used if its confidence is at least 0.80.
+
+OPTIONS — infra
+  --with=<parts>               docs | ci | quality | upgrades, comma-separated, or all | none
+                               (default: all)
+  --ci=<providers>             github-actions | jenkins, comma-separated (default: github-actions);
+                               the upgrade workflow is GitHub Actions only
+  --ci-cache                   GitHub Actions: cache the Nx cache directory between runs
+  --flutter=<mode>             Set up Flutter in CI: auto (when a pubspec.yaml is under apps/ or
+                               libs/) | on | off; default auto
+  --upgrade-schedule=<when>    weekly (Monday 03:17 UTC) | monthly (1st, 03:17 UTC); default weekly
+  --upgrade-scope=<scope>      polystack (pstack update) | nx-minor (also nx migrate within the
+                               current Nx major); default polystack
+  --lint-staged=warn|block     ESLint on commit: report only (warn) or block on errors (v0.36.0+)
+  --force                      Overwrite files that already exist (.husky/pre-push is always
+                               appended to, never replaced)
+  Existing files are kept and listed; npm scripts and dependencies are only added when missing.
+
+GLOBAL FLAGS
+  --dry-run, -d                Preview changes without writing files
+  --verbose                    Verbose output
+  --help,    -h                Show this help
+  --version, -v                Print version
+
+Flag values must use --flag=value (a space-separated value is read as an argument).
+```
+
+**Version delegation.** Run inside a workspace that has `@mouryaamit/nx-polystack` in `node_modules`,
+the global `pstack` hands `app`, `env`, `preset`, `migrate` and `infra` to that workspace's copy. `app`, `env`,
+`migrate` and `infra` run from the workspace root (a relative `migrate --source` is made absolute first); `preset`
+and any other command run from the current directory. `pstack migrate` needs nx-polystack 0.12.0 or newer (0.13.0 for `--rollback`, 0.14.0 for `--config`, 0.15.0 for `--min-confidence`, 0.16.0 for `--dir`) pinned
+in the workspace, `pstack infra` 0.9.0 or newer. If the workspace
+copy is older than the global CLI you get a one-line hint to run `pstack update`. `new`, `update`, and `help` /
+`--help` / `--version` always run from the global CLI.
+
+---
+
+## 3a. pstack new — create a workspace
+
+```bash
+pstack new <dir> [--npmScope=<scope>] [--baseBranch=<branch>] [--infra=…] [--ci=…] [--llm=…]
+                 [--projectDescription=…] [--skip-install] [--skip-git] [--force] [--dry-run]
+```
+
+1. Refuses a non-empty `<dir>`, and a `<dir>` inside another Nx workspace unless `--force`.
+2. `--baseBranch` must match `/^[\w./-]+$/` (letters, digits, `_`, `.`, `/`, `-`).
+3. Generates the same files as `pstack preset`, plus `@mouryaamit/nx-polystack` pinned to the CLI's version.
+   That includes the `pstack infra` files (§3c), all four parts by default; `--infra=none` skips them and
+   `--infra=docs,ci` (any subset) picks parts. `--ci` (default `github-actions`), `--ci-cache`, `--flutter`,
+   `--upgrade-schedule` and `--upgrade-scope` are passed to it.
+4. Runs `git init -b <baseBranch>`, then `npm install`, then `git add -A` and
+   `git commit --no-verify -m "chore: initial polystack workspace"`. `git init` comes first because the generated
+   `prepare` script runs husky, which needs `.git`; `--no-verify` skips the hooks for that first commit.
+   Later commits run the pre-commit hook: `npx lint-staged`, configured in `package.json` (Prettier on
+   changed `ts/html/scss/json/md` files, `eslint --fix` on `ts`). Workspaces created before v0.18.1 had
+   no lint-staged config, so their commits failed; the 0.18.1 migration `add-lint-staged-config` adds it
+   (`pstack update`).
+5. If git is missing or a git step fails, `pstack new` warns and continues without git. If `npm install` fails the
+   files stay in place; fix the error and re-run `npm install` there.
+
+---
+
+## 3b. pstack update — upgrade a workspace
+
+```bash
+pstack update [--to=<version>] [--dry-run] [--allow-dirty] [--force]
+```
+
+1. Reads the pinned version of `@mouryaamit/nx-polystack` from `package.json` (`1.2.0`, or the installed
+   version for a range such as `^1.2.0`).
+2. Target is `--to`, else the global CLI's version. Downgrades need `--force`. If the global CLI is older than the
+   workspace pin, `update` tells you to upgrade the global CLI first (or pass `--force`).
+3. Needs a clean git tree unless `--allow-dirty`. The check covers only the workspace folder.
+4. Installs with `npm install @mouryaamit/nx-polystack@<to> --save-dev --save-exact` (`--save-prod` if the plugin
+   is under `dependencies`), so npm rewrites `package.json` itself.
+5. If the install fails, or the installed version is not the one requested, `package.json` and
+   `package-lock.json` are restored (a lockfile created by the failed install is deleted).
+6. Runs every plugin migration newer than the old version and up to the new one, using the new version's code.
+
+A failed migration stops the run; earlier ones stay applied. Review with `git diff`. `--verbose` is passed
+through to the migration step.
+
+`--dry-run` prints the planned change and exits before the dirty-tree check, so it works in a dirty tree.
+
+**If migrations fail.** By then the plugin is already on the new version. `update` prints how to retry:
+either `git checkout -- . && npm install` and then `pstack update` again, or, after fixing the cause, rerun only
+the migrations with `npx pstack _migrate --from=<from> --to=<to>`.
+
+**The 0.4.1 migration.** `add-lint-dependencies` adds the ESLint packages the root `.eslintrc.json` needs
+(`eslint`, `@nx/eslint`, `@nx/eslint-plugin`, `@typescript-eslint/*`, `eslint-config-prettier`) when missing, and,
+for Angular 15 workspaces, any missing build/lint package (`@angular-devkit/build-angular`, `@angular/compiler-cli`,
+`@angular/cli`, `@nx/angular`, `@angular-eslint/*`) at the installed Angular version. It never changes an existing
+version and never adds runtime packages. New workspaces from `pstack new` pin `nx` and `@nx/*` to `~17.0.6`.
+
+**The 0.4.0 migration.** `angular-release-target` rewrites Angular apps generated by v0.3.x so `nx build <app>`
+works and the hardened pipeline moves to `nx run <app>:release:<config>`. See "Upgrading from v0.3.x" in section 5.
+
+**The 0.3.0 migration.** v0.3.0 makes `sharp` and `crypto-js` optional peers, so npm may stop installing them
+automatically. The `add-executor-peers` migration adds `sharp@^0.33.0` and/or `crypto-js@^4.2.0` to
+`devDependencies` when neither `dependencies` nor `devDependencies` already lists them.
+
+---
+
+## 3c. pstack infra — repo docs, CI gates, quality checks
+
+```bash
+pstack infra [--with=docs,ci,quality,upgrades] [--ci=github-actions,jenkins] [--ci-cache] [--flutter=auto|on|off]
+             [--upgrade-schedule=weekly|monthly] [--upgrade-scope=polystack|nx-minor] [--force] [--dry-run]
+npx nx g @mouryaamit/nx-polystack:infra [same options]
+```
+
+Adds the repo files and checks a team needs before the first pull request. `pstack new` (and
+`:preset`) run it with every part by default; `--infra=none` or a subset (`--infra=docs,ci`) changes
+that, and `--ci`, `--ci-cache`, `--flutter`, `--upgrade-schedule` and `--upgrade-scope` are passed through.
+
+| Part       | Files                                                                                                                                                                            | package.json (only when missing)                                                                                     |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `docs`     | `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1 by link), `SECURITY.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/ISSUE_TEMPLATE/{bug,feature,config}.yml` | —                                                                                                                    |
+| `ci`       | GitHub: `.github/workflows/ci.yml`, `.github/workflows/pr-title.yml`; Jenkins: `Jenkinsfile`; both: `tools/scripts/check-cycles.js`, `tools/config/allowed-cycles.json`          | `check:cycles`; GitHub: `@commitlint/cli` + `config-conventional` and `commitlint.config.js` if no commitlint config |
+| `quality`  | `knip.json`, `.secretlintrc.json`, `.secretlintignore`, `.husky/pre-push`                                                                                                        | `stale-code`, `check:prepush`, `check:audit`; `knip`, `secretlint`, its recommended preset, `husky` (+ `prepare`)    |
+| `upgrades` | `.github/workflows/dependency-upgrade.yml` (GitHub Actions only)                                                                                                                 | —                                                                                                                    |
+
+- **Never overwrites.** A file that exists is kept and listed at the end ("pass --force to
+  overwrite"); `--force` replaces it. `.husky/pre-push` is never replaced: the check is appended once,
+  after a `# nx-polystack:infra pre-push` marker line. npm scripts and dependencies are only added
+  when missing; a script that exists with another command is kept and listed. A second run changes
+  nothing.
+- **Placeholders.** `<conduct-contact>` and `<security-contact>` are written as-is and listed under
+  "Fill in".
+- **`ci.yml`** runs on pull requests and on pushes to the base branch (nx.json
+  `affected.defaultBase`, else `master`): checkout with full history, setup-node from `.nvmrc`,
+  `npm ci`, `nrwl/nx-set-shas` (`main-branch-name` = the base branch),
+  `npx nx affected -t lint typecheck test build --parallel=3`, `npm run check:cycles`. `--ci-cache` adds an
+  `actions/cache` step for the Nx cache (`.nx/cache`, or nx.json `cacheDirectory`).
+- **Flutter.** `--flutter=auto|on|off` (default `auto`). With `auto`, when a `pubspec.yaml` exists
+  under `apps/` or `libs/`, `ci.yml` gets a `subosito/flutter-action@v2` step (`channel: stable`,
+  `cache: true`) after setup-node, and the `Jenkinsfile` runs `flutter --version` first in Install
+  (Flutter must be on the agent's PATH). A new workspace has no Flutter project yet: after
+  `pstack app --type=flutter`, run `pstack infra --with=ci --force` to add the step.
+- **`pr-title.yml`** checks the pull request title with the workspace's own commitlint
+  (`echo "$TITLE" | npx --no-install commitlint`); no third-party action.
+- **`Jenkinsfile`**: install, affected lint/test/build (base: `origin/$CHANGE_TARGET` for pull
+  requests, `HEAD~1` on the base branch, else `origin/<base>`), cycles.
+- **Cycle gate.** `npm run check:cycles` reads the project graph (`nx graph --file=<tmp>.json`),
+  finds cycles (strongly connected groups, plus self-dependencies; `npm:` packages ignored) and fails
+  only on cycles not listed in `tools/config/allowed-cycles.json` (`[["app-a","lib-b"]]`, any order).
+  It is plain Node with no dependencies; `--graph=<file>` reads a saved graph instead.
+- **Stale code.** `npm run stale-code` runs `knip --no-exit-code`: a report, never a failure.
+  `knip.json` lists the entry and project globs, the plugin under `ignoreDependencies`, and
+  `flutter`/`dart` under `ignoreBinaries` only when the workspace has Flutter. `pstack lib
+--type=design-tokens` adds its `generated/**` and `src/lib/tokens.ts` outputs to the `ignore`
+  list of an existing `knip.json`. A `knip.json` written by v0.9.0 still has `**/dist/**`,
+  `libs/**/generated/**`, `crypto-js`/`sharp` and `dart` entries; knip prints them under
+  "Configuration hints" when they match nothing. The hints are harmless; delete those entries to
+  silence them.
+- **Pre-push.** `npm run check:prepush` runs `secretlint "**/*"` first (node_modules, dist, .nx and
+  the lockfile are ignored), which blocks the push on a finding, then
+  `npm audit --omit=dev --audit-level=high` as a warning only, and ends with a line pointing to
+  `npm run check:audit`, the strict audit that fails on high or critical advisories. (Advisories
+  with no fix for the workspace's framework major would otherwise block every push.) The 0.9.1
+  migration `prepush-audit-warn-only` rewrites a `check:prepush` that is exactly the v0.9.0 default
+  and adds `check:audit` when missing.
+- **Upgrade workflow.** Weekly (Monday 03:17 UTC) or `--upgrade-schedule=monthly` (the 1st, 03:17
+  UTC), plus a manual run. `polystack` scope: `pstack update --to=<latest release>`; `nx-minor` also
+  runs `nx migrate nx@<current major>`, `npm install` and the Nx migrations. Opens or updates the
+  `chore/dependency-upgrade` pull request (`chore(deps): scheduled dependency upgrade`) with
+  `peter-evans/create-pull-request@v6`, and `subosito/flutter-action@v2` when Flutter is set up. With only `--ci=jenkins` it is skipped, with a note.
+
+- **Settings.** The upgrade workflow finds the latest version with `npm view` and needs "Allow GitHub
+  Actions to create and approve pull requests" in the repo settings.
+
+- Actions are pinned to major tags: `actions/checkout@v4`, `actions/setup-node@v4`,
+  `nrwl/nx-set-shas@v4`, `actions/cache@v4`, `peter-evans/create-pull-request@v6`.
+
+The llm block is refreshed and lists the new npm scripts. Through the global CLI, `pstack infra`
+needs nx-polystack 0.9.0 or newer pinned in the workspace.
+
+```bash
+pstack infra                                    # all parts, GitHub Actions
+pstack infra --with=docs,ci --ci=jenkins        # docs and a Jenkinsfile
+pstack infra --with=upgrades --upgrade-schedule=monthly --upgrade-scope=nx-minor
+pstack infra --with=docs --dry-run              # preview
+pstack infra --force                            # overwrite existing files with the templates
+```
+
+---
+
+## 4. pstack preset — bootstrap a workspace
+
+Creates the complete Nx workspace root skeleton in the **current directory**. Run this in a
+freshly created, empty directory.
+
+```bash
+pstack preset [options]
+```
+
+### Options
+
+| Option                        | Default          | Description                                                                                        |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
+| `--npmScope=<scope>`          | `mouryaamit`     | npm scope written into `nx.json` and `tsconfig.base.json` path aliases                             |
+| `--baseBranch=<branch>`       | `master`         | Default git branch (`defaultBase` in `nx.json`)                                                    |
+| `--infra=<parts>`             | `all`            | Runs `:infra` (§3c) with these parts: `docs`, `ci`, `quality`, `upgrades`; or `all`, `none`.       |
+| `--ci=<providers>`            | `github-actions` | CI for the `:infra` ci part. Values: `github-actions`, `jenkins`. Comma-separated for multiple.    |
+| `--llm=<tools>`               | —                | Runs `:llm` for these providers: `claude`, `agents`, `copilot` (`codex`, `openai-gpt` → `agents`). |
+| `--projectDescription=<text>` | —                | Short project description written into `package.json`                                              |
+| `--skipFormat`                | false            | Skip the Prettier format pass after generation                                                     |
+| `--skipInstall`               | false            | No-op for `preset` (it never installs); kept for compatibility                                     |
+
+### What is generated
+
+**Always generated (workspace root skeleton):**
+
+```
+nx.json
+tsconfig.base.json
+package.json
+.nvmrc               Node 20
+.npmrc               legacy-peer-deps=true
+.editorconfig
+.gitattributes
+.gitignore
+.prettierrc
+.prettierignore
+.eslintrc.json
+.eslintignore
+commitlint.config.js
+.husky/
+  pre-commit
+  commit-msg
+tools/config/
+  sri-cdn-allowlist.json
+(nx.json also gets pstack.envEncryption — see "Env encryption settings (v0.25.0)")
+```
+
+**Repo infrastructure (`--infra`, default all parts; written by `:infra`, see §3c):** repo docs,
+CI (`--ci=github-actions`: `.github/workflows/ci.yml` and `pr-title.yml`; `--ci=jenkins`: `Jenkinsfile`;
+both: the dependency-cycle check), quality checks (knip, pre-push audit + secretlint) and, with GitHub
+Actions, `.github/workflows/dependency-upgrade.yml`. The old `.github/workflows/build.yml` template is gone.
+
+**Conditional — AI-assistant instructions (`--llm`, written by `:llm` after formatting):**
+
+| Flag value             | File                              |
+| ---------------------- | --------------------------------- |
+| `claude`               | `CLAUDE.md`                       |
+| `agents`               | `AGENTS.md`                       |
+| `codex` / `openai-gpt` | `AGENTS.md` (aliases of `agents`) |
+| `copilot`              | `.github/copilot-instructions.md` |
+
+Unknown values fail with the supported list. `.codex/instructions.md` is no longer generated.
+See `:llm` in §6 for the block these files get.
+
+### Examples
+
+```bash
+# Minimal workspace
+mkdir my-workspace && cd my-workspace
+pstack preset --npmScope=acme
+
+# Full setup — GitHub Actions CI + Claude AI config
+pstack preset --npmScope=acme --ci=github-actions --llm=claude
+
+# Jenkins CI + Claude + Copilot
+pstack preset --npmScope=acme --ci=jenkins --llm=claude,copilot
+
+# Skeleton only, no repo docs / CI / checks
+pstack preset --npmScope=acme --infra=none
+
+# Preview without writing
+pstack preset --npmScope=acme --dry-run
+```
+
+---
+
+## 5. pstack app — scaffold an application
+
+Adds a new application to an **existing Nx workspace**. Must be run from the workspace root
+(where `nx.json` exists). If no `nx.json` is found, the command exits with an error.
+
+```bash
+pstack app --type=<type> --name=<name> [options]
+```
+
+### Options
+
+| Option                  | Required | Description                                                                |
+| ----------------------- | -------- | -------------------------------------------------------------------------- |
+| `--type=<type>`         | Yes      | Application type: `angular`, `ionic` or `flutter`                          |
+| `--name=<name>`         | Yes      | Application name — becomes `apps/<name>/` (or `apps/<dir>/<name>/`)        |
+| `--dir=<path>`          | —        | Put the app in `apps/<path>/<name>` (v0.17.0+, rules below)                |
+| `--tags=<tags>`         | —        | Comma-separated Nx tags (e.g. `platform:web,scope:app`)                    |
+| `--cspConnectSrc=<url>` | —        | Angular/Ionic — pre-fills the `connect-src` entry in `csp-allowlist.json`  |
+| `--appId=<id>`          | —        | Ionic only — Capacitor appId (default `com.example.<name without dashes>`) |
+
+`--dir` takes kebab-case folders separated by `/` (at most three; not `dist`, `tmp`, `coverage` or
+`out-tsc`; not through another project). Relative paths and build output (`dist/apps/<dir>/<name>`)
+follow the folder; the project name, npm scripts, `environments/<name>/` and the
+`@mouryaamit/<name>` alias stay keyed by name. A name another project already uses is refused, with
+or without `--dir`. Needs nx-polystack 0.17.0 in the workspace and a 0.17.0 global CLI.
+
+### What is generated — Angular (`--type=angular`)
+
+```
+apps/<name>/
+  project.json              Nx targets: build, serve, release, lint, extract-i18n
+  tsconfig.json
+  tsconfig.app.json
+  tsconfig.spec.json
+  .eslintrc.json
+  csp-allowlist.json        CSP overrides (per-app)
+  src/
+    index.html
+    main.ts                 platformBrowserDynamic().bootstrapModule(AppModule)
+    styles.scss
+    .htaccess               Apache SPA routing, CSP with a per-request nonce, security headers (pstack csp)
+    app/
+      app.module.ts         BrowserModule + HttpClientModule
+      app.component.ts      OnPush change detection
+      app.component.html
+      app.component.scss
+      app-routing.module.ts Empty routes array
+  server/
+    nginx.conf              Nginx try_files + security headers
+    README.md               Deployment notes
+
+environments/<name>/
+  environment.ts
+  environment.uat.ts
+  environment.prod.ts
+```
+
+**Also adds:**
+
+- 6 npm scripts to root `package.json` (see the table below)
+- `tsconfig.base.json` path alias: `@mouryaamit/<name>` → `apps/<name>/src`
+- Nx tags: `scope:app`, `type:app`, `platform:web`
+
+**Targets in `project.json`:**
+
+| Target                 | Executor                                   | What it does                                                                                                                                                                                                                                                                           |
+| ---------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build`                | `@angular-devkit/build-angular:browser`    | Plain Angular build to `dist/apps/<name>`. Configurations `production` (default), `uat`, `development`; `production` and `uat` swap `environments/<name>/environment.ts` for the `.prod.ts` / `.uat.ts` file. Assets include `src/.htaccess`.                                          |
+| `serve`                | `@angular-devkit/build-angular:dev-server` | Dev server; configurations `production` / `uat` / `development` point at the matching `build` configuration. Default `development`.                                                                                                                                                    |
+| `release`              | `@mouryaamit/nx-polystack:build`           | Hardened pipeline that wraps `build` (`buildTarget: <name>:build`): env encryption, EXIF stripping, build meta, optional CSP nonce / SRI, and non-DEV release hardening (leak check, source maps, comments, console, obfuscation). Configurations `dev`, `uat`, `prod`; default `dev`. |
+| `lint`, `extract-i18n` | `@nx/eslint:lint`, Angular extract-i18n    | Unchanged.                                                                                                                                                                                                                                                                             |
+
+`nx build <name>` is a plain Angular build. Use `nx run <name>:release:prod` for the hardened build.
+
+**npm scripts:**
+
+| Script                         | Command                                     |
+| ------------------------------ | ------------------------------------------- |
+| `serve:<name>`                 | `nx serve <name>`                           |
+| `build:<name>:dev`             | `nx run <name>:release:dev`                 |
+| `build:<name>:uat`             | `nx run <name>:release:uat`                 |
+| `build:<name>:prod`            | `nx run <name>:release:prod`                |
+| `build:<name>:prod:secure`     | `nx run <name>:release:prod --secure`       |
+| `build:<name>:prod:secure:sri` | `nx run <name>:release:prod --secure --sri` |
+
+**Angular version.** Generated apps target Angular 15. Packages are only ever added, never upgraded:
+
+- No `@angular/core` in the workspace → the Angular 15 set (`~15.2.0`, TypeScript `~4.9.5`) plus the lint packages
+  (`@nx/angular`, `@nx/eslint` at the workspace's Nx version, `@angular-eslint/*` `~15.2.0`) is added.
+- Angular 15 already installed → missing build and lint packages are added at your installed Angular version
+  (`@angular-devkit/build-angular`, `@angular/compiler-cli`, `@angular/cli`, `@nx/angular`, `@nx/eslint`,
+  `@angular-eslint/*`), plus the runtime packages the generated code imports (`@angular/common`, `compiler`,
+  `platform-browser`, `platform-browser-dynamic`, `router`, `rxjs`, `tslib`, `zone.js`). Existing versions are kept.
+- Another Angular major → nothing is added; `pstack app` prints which packages to install at versions matching
+  your Angular. Angular 16–17 likely work with the generated files.
+
+**Upgrading from v0.3.x.** Apps generated by older versions have a `build` target that runs the plugin executor and
+cannot build. `pstack update` runs the `angular-release-target` migration, which moves that target to `release`,
+gives `build` the Angular builder, renames `serve` configurations, and rewrites matching npm scripts to
+`nx run <app>:release:<config>`. Details:
+
+- Custom configurations (e.g. `qa`) are carried over to `build` and `release`.
+- Only `nx run <app>:build:<config>` commands are rewritten in scripts (matched on word boundaries; a trailing `--` is dropped).
+- Ionic and other non-Angular apps, and apps that already have a `release` target, are skipped (the latter with a warning).
+- Re-running is a no-op.
+
+### What is generated — Ionic (`--type=ionic`)
+
+An Angular app (everything in the Angular section above) turned into an Ionic 7 + Capacitor 5 app:
+
+- `src/app/app.module.ts` imports `IonicModule.forRoot()` and uses `IonicRouteStrategy`; `app.component.html` is
+  `<ion-app><ion-router-outlet>`; `index.html` has a mobile viewport (`viewport-fit=cover`); `styles.scss` imports the
+  Ionic core CSS; ionicons SVGs are copied to `/svg` by the build.
+- `capacitor.config.ts` — `appId` (`--appId`), `appName`, `webDir: '../../dist/apps/<name>'`.
+- `package.json` in the app folder — its own `@capacitor/core`, `android`, `ios` and `cli` (`~5.7.0`), kept out of
+  the root install; plus a `.gitignore` for its `node_modules` and native build output.
+- `project.json`: `build` / `serve` / `release` as for Angular (`release.options.type: ionic`), and
+  `cap-sync`, `cap-open`, `cap-add` (executor `:capacitor`, platform given as `--platform=android|ios`).
+- Root `package.json`: Angular 15 packages as for Angular apps, plus `@ionic/angular ~7.8.0` when missing.
+  `pstack app` then installs the root packages and the app's own package.json.
+
+| Script                                | Command                                                              |
+| ------------------------------------- | -------------------------------------------------------------------- |
+| `build:<name>:<dev\|uat\|prod>`       | `nx run <name>:release:<env>`                                        |
+| `build:<name>:<env>:android` / `:ios` | release build, then `nx run <name>:cap-sync --platform=android\|ios` |
+| `open:<name>:android` / `:ios`        | `nx run <name>:cap-open --platform=android\|ios`                     |
+
+First native build:
+
+```bash
+pstack app --type=ionic --name=field-ops --appId=com.acme.fieldops
+npx nx run field-ops:release:prod
+npx nx run field-ops:cap-add --platform=android     # once — creates apps/field-ops/android
+npm run build:field-ops:prod:android                 # release build + cap sync
+npm run open:field-ops:android                       # opens Android Studio
+```
+
+`pstack env --name=qa --app=<name>` adds `qa` to `build`, `serve` and `release`, plus `build:<name>:qa:android` / `:ios`.
+
+Native prerequisites (Capacitor 5): Node 16+, JDK 17 and Android Studio Flamingo or newer for Android; Xcode 14.1+ and
+CocoaPods for iOS (macOS only). On Linux, set `CAPACITOR_ANDROID_STUDIO_PATH` for `cap-open`.
+
+### What is generated — Flutter (`--type=flutter`)
+
+```
+apps/<name>/
+  project.json              Nx targets: flutter-build (3 configs), serve
+  pubspec.yaml
+  analysis_options.yaml
+  .gitignore
+  lib/
+    main.dart
+  web/
+    index.html              loads flutter_bootstrap.js (no inline script); keeps $FLUTTER_BASE_HREF
+    manifest.json
+  server/
+    nginx.conf
+
+environments/<name>/
+  env.dev.json
+  env.uat.json
+  env.prod.json
+```
+
+Web builds (`build-web`, `serve`) need Flutter 3.22 or later. Add icons under `web/` if you want them.
+
+### Examples
+
+```bash
+# Angular SPA
+pstack app --type=angular --name=portal
+
+# Angular with tags and CSP entry
+pstack app --type=angular --name=admin --tags=platform:web,scope:app --cspConnectSrc=https://api.example.com
+
+# Flutter
+pstack app --type=flutter --name=mobile --tags=platform:mobile
+
+# Preview — no files written
+pstack app --type=angular --name=portal --dry-run
+```
+
+---
+
+## 6. Nx plugin usage — generators
+
+When the plugin is installed as a dev dependency in an Nx workspace, generators can also be invoked
+through Nx directly:
+
+```bash
+npx nx g @mouryaamit/nx-polystack:preset [options]
+npx nx g @mouryaamit/nx-polystack:app --type=angular --name=portal [options]
+
+# Preview without writing
+npx nx g @mouryaamit/nx-polystack:app --type=angular --name=portal --dry-run
+```
+
+All options are identical to the `pstack` CLI flags. The `--dry-run` flag is supported by both Nx and
+the `pstack` CLI.
+
+### `:preset` generator schema
+
+```jsonc
+{
+  "npmScope": "mouryaamit", // string — default: "mouryaamit"
+  "baseBranch": "master", // string — default: "master"
+  "apps": "angular,flutter", // string — comma-separated app types (stored in nx.json)
+  "infra": "all", // string — :infra parts: docs,ci,quality,upgrades | all | none
+  "ci": "github-actions", // string — comma-separated CI providers (default: github-actions)
+  "ciCache": false, // boolean — passed to :infra
+  "flutter": "auto", // "auto" | "on" | "off" — passed to :infra
+  "upgradeSchedule": "weekly", // "weekly" | "monthly" — passed to :infra
+  "upgradeScope": "polystack", // "polystack" | "nx-minor" — passed to :infra
+  "llm": "claude,copilot", // string — comma-separated :llm providers
+  "projectDescription": "...", // string
+  "skipFormat": false, // boolean
+  "skipInstall": false // boolean
+}
+```
+
+### `:llm` generator / `pstack llm` (v0.7.0)
+
+```bash
+pstack llm [--providers=claude,agents,copilot] [--dry-run]
+npx nx g @mouryaamit/nx-polystack:llm --providers=claude,agents,copilot
+```
+
+Writes a generated description of the workspace — npm scope, Nx / Angular / plugin versions, an apps
+table (type detected from targets), environments, a libs table with import aliases, common commands
+and rules — between `<!-- nx-polystack:start -->` and `<!-- nx-polystack:end -->` in `CLAUDE.md`
+(`claude`), `AGENTS.md` (`agents`; `codex` and `openai-gpt` are aliases) and
+`.github/copilot-instructions.md` (`copilot`). Default: all three.
+
+A missing file is created with a title; a file with markers gets only the block replaced; a file
+without markers gets the block appended; malformed markers stop the run with an error naming the
+file. Text outside the block is never changed. `:app`, `:lib` and `:env` refresh the block in files
+that already contain the markers. Through the global CLI, `pstack llm` needs nx-polystack 0.7.0 or
+newer pinned in the workspace.
+
+### `:migrate` generator / `pstack migrate` (v0.8.0, Nx import v0.10.0)
+
+```bash
+pstack migrate --source=<path> [--name=<app>] [--adapter=angular-cli|flutter|nx-workspace|angular-workspace|ionic] [--detect] [--dry-run] [--force-angular]
+               [--projects=<a,b>] [--no-deps] [--prefix=<p>]
+npx nx g @mouryaamit/nx-polystack:migrate --source=<path> [same options]
+```
+
+Copies an existing standalone project into the workspace as `apps/<name>`, in the shape `pstack app`
+produces. The source is only read; git history is not carried over.
+
+- **Detection.** `angular-cli`: `angular.json` with exactly one application project, `@angular/core`,
+  the build `main` file. `flutter`: `pubspec.yaml` with the Flutter SDK, `lib/main.dart`. `nx.json`
+  disqualifies both; more than one Angular application project disqualifies `angular-cli`; an Ionic
+  app scores below the threshold. The best adapter is used at confidence ≥ 0.80; otherwise the
+  command stops with the table and suggests `--adapter`. `--detect` only prints the table.
+- **Angular CLI apps.** Files copied without `node_modules`, `dist`, `.angular`, `.git`, IDE folders,
+  `coverage` and the workspace-level files. `project.json` is built from `angular.json`: every
+  target, every path option moved under `apps/<name>`, `dist/<x>` → `dist/apps/<name>`, target
+  references renamed, plus a polystack `release` target (`production` → `prod`, `development` →
+  `dev`, other configurations keep their name) and an `@nx/eslint:lint` target if missing. The
+  tsconfigs extend `tsconfig.base.json` (source `paths` merged in, clashes reported); the ESLint
+  config extends the root one (or the polystack one is generated). Source dependencies are added only
+  when missing (clashes reported); a different Angular major in the workspace stops the command
+  unless `--force-angular`. `serve:<name>` / `build:<name>:<env>` npm scripts are added; source
+  scripts are listed in the report. Environment files stay where they were.
+- **Flutter apps.** Files are copied without `build`, `.dart_tool`, Pods, Gradle caches, generated
+  plugin lists and `flutter/ephemeral` folders. The app gets the `pstack app --type=flutter` targets
+  and npm scripts, without the FlutterFlow export. Missing `env/dev|uat|prod.json` files are created
+  as `{}`. The report notes pubspec path dependencies outside the source repo, product flavors and
+  extra `lib/main_*.dart` entrypoints.
+- **Both.** In a git work tree only the files git lists are copied. Possible secrets (`.env*`,
+  keystores, `*.pem`, `key.properties`, Firebase configs, `.npmrc`) are never copied, and the report
+  lists them. File modes are kept. `--max-files` (default 20000) caps the copy. Angular 17+
+  application-builder sources are converted to Angular 15 builders (see Angular 17+ sources).
+- **Report.** `docs/migrations/<name>.md`: adapter and confidence, copied/skipped counts and the
+  skipped paths, dependency and alias clashes, source scripts, Angular notes, and a next-steps
+  checklist. The llm block is refreshed.
+- **Undo.** `pstack migrate --rollback=<name>` undoes a migration made with v0.13.0+ from
+  `docs/migrations/<name>.manifest.json`; what was edited since is kept and listed (`--force`
+  overrides, `--dry-run` previews). See the user manual §6.5.
+- **Batches.** `pstack migrate --config=<file>` runs the migrations listed in a JSON file, all or
+  nothing; each entry gets its own report and manifest. See the user manual §6.5.
+
+```bash
+pstack migrate --source=../legacy-portal --detect
+pstack migrate --source=../legacy-portal --name=portal
+pstack migrate --source=../field_notes --adapter=flutter --dry-run
+```
+
+#### Importing from an Nx workspace (v0.10.0)
+
+`pstack migrate --source=../nx-repo` copies the Angular apps, Angular/TS libs and Flutter projects
+of an Nx 15–17 workspace into this one (`nx-workspace` adapter). Projects keep their paths, names and
+import aliases, so no source file is rewritten.
+
+```bash
+pstack migrate --source=../nx-repo --detect                       # project kinds, what can be migrated
+pstack migrate --source=../nx-repo                                # every supported project
+pstack migrate --source=../nx-repo --projects=portal,admin        # these, plus the libs they import
+pstack migrate --source=../nx-repo --projects=portal --no-deps    # only portal
+pstack migrate --source=../nx-repo --prefix=legacy                # projects named legacy-<name>
+```
+
+- Projects come from `project.json` files, `workspace.json` and an Nx `angular.json`. Kinds:
+  Angular app (`browser` / `webpack-browser` build), lib (no build, or an Angular, `js` or
+  run-commands build), Flutter app or package (`pubspec.yaml`), Ionic app (an Angular app with a
+  Capacitor or Ionic config; see below). e2e, Angular 17+ application-builder, Angular SSR,
+  React/Node and root projects are listed in the report as not supported yet.
+- `--projects` brings the libs the named projects need: path-alias imports, `implicitDependencies`
+  and pubspec `path:` dependencies. `--no-deps` turns that off.
+- `--prefix` renames the projects, their target references and implicit dependencies; paths and
+  aliases stay as they are.
+- `@nrwl/*` executors become `@nx/*` (and `@nrwl/nx` in ESLint configs becomes `@nx`); the `@nx/*`
+  plugins they use, and the ng-packagr build packages for buildable Angular libs, are added at the
+  workspace's versions. The source's own Nx packages are not copied.
+- Angular apps get the polystack `release` target, tags and npm scripts; Flutter apps get the
+  polystack Flutter targets, `env/*.json` and npm scripts.
+- The source aliases of copied projects go into `tsconfig.base.json`, named inputs the targets use
+  into `nx.json`, and `jest.preset.js` when Jest targets need it. The report lists the root ESLint
+  `depConstraints`, `tsconfig` compiler options and options pointing outside the copied projects.
+- Nothing is written when a project path, a project name or an alias already exists in the
+  workspace, or the Angular majors differ (`--force-angular`).
+
+The report is `docs/migrations/<name>.md`; `--name` defaults to the source package name.
+
+#### Multi-app Nx sources and shared folders (v0.24.0)
+
+Nx sources with several apps (including Nx 15 repos on `@nrwl/*`) that keep shared files outside
+their projects come over in one run:
+
+- **Folders that are not projects** are copied to the same path. A folder is copied when the
+  projects use it:
+
+  - from `assets`, `styles`, `scripts`, `fileReplacements` and
+    `stylePreprocessorOptions.includePaths`;
+  - from `tsconfig.base.json` (`typeRoots`, `include`);
+  - from files the root npm scripts run (`node tools/scripts/build.js`);
+  - from imports that leave a project: relative imports, imports through `baseUrl: "."` such as
+    `environments/<app>/…`, and SCSS `@use`/`@import`/`@forward`.
+
+  Typical ones are an assets or styles folder under `libs/`, a root `environments/` folder and
+  `tools/`. Root files those scripts or options use (e.g. `postbuild.js`) are copied too. Files the
+  workspace already has (for example `tools/config/*.json`) are kept and listed. Possible secrets
+  (now also `*.key` and `*.pfx`) are never copied. Paths into projects that were not selected are
+  reported, not followed.
+
+- **Root `package.json`:** `overrides`, `browser` and `engines` are carried over (missing keys
+  only; differing ones are listed). An `engines.node` range that leaves out the Node in the
+  workspace's `.nvmrc` is reported instead of carried (since v0.27.1), because the workspace
+  installs with `engine-strict`. A pnpm or Yarn workspace gets a note to move the overrides.
+  Source npm scripts the workspace does not have are kept, so a repo that builds through its own
+  scripts (`build:<app>:<env>` → `node tools/scripts/build.js --project=<app> --env=<env>`) can keep
+  using them. Scripts of the same name keep the source command, and the polystack ones are added
+  only for names that are free. Three kinds of scripts behave differently:
+  - Lifecycle scripts (`postinstall`, `prepare`, …) are never carried over; they are listed.
+  - Scripts that name a project that was not imported are dropped and listed.
+  - With `--prefix`, project names in nx/ng commands of the kept scripts (`nx <verb> <p>`,
+    `nx run <p>:…`, `--project=<p>`) are renamed. A custom script (`node build.js --project=<p>`)
+    keeps the source name, because it looks the name up itself (base hrefs, env folders); the
+    report lists these scripts, so you can update the `nx build` call inside them.
+- **Release target:** added next to those scripts. A source's own `release` target is left as it
+  is.
+
+  - `envProject` comes from the build's `fileReplacements` (`environments/<x>/environment.<env>.ts`).
+  - In that per-env layout (`environment.dev.ts`, no `environment.ts`) the executor reads
+    `environment.<env>.ts` for UAT and PROD; DEV is not encrypted.
+  - Base hrefs come from `nx build … --base-href` flags in the npm scripts, or from a map in the
+    custom build script whose name says base href (`const BASE_HREF = { app: { uat: '/x/' } }` or
+    `{ app: '/x/' }`). Apps whose base hrefs can't be read, or are read differently from two maps,
+    are listed.
+
+  The report says to keep using the repo's scripts until the release target covers their extra
+  steps.
+
+- **CSP nonce patch:** in Angular and Ionic apps, a `main.ts` side-effect import of a local nonce
+  patch that reads the nonce the way the library does (`window.__cspNonce` or the `csp-nonce` meta
+  tag) is replaced by `@mouryaamit/nx-polystack/runtime/csp-nonce`. Other local patches are kept,
+  with the library import added before them. Apps without one get the import first (after any
+  `/// <reference>` lines). Local patch files are not deleted.
+- **Nx 15 specifics:**
+  - `@nrwl/*` executors and ESLint configs become `@nx/*`.
+  - Wildcard aliases (`@scope/lib/*`) of copied libraries are kept.
+  - `baseUrl` is set in `tsconfig.base.json` when the workspace has none and the code imports
+    through it.
+  - A Jest major below 29 gets a note: the workspace's `@nx/jest` needs Jest 29 and
+    `jest-preset-angular` 13.
+
+#### CSP nonce at runtime (v0.24.0)
+
+`@mouryaamit/nx-polystack/runtime/csp-nonce` is a small browser script that new Angular and Ionic
+apps import first in `main.ts`. Under a strict Content-Security-Policy, Angular 15 and webpack add
+`<style>`, `<script>` and stylesheet `<link>` elements at runtime without a nonce, and the browser
+blocks them (Angular 15 has no built-in nonce support).
+
+- **What it patches:** it gives these elements the page nonce when they are inserted, through any
+  of:
+  - `appendChild`/`insertBefore`/`replaceChild` on the document, on elements and on shadow roots;
+  - `append`/`prepend`/`before`/`after`/`replaceWith`/`insertAdjacentElement`.
+- **Where the nonce comes from:** `window.__cspNonce`, or the `csp-nonce` meta tag that
+  `release --secure` writes. An SSI directive the server did not process, or a placeholder such as
+  `random-csp-nonce`, counts as no nonce, and nothing is patched.
+- **Existing apps:** `pstack update` (migration `add-csp-nonce-import`) adds the import to apps
+  with the polystack release target. It never removes a local nonce patch import.
+
+#### Env encryption settings (v0.25.0)
+
+Release builds (`nx run <app>:release:<env>`) encrypt env values for every env except DEV. The
+settings live in `nx.json`:
+
+```json
+"pstack": { "envEncryption": {
+  "mode": "listed",
+  "cipher": "cryptojs",
+  "keySources": ["commit"],
+  "metaName": "x-build",
+  "keys": { "default": [], "web": ["password", "token"] },
+  "format": "raw",
+  "profileFiles": [],
+  "publicKeys": ["production", "envName", "appName", "timeStamp"],
+  "stamp": { "timeField": "timeStamp", "branchField": "branch", "timezone": "UTC",
+             "format": "DD MMM YYYY hh:mm:ss A z" }
+} }
+```
+
+- `mode: "listed"` (default) encrypts the keys of the env project (`keys.<envProject>`, else
+  `keys.default`), wherever `key: '<value>'` appears in the file (as before, the key is not
+  anchored: `key` also matches `apiKey:`). `keys.default` is empty unless you list keys, so nothing
+  is encrypted by default, as before v0.25.0. A listed key whose value is not a plain string is
+  left alone with a warning.
+- `mode: "all"` encrypts every top-level string field except `publicKeys`. The stamp fields are
+  filled first and stay plain only when listed there: the default list has `timeStamp` but not the
+  branch field, so since v0.27.0 the branch is encrypted too (add it to `publicKeys` with
+  `pstack encryption --add-public=branch` to keep it plain). A stamp field that is not a string
+  literal is left as it is. Any other non-public field that is not a literal (a variable, a call,
+  `${…}` in a template), an entry without `key:` (shorthand, spread, computed key) or a missing
+  `environment = { … }` object fails the build. Profile values equal to a stamp value are not
+  encrypted for it.
+  Use it only when the app decrypts every field (`envReady` of `runtime/env-secret`, see Env
+  secrets in the browser).
+- With `cryptojs` the ciphertext is unchanged: CryptoJS AES with the build's commit as the
+  passphrase, the same commit that goes into `<meta name="<metaName>">`. This is obfuscation; real
+  secrets belong on a server. The commit is taken as CI gives it: on GitHub Actions, GitLab,
+  Bitbucket, CircleCI and Azure that is the full 40-character SHA (meta tag and key still match).
+  Build errors never print values.
+- Changing `metaName` needs the same change in apps that read the key from the meta tag.
+- `cipher`: `cryptojs` (default) or `aes-gcm` (v0.28.0, see AES-GCM env encryption).
+  `keySources` (v0.28.0; replaces `keySource`, which `pstack update` renames) lists the
+  aes-gcm key factors (default `["commit"]`); `cryptojs` always uses the commit.
+
+**Secrets out of git.** UAT/PROD env files may hold `${NAME}` placeholders in quoted strings. The
+release build fills them from environment variables, then from `.env.local` at the workspace root
+(`NAME=value` lines; gitignored), and fails listing every missing name. The dev env file must keep
+literal values (`nx serve` does not fill placeholders); a placeholder there fails `release:dev`.
+
+**Build stamp.** When the env file declares `timeStamp` / `branch` (the `stamp` field names), the
+release build fills them with the build time (`timezone`, `format` tokens `YYYY MM MMM DD HH hh mm
+ss A z`, optional `timezoneLabel` for `z`) and the branch. Branch and commit come from CI variables
+(Jenkins, GitHub Actions, GitLab, Bitbucket, CircleCI, Azure Pipelines) or git. Text in `[ ]` is
+kept as is (`[at] HH:mm`).
+
+**Safe restores.** The env file is backed up under `node_modules/.cache/nx-polystack/env-backup`
+and restored after the build, also when it fails; a build that was killed is repaired by the next
+release build of that env file (unless the file was edited since; then it is kept). Release builds
+that share an env file wait for each other (on one machine; builds in different containers
+sharing one workspace are not coordinated). The Angular build runs with `--skip-nx-cache`. While a
+release build runs, the env file holds filled and encrypted values: don't commit it then.
+
+**`pstack encryption`** shows the settings; `--mode`, `--add-key` / `--remove-key`
+(`--project=<envProject>`), `--add-public` / `--remove-public`, `--meta-name`, `--timezone` and
+`--stamp-format` change them. Needs nx-polystack 0.25.0 in the workspace.
+
+**Updating.** `pstack update` (migration `env-encryption-config`) moves
+`tools/config/encrypt-keys.json` into `nx.json` with the same keys (mode `listed`), removes the
+file and adds `.env.local` to `.gitignore`. Builds encrypt the same fields as before. Until then the
+executor still reads the old file and prints a warning.
+
+#### Env secrets in the browser (v0.26.0)
+
+`@mouryaamit/nx-polystack/runtime/env-secret` decrypts what the release build encrypted
+(`crypto-js` comes from the workspace's dependencies). Call it once in `main.ts`, before
+`AppModule` is imported or bootstrapped:
+
+```ts
+import { environment } from '../../../environments/web/environment';
+import {
+  envReadySync,
+  envSecret,
+  envSecretAsync,
+} from '@mouryaamit/nx-polystack/runtime/env-secret';
+
+envReadySync(environment, { sync: ['uname'] }); // or { inPlace: true }, or { sync: 'all' }
+
+envSecret('uname'); // sync: decrypted at startup, or on first call and cached
+await envSecretAsync('password'); // decrypted on every call, nothing kept
+```
+
+- `inPlace: true` decrypts every encrypted value of `environment` (nested objects and arrays too),
+  so code reading `environment.x` gets plaintext.
+- `sync` decrypts the listed top-level fields (or `'all'`) at startup into a private cache, without
+  changing `environment`.
+- `envReady()` is the same as a Promise; with `cipher: aes-gcm` it also decrypts `ENC2(...)`
+  values (see AES-GCM env encryption).
+- `getBuildMeta()`, `decryptEnvValue(value)`, `isEncryptedValue(value)` and `decryptTree(obj)` (in
+  place, any object) are exported too. The module is an ES module; `require()` users such as Jest get
+  a CommonJS copy.
+- Values that are not encrypted (`nx serve`, a plain build) are returned as they are. A value that
+  cannot be decrypted is returned unchanged with one console warning (never the value).
+
+**Build side.** `format: "enc"` writes values as `ENC(<ciphertext>)` (new workspaces; a committed
+value already in that form fails the build); `"raw"` keeps the bare ciphertext. `profileFiles`
+(e.g. `["app.profile.ts"]`, next to the env file) are encrypted too: string values of
+sensitive-looking keys at any depth (password, pin, otp, secret, uname, token, apiKey, clientId…;
+not names of things such as `otpField`, `getOtp`, a bare `key`), and any string equal to a value
+encrypted from the env file. `pstack encryption --format=enc --profile-files=app.profile.ts`
+changes them.
+
+**`:migrate`.** When an Nx source encrypts its env files with its own `tools/**/encrypt-env.js`
+(`ENC(` marker and a `PUBLIC_ENV_KEYS` list), the workspace gets mode `all`, format `enc`, those
+public keys, `profileFiles` when `app.profile.ts` exists and the stamp fields the env files
+declare — unless the workspace's settings were already changed or other apps already build with
+them (the settings apply to every app); then they are kept and the report lists the suggestion. A copied `env-secret.ts` of the
+known shape (CryptoJS, `ENC(`, `envSecret` + `decryptEnvironment`, no other exports, key type
+`string`) becomes a wrapper of the runtime module with the same exports, so `env-init.ts` and every
+caller keep working; other shapes are kept and reported. In profile files, values equal to an
+encrypted env value are encrypted only as property values or array items (never import paths,
+type literals or comparisons), and sensitive keys whose values are not plain strings are named in a
+warning.
+
+#### AES-GCM env encryption (v0.28.0)
+
+`pstack encryption --cipher=aes-gcm` switches release builds to AES-256-GCM (Web Crypto). Every
+build makes a new 32-byte random key and takes the UTC build time; your `keySources` (at least one
+of `commit`, `salt`, `env`, `custom`; `--key-sources=commit,salt`) are mixed in with HKDF-SHA256.
+Values are written as `ENC2(...)` and bound to the name of the property that holds them (array
+items: the array's property name), so a value moved to another field does not decrypt.
+
+```bash
+pstack encryption --cipher=aes-gcm --key-sources=commit,salt
+pstack encryption --app=web --key-split=meta-bundle-asset
+pstack encryption --app=web --domains='uat=uat.example.com,example.in;prod=example.com'
+pstack encryption --app=web --domains=uat=           # removes the uat list
+pstack encryption --app=web --include-www=false --on-mismatch=warn
+```
+
+- The random key is split: one share in `<meta name="x-build">` (`metaName`), one in the bundle
+  (`keySplit: meta-bundle`, the default), and with `meta-bundle-asset` a third in
+  `assets/pstack-k.<hash>.bin`. The meta share and the asset go next to the served `index.html`
+  (`<outputPath>`, or `<outputPath>/browser` for the Angular application builder); an aes-gcm
+  build without an `index.html` there fails. `--app=<project>` sets `--key-split`, `--domains`,
+  `--include-www` and `--on-mismatch` on that app's release target.
+- `salt`: `tools/config/env-salt`, created on first use; commit it; `--rotate-salt` renews it.
+  `env`: `PSTACK_ENV_KEY` at build time. The `salt` and `env` values are written into the bundle,
+  like the commit: use a dedicated random value, never a real secret. `custom`:
+  `PSTACK_CUSTOM_KEY` at build time and `envReady(environment, { getKey })` in the app (e.g.
+  fetched from your server) — the only source that stays out of the shipped files.
+- Domain lock per app and configuration: `--domains=<conf>=<hosts>[;<conf>=<hosts>…]`
+  (`example.com` also allows `www.example.com` unless `--include-www=false`; `*.example.com` any
+  subdomain; an empty list removes the lock). `--on-mismatch=block` (default) leaves the values
+  encrypted on other hosts; `warn` decrypts with a console warning, for a rollout. `localhost`,
+  `127.0.0.1`, `[::1]` and `capacitor:` / `ionic:` origins are never locked. It deters re-hosting
+  a copied build; it is not protection.
+- The build fails before it touches any file when `PSTACK_ENV_KEY` / `PSTACK_CUSTOM_KEY` is
+  missing for a listed source, a host is not valid (`@`, `\`, `%`, a wildcard on a single
+  label or an IPv4 address, a path without a scheme) or `keySplit` is unknown. In
+  `mode: "listed"`, a listed key found outside `environment = { … }` or without a property name
+  fails the build too.
+- Switching rewrites `main.ts` to `await envReady(environment, { inPlace: true })` before
+  bootstrap (with `metaName` when it is not `x-build`) and lists code that reads env fields at
+  import time (those values are still encrypted then). `envSecret()` works after that (it throws on
+  a value still in `ENC2(...)`); `envSecretAsync()` decrypts on use. `envReadySync()` leaves
+  `ENC2(...)` values alone, so an `env-init.ts` that runs at import keeps working.
+- Objects outside `environment` (e.g. profiles): `await decryptTreeAsync(profile)` after
+  `envReady`. An `env-secret.ts` wrapper written by `:migrate` has `decryptEnvironmentAsync(obj?)`
+  (no argument: the environment); switching adds it to wrappers written before v0.28.0.
+- Web Crypto needs a secure context: serve the app over https (or localhost).
+- The key ships with the page (except `custom`), so this hides values; real secrets belong on a
+  server.
+- `pstack update` (migration `env-encryption-key-sources`) renames `keySource` to `keySources`.
+
+#### Importing an Ionic app (v0.11.0)
+
+`pstack migrate --source=../ionic-app` imports a standalone Ionic Angular app that uses Capacitor
+(`@ionic/angular` plus a `capacitor.config.*`) with the `ionic` adapter. Ionic apps in an Nx import
+(`ionic-app` projects) get the same treatment. The app ends up in the shape `pstack app --type=ionic`
+generates:
+
+- Native packages (Capacitor and Cordova plugins: `@capacitor/*`, names containing `capacitor`,
+  `cordova-*`, `@awesome-cordova-plugins/*`, `@ionic-native/*`, and any installed package that
+  declares a `capacitor` or `cordova` section) are listed in the app's own `package.json` at the
+  source's versions, so `cap sync` finds them. The ones the copied code imports stay in the root
+  `package.json` too, because the web build resolves them from there; the rest (the Capacitor CLI,
+  platform packages, plugins used only natively) are only in the app's `package.json`.
+- With several Ionic apps in one Nx import, each app gets the platform packages, the plugins it or
+  the shared code imports, and the plugins no copied code imports.
+- An Angular app with Capacitor but without `@ionic/angular` is handled the same way (no ionicons
+  asset).
+- `android/` and `ios/` are copied without build output (Gradle `build` and `release` folders,
+  Pods, DerivedData, the generated Cordova plugin projects, the web assets and config `cap sync`
+  copies in) or `local.properties`.
+- The build output moves from `www` to `dist/apps/<app>`, and `webDir` in the Capacitor config
+  points there. When `webDir` is not a plain string, the report says what to set.
+- The release target builds with `type: ionic`; `cap-sync`, `cap-open` and `cap-add` targets and
+  the `build:<app>:<env>:android|ios` / `open:<app>:android|ios` scripts are added. `@nxext/*` and
+  `@ionic/angular-toolkit` targets are dropped.
+- The report's Ionic section lists the package split, the `webDir` change, the platforms copied
+  and any Cordova plugins to check against Capacitor.
+
+```bash
+pstack migrate --source=../field-notes
+npm install
+npx nx run field-notes:release:prod
+npx nx run field-notes:cap-sync --platform=android
+```
+
+Ionic 6 and Capacitor majors other than 5 are accepted with a note. Cordova-only apps (`config.xml`
+or `ionic.config.json` without a Capacitor config) are refused, in Nx imports too (kind
+`ionic-cordova`): move them to Capacitor first. Capacitor apps on the Angular 17+ application
+builder are converted like other Angular 17+ apps (v0.23.0).
+
+#### Importing a multi-project Angular CLI workspace (v0.12.0)
+
+`pstack migrate --source=../ng-repo` imports the apps and libraries of an Angular CLI repo whose
+`angular.json` has several projects (the `angular-workspace` adapter). A repo with a single project
+still goes to the `angular-cli` (or `ionic`) adapter.
+
+```bash
+pstack migrate --source=../ng-repo --detect                  # projects and their kinds
+pstack migrate --source=../ng-repo                           # every supported project
+pstack migrate --source=../ng-repo --projects=portal         # portal and the libraries it imports
+pstack migrate --source=../ng-repo --projects=admin --no-deps
+pstack migrate --source=../ng-repo --prefix=legacy           # legacy-<name> projects and folders
+```
+
+- Apps go to `apps/<name>`, libraries to `libs/<name>`. An app at the repo root (the usual first
+  app) is copied without the `projects/` folder and the other projects' folders.
+- Library aliases that pointed at the build output (`"ui-kit": ["dist/ui-kit"]`) now point at the
+  library source (`libs/ui-kit/src/public-api.ts`, or `lib.entryFile` from `ng-package.json`), so apps
+  build without building the libraries first. Aliases into a project's source follow it to its new
+  folder; others are listed in the report. Imports in the copied code are rewritten (see Import
+  rewriting).
+- Libraries keep their ng-packagr build (`nx build <lib>`); `ng-package.json` `dest` becomes
+  `dist/libs/<name>`. ng-packagr and its build packages are added when a library builds.
+- Apps get the release target and npm scripts; apps with a Capacitor config get the Ionic treatment.
+- Angular 17+ application-builder apps are converted to Angular 15 builders (v0.23.0);
+  server-rendered apps (`angular-ssr`) and e2e-only projects are listed as not supported.
+- Before anything is written, folders, project names, aliases and the Angular major are checked.
+
+#### Importing an npm, Yarn or pnpm workspaces repo (v0.18.0, pnpm v0.20.0)
+
+`pstack migrate --source=../mono` imports a repo whose root `package.json` lists its packages under
+`workspaces` (npm, Yarn 1 or Yarn Berry, Plug'n'Play included), or whose `pnpm-workspace.yaml` lists
+them under `packages` (pnpm); this is the `npm-workspaces` adapter. Repos with `nx.json` or a root
+`angular.json` still go to the Nx and Angular adapters.
+
+```bash
+pstack migrate --source=../mono --detect                 # packages and their kinds
+pstack migrate --source=../mono                          # every supported package
+pstack migrate --source=../mono --projects=@acme/web     # web and the packages it imports
+pstack migrate --source=../mono --projects=web --no-deps
+pstack migrate --source=../mono --prefix=legacy          # legacy-<name> projects and folders
+```
+
+- Angular app packages (`angular.json` with one application) go to `apps/<name>` with the
+  `angular-cli` treatment; those with a Capacitor config get the Ionic treatment.
+- TypeScript library packages (an entry from `ng-package.json`, `source`, `types` → `src/…`,
+  `src/index.ts` or `index.ts`) go to `libs/<name>` with a lint target, and their **package name**
+  becomes the tsconfig alias (`"@acme/utils": ["libs/utils/src/index.ts"]`), so imports between
+  packages keep working unchanged.
+- Project names are the package names without scope (`@acme/web` → `web`); when two packages
+  would share one, both keep their scope (`acme-utils`, `other-utils`). `--projects` takes package
+  or project names.
+- Dependencies of the source root and the imported libraries are merged into the root
+  `package.json`; app packages merge their own (Angular versions come from the app packages).
+  Workspace packages (`workspace:*` or local versions) are left out; other local `file:`/`link:`
+  paths inside an imported package follow it to its new folder. Lockfiles, `.yarnrc.yml`, `.yarn/`,
+  `.pnp.*` and other root files are not copied; the workspace installs with npm. Outside git, the
+  root `.gitignore` applies to every package.
+- A dependency on a workspace package that cannot be imported (an ESLint or tsconfig preset, a
+  server) is listed in the report instead of stopping the import; imports of one still do.
+- Packages that are not Angular/Ionic apps or TypeScript libraries (React, Node servers, CLIs with
+  `bin`) are listed as not supported. Subpath imports (`@acme/utils/x`) and the source root tsconfig
+  options are listed in the report.
+- pnpm repos:
+  - `catalog:` and `catalog:<name>` versions are taken from `pnpm-workspace.yaml`; an entry the
+    catalogs do not define stops the import before anything is written.
+  - Flat `overrides` (`pnpm.overrides` in `package.json` and `overrides` in `pnpm-workspace.yaml`)
+    become npm `overrides`; entries with selectors (`a>b`, `pkg@<2`), removals (`-`) or
+    `workspace:`/`link:`/`file:` values are listed in the report. An override of a package the
+    import added as a direct dependency also sets that dependency's version (npm refuses an
+    override that differs from it); one the workspace already depends on at another version is
+    reported.
+  - `patchedDependencies`, `.pnpmfile.cjs`, `.npmrc` and the other pnpm settings are listed in the
+    report, not carried over. `pnpm-workspace.yaml`, `pnpm-lock.yaml` and `.pnpmfile.cjs` are not
+    copied.
+  - `pnpm-workspace.yaml` is read with a small reader: anchors, aliases, tags, block scalars
+    (`|`, `>`) and flow lists over several lines stop the import with the line number.
+  - The Nx, Angular CLI and Ionic imports resolve `catalog:` specs in the source `package.json` the
+    same way; an unknown entry, or a `catalog:` spec without pnpm catalogs (Yarn catalogs are not
+    read), stops the import.
+
+#### Import rewriting (v0.21.0)
+
+After the copy, `pstack migrate` rewrites imports in the copied code so it builds in its new place.
+The source is never changed, and `--rollback` removes the rewritten copies with the rest.
+
+- **Into another moved project:** a relative import that reaches into another project that moved
+  (`../../../utils/src`) becomes that library's alias when it points at the library entry
+  (`@acme/utils`), otherwise a corrected relative path. The report lists the corrected ones so you
+  can export what they need from the entry instead.
+- **Through the source `baseUrl`:** `import … from 'src/app/x'` becomes a relative path (or the
+  library alias), unless the workspace `baseUrl` still resolves it to the same file.
+- **`@nrwl/*`:** becomes `@nx/*` (`@nrwl/nx-plugin` becomes `@nx/plugin`; `@nrwl/nx-cloud`,
+  `@nrwl/tao` and `@nrwl/cli` are listed instead). The report names `@nx/*` packages the
+  workspace does not declare yet.
+- **SCSS:** relative `@use`, `@import` and `@forward` paths that reach into another moved project
+  are corrected; paths into the source's root `node_modules` point at the workspace's.
+- **Library subpaths** (npm, Yarn and pnpm imports): `@acme/utils/x` resolves through an added
+  `@acme/utils/*` alias to the package folder.
+
+Code files are `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs` and `.cjs` (not `.d.ts`); the
+rewritten forms are `import`/`export … from`, `import()`, side-effect imports, `require()` and
+`jest.mock()` / `vi.mock()`. Imports that point outside the imported projects, or at a file that
+was not copied, are left as they are and listed, unless they still resolve in the workspace.
+Imports inside one copied project are never changed. ESM-style `.js` specifiers of `.ts` files
+and `?raw`-style suffixes are understood. A bare specifier is only taken as a `baseUrl` import
+when a file (or a folder with an `index`) exists there; one that is also a dependency in the
+source `package.json` is listed instead.
+Nx imports keep their paths, so their relative imports are left alone. The report's `## Imports`
+section lists every change. `--no-rewrite-imports` (or `"rewriteImports": false` in a `--config`
+file) keeps the copies as they were and the report lists what needs a hand edit, as before.
+
+#### Writing your own adapter (v0.22.0)
+
+When no built-in adapter fits a source, write one. `pstack migrate --new-adapter=<id>` writes a
+working starter (`tools/migrate/<id>.adapter.ts`, which imports a static site with an `index.html`)
+with a Jest spec and `tools/migrate/jest.config.js`, and lists it in `nx.json`:
+
+```json
+{
+  "pstack": {
+    "migrateAdapters": ["./tools/migrate/legacy-site.adapter.ts", "@acme/pstack-adapter-x"]
+  }
+}
+```
+
+Entries are workspace-relative `.js`/`.ts` files or installed package names. A module exports one
+adapter or a list (`default`, `adapters`, `adapter`, or `module.exports`).
+
+- **TypeScript:** `.ts` files are transpiled with the workspace's `typescript` and its
+  `tsconfig.base.json` options (no ts-node needed). `paths` aliases are not resolved, and
+  `.mts`/`.cts` files are not supported.
+- **Adapter packages:** must be CommonJS, and should list nx-polystack as a peer dependency so
+  they use the workspace's copy.
+- **Trust:** listed adapters run as code on `pstack migrate`, `--detect` included. List only
+  adapters you trust, as with Nx plugins.
+
+```ts
+import {
+  copyIntoTree,
+  defineMigrationAdapter,
+  emptyReportData,
+  MIGRATE_API_VERSION,
+  recordCopy,
+  sourceExists,
+} from '@mouryaamit/nx-polystack/migrate';
+
+export default defineMigrationAdapter({
+  apiVersion: MIGRATE_API_VERSION,
+  id: 'legacy-site',
+  label: 'legacy static site',
+  detect: (dir) =>
+    sourceExists(dir, 'site.conf')
+      ? { confidence: 0.9, reasons: ['site.conf'] }
+      : { confidence: 0, reasons: ['no site.conf'] },
+  defaultName: () => undefined,
+  migrate(tree, ctx) {
+    const data = emptyReportData();
+    const copy = copyIntoTree(
+      tree,
+      ctx.sourceDir,
+      ctx.projectRoot,
+      {
+        anyDepth: ['.git'],
+        topLevel: [],
+      },
+      { maxFiles: ctx.maxFiles },
+    );
+    recordCopy(data, copy, '');
+    return data;
+  },
+});
+```
+
+- **The SDK** (`@mouryaamit/nx-polystack/migrate`) has the adapter and report types, and the
+  helpers the built-in adapters use:
+  - `copyIntoTree`, which applies skip rules, leaves out possible secrets, honours `.gitignore`
+    and enforces `--max-files`;
+  - `recordCopy` and `emptyReportData`;
+  - `mergeDependencies` and `classifyDependencySpec`;
+  - the source readers, `kebabName`, `upTo` and `setProjectTags`.
+- **Same treatment as the built-ins:** listed adapters take part in `--detect` (inside a workspace),
+  `--adapter=<id>`, `--config` and `--rollback`. Copies made with `copyIntoTree` + `recordCopy` get
+  import rewriting and the report's skipped-paths and secrets lists.
+- **Checks:**
+  - an adapter must declare `apiVersion: 1` (`MIGRATE_API_VERSION`);
+  - its id must be kebab-case and used by no built-in or other listed adapter;
+  - it needs `label`, `detect`, `defaultName` and `migrate` (plus `preflight` for
+    `kind: 'workspace'`).
+    Anything else stops the run, naming the `nx.json` entry.
+- **Ties and errors:** built-ins are tried first, so they win ties. An adapter whose `detect()`
+  throws scores 0, with the error as its reason.
+- **CLI version:** the global `pstack` delegates to the workspace's nx-polystack, which must be
+  v0.22.0 or later to load listed adapters.
+
+#### Angular 17+ sources (v0.23.0)
+
+`pstack migrate` imports Angular CLI apps built with the Angular 17+ application builder. The
+workspace builds with Angular 15, so the targets are converted to the Angular 15 builders. Covered:
+standalone Angular CLI apps, Ionic apps, multi-project Angular CLI workspaces, and Angular app
+packages of npm, Yarn and pnpm workspaces. Nx sources on the application builder are still listed as
+not supported.
+
+- **Build target:** `@angular-devkit/build-angular:application` and `@angular/build:application`
+  (and `:browser-esbuild` with `browser`/`server`/`ssr` options) become
+  `@angular-devkit/build-angular:browser`. `browser` becomes `main`, an `outputPath` object becomes
+  its `base`, an `index` object keeps `input` and `output`, and a `serviceWorker` path becomes
+  `serviceWorker: true` plus `ngswConfigPath`. Asset objects without `output` get `"/"`. Missing
+  `main`, `index`, `outputPath` and `tsConfig` are filled in, with `aot: true`; a configuration
+  with `optimization: false` gets `buildOptimizer: false`. Options the browser builder does not
+  have (`define`, `loader`, `externalDependencies`, `security`, …), and sub-options Angular 15
+  rejects (`stylePreprocessorOptions.sass`, `optimization.styles.removeSpecialComments`, …), are
+  dropped and listed. The output goes to `outputPath` itself, not to a `browser/` folder inside it.
+- **Other targets:** `@angular/build:dev-server`, `extract-i18n`, `karma` and `ng-packagr` become
+  the `@angular-devkit/build-angular` builders. Every dev-server, extract-i18n and karma target of
+  the project is checked against Angular 15: `buildTarget` becomes `browserTarget` (added when
+  missing, as Angular 17+ defaults it), asset objects get `output: "/"`, and options Angular 15
+  does not have (`prebundle`, `builderMode`, …) are dropped and listed. Other `@angular/build`
+  targets (`unit-test`) are kept and listed: they cannot run on Angular 15.
+- **i18n:** a `subPath` (Angular 17.2+) is listed; Angular 15 names locale folders after the
+  locale.
+- **tsconfig:** TypeScript 5-only compiler options are fixed for TypeScript 4.9:
+  `moduleResolution: "bundler"` becomes `"node"`, `module: "preserve"` becomes `"es2022"`, an
+  ES2023+ `target` or `lib` becomes ES2022, and `verbatimModuleSyntax`, `allowImportingTsExtensions`
+  and the like are removed.
+- **Server rendering:** an app whose build sets `server`, `ssr`, `prerender` or `appShell` (or that
+  has a server, ssr-dev-server, prerender or app-shell target) is refused before anything is
+  written; in a workspace it is listed as `angular-ssr`. Angular 15 Universal apps (browser builder
+  plus a server target) keep their builders and migrate as before.
+- **Code (report only):** the report's Angular section lists files that use Angular 16+ code
+  Angular 15 cannot compile: template control flow (`@if`, `@for`, `@switch`, `@defer`, `@let`),
+  signal APIs (`signal`, `computed`, `effect`, `input`, `output`, `model`, `viewChild`, …),
+  `@angular/core/rxjs-interop`, and newer providers (`withFetch`, `provideAnimationsAsync`,
+  `provideZoneChangeDetection`, …). Nothing is rewritten.
+- **Angular version:** a source on another Angular major still needs `--force-angular`; the
+  workspace's Angular packages are kept.
+- **CLI version:** the global `pstack` delegates to the workspace's nx-polystack, which must be
+  v0.23.0 or later.
+
+### `:infra` generator / `pstack infra` (v0.9.0)
+
+Same options as `pstack infra` (§3c): `with`, `ci`, `ciCache`, `flutter`, `upgradeSchedule`, `upgradeScope`,
+`force`, `skipFormat`.
+
+```bash
+npx nx g @mouryaamit/nx-polystack:infra --with=docs,ci --ci=jenkins
+```
+
+### `:app` generator schema
+
+```jsonc
+{
+  "name": "portal", // string — required
+  "type": "angular", // "angular" | "flutter" — required
+  "tags": ["platform:web"], // string[] — optional
+  "cspConnectSrc": "https://..." // string — optional, angular only
+}
+```
+
+---
+
+## 7. Nx plugin usage — executors
+
+Executors run as Nx targets after the plugin is installed as a dev dependency.
+
+### `:build` — Angular / Ionic build pipeline
+
+Replaces the legacy `tools/scripts/build.js` orchestrator. Runs the full pipeline:
+
+```
+encrypt-env → nx build → restore env
+  [→ leak check]          (non-DEV, leakCheck)
+  [→ source-map check]    (non-DEV, sourceMaps)
+  [→ strip / drop console] (non-DEV, stripComments / dropConsole)
+  [→ obfuscate]           (non-DEV, obfuscate: light)
+  [→ SRI hash swap]       (non-DEV, sri: true)
+  → strip-exif (PROD) → inject-meta
+  [→ inject-nonce]   (if secure: true)
+  [→ inject-sri]     (if sri: true; recomputes Angular's values)
+  → ngsw.json hashes (when present)
+```
+
+The `nx build` step runs the app's Angular `build` target (`buildTarget`). Generated Angular apps register this
+executor as the `release` target; the Angular builder lives on `build`.
+
+**`project.json` target example:**
+
+```jsonc
+{
+  "release": {
+    "executor": "@mouryaamit/nx-polystack:build",
+    "outputs": ["{options.outputPath}"],
+    "options": {
+      "type": "angular",
+      "outputPath": "dist/apps/portal",
+      "envProject": "portal",
+      "buildTarget": "portal:build"
+    },
+    "configurations": {
+      "dev": { "env": "DEV", "buildConfiguration": "development" },
+      "uat": {
+        "env": "UAT",
+        "buildConfiguration": "uat",
+        "leakCheck": "fail",
+        "sourceMaps": "fail",
+        "stripComments": true,
+        "dropConsole": ["log", "debug", "warn"]
+      },
+      "prod": {
+        "env": "PROD",
+        "buildConfiguration": "production",
+        "leakCheck": "fail",
+        "sourceMaps": "fail",
+        "stripComments": true,
+        "dropConsole": ["log", "debug", "warn"]
+      }
+    },
+    "defaultConfiguration": "dev"
+  }
+}
+```
+
+**Schema options:**
+
+| Option               | Type                         | Default           | Description                                                             |
+| -------------------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------- |
+| `type`               | `"angular" \| "ionic"`       | —                 | App type                                                                |
+| `outputPath`         | `string`                     | —                 | Build output directory                                                  |
+| `envProject`         | `string`                     | —                 | Folder name under `environments/`                                       |
+| `env`                | `string`                     | —                 | `DEV`, `UAT`, `PROD` or custom (e.g. `QA`); set via Nx `configurations` |
+| `buildTarget`        | `string`                     | `<project>:build` | Angular target to run, exactly `<project>:<target>`                     |
+| `buildConfiguration` | `string`                     | see below         | Configuration of `buildTarget`                                          |
+| `secure`             | `boolean`                    | `false`           | Inject CSP nonce SSI placeholders                                       |
+| `sri`                | `boolean`                    | `false`           | Integrity for every chunk (`--subresource-integrity`, hashes refreshed) |
+| `leakCheck`          | `fail\|warn\|off`            | `off`             | non-DEV: plaintext of encrypted env values in the output (below)        |
+| `sourceMaps`         | `fail\|warn\|off`            | `off`             | non-DEV: source maps in the output                                      |
+| `stripComments`      | `boolean`                    | `false`           | non-DEV: remove comments from built JS, CSS, `index.html`               |
+| `dropConsole`        | `string[]`                   | `[]`              | non-DEV: console methods removed from built JS                          |
+| `obfuscate`          | `off\|light\|medium\|strong` | `off`             | non-DEV: obfuscate main and lazy chunks (below)                         |
+| `obfuscateOptions`   | `object`                     | —                 | non-DEV: javascript-obfuscator overrides on top of the level            |
+| `harden`             | `boolean`                    | `false`           | Replaced: read as `stripComments` + `dropConsole` defaults; no script   |
+| `baseHref`           | `string`                     | —                 | Forwarded to Angular CLI `--base-href`                                  |
+
+**`buildTarget` / `buildConfiguration`.** The executor runs
+`npx nx run <buildTarget>:<buildConfiguration> --outputPath=<outputPath>`. When `buildConfiguration` is unset it
+falls back to `production` for `PROD`, `uat` for `UAT`, and `development` for anything else. `buildTarget` must be
+`<project>:<target>`; any other format is an error.
+
+**Self-reference error.** `buildTarget` must not point at the target that is running (for example `portal:release`
+with `buildTarget: portal:release`). The executor stops with
+`buildTarget "<x>" points at this target. Run "pstack update" (migration angular-release-target) or set buildTarget to the Angular build target.`
+This is what an app generated by v0.3.x hits, because its `build` target used this executor.
+
+**Custom environments (QA).** `env` is free-form. `env: "QA"` reads `environments/<envProject>/environment.qa.ts`
+(`DEV` reads `environment.ts`); EXIF stripping stays PROD-only. `pstack env --name=qa --app=portal` adds the `qa`
+configuration to `build`, `serve` and (when present) `release`, plus a `build:<app>:qa` npm script
+(see "Adding an environment later"):
+
+```bash
+pstack env --name=qa --app=portal
+npx nx run portal:release:qa
+```
+
+**Release hardening (v0.29.0).**
+
+The polystack `release` target (`@mouryaamit/nx-polystack:build`) can check and clean the build
+output of a UAT or PROD release. The options are set per release configuration; DEV builds skip
+every step.
+
+| Option          | Values                                                   | New apps (uat, prod)     | What it does                                                            |
+| --------------- | -------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `leakCheck`     | `fail`, `warn`, `off`                                    | `fail`                   | Plaintext of a value encrypted in this build found in the output        |
+| `sourceMaps`    | `fail`, `warn`, `off`                                    | `fail`                   | `.map` files or `sourceMappingURL` comments in the output               |
+| `stripComments` | boolean                                                  | `true`                   | Removes comments from the built JS, CSS and the served `index.html`     |
+| `dropConsole`   | list of `log`, `debug`, `warn`, `info`, `error`, `trace` | `["log","debug","warn"]` | Removes those console calls from the built JS (`info`/`error` are kept) |
+
+```jsonc
+"uat": {
+  "env": "UAT",
+  "buildConfiguration": "uat",
+  "leakCheck": "fail",
+  "sourceMaps": "fail",
+  "stripComments": true,
+  "dropConsole": ["log", "debug", "warn"]
+}
+```
+
+Absent options are off. `fail` lists every hit, then fails the build; `warn` lists them and
+continues. `LEAK_CHECK=warn` (or `fail`/`off`) overrides `leakCheck` for one run:
+
+```bash
+LEAK_CHECK=warn npx nx run web:release:uat
+```
+
+**Order after the Angular build:** env files restored → leak check → source-map check → strip
+comments and drop console (one terser pass per JS file) → EXIF strip (PROD) → build meta, aes-gcm
+key share, CSP nonce, SRI. SRI hashes therefore cover the final files.
+
+- **Leak check.** Looks for the plaintext of every value encrypted from the env and profile files
+  (4 characters or longer) in the js, mjs, cjs, html, css, json, txt and map files of the served
+  output (`3rdpartylicenses.txt` is skipped). Matches are whole tokens, raw or escaped (JSON,
+  `\uXXXX`, and HTML entities in html files). Messages name the file and the env key, never the
+  value. A value a profile file holds under a non-sensitive key (public by the app's own
+  configuration) is only a warning.
+- **Source maps.** The hint names the Angular option to change: `"sourceMap": false` in the build
+  configuration.
+- **Strip and drop console.** `assets/` is never touched. License comments (`/*! … */`) stay when
+  only `dropConsole` is set. SSI (`<!--#…-->`) and IE conditional comments stay in html; html is
+  left alone for SSR hydration (`index.csr.html` or `ngh` attributes). A file terser cannot parse
+  fails the build, naming the file. The Angular service worker's `ngsw.json` hashes are
+  recomputed at the end of the build (v0.30.0).
+- **terser.** The JS step loads terser from the workspace: keep `terser` in the root
+  `devDependencies` (new apps and the migration add `^5.16.0`). Without it the build fails with "stripComments/dropConsole need terser in the
+  workspace devDependencies".
+- **`harden`** is replaced. It used to run two scripts that workspaces do not have; now
+  `harden: true` is read as `stripComments: true` plus `dropConsole: ["log","debug","warn"]` when
+  those are unset, with a warning naming the new options. It runs no script.
+- **`pstack update`** (migration `release-hardening`, 0.29.0) turns the four options on for every
+  release configuration whose `env` is `UAT` or `PROD` (values already set, in the configuration
+  or the target options, are kept), removes `harden` (other non-DEV configurations it applied to
+  get `stripComments` and `dropConsole` instead) and adds terser. Set `leakCheck`/`sourceMaps` to
+  `"warn"` to report only.
+
+**Obfuscation and integrity (v0.30.0).** Two more release options, also per configuration and
+skipped for DEV:
+
+| Option             | Values                             | Default | What it does                                                                              |
+| ------------------ | ---------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `obfuscate`        | `off`, `light`, `medium`, `strong` | `off`   | Obfuscates main and the lazy chunks (runtime, polyfills, vendor, scripts, styles skipped) |
+| `obfuscateOptions` | object                             | —       | javascript-obfuscator options on top of the level (CSP-safe subset)                       |
+| `sri`              | boolean                            | `false` | Integrity for every chunk; with aes-gcm the app decrypts nothing without it               |
+
+```bash
+pstack hardening --app=web                                   # show the settings
+pstack hardening --app=web --configuration=uat --obfuscate=light --sri
+pstack hardening --app=web --sri --drop-console=log,debug,warn  # every non-DEV configuration
+```
+
+- **Order:** checks → strip / drop console → obfuscate → SRI hash swap → EXIF, meta, key share,
+  CSP nonce → SRI in index.html → `ngsw.json` hashes.
+- **`obfuscate`** uses `javascript-obfuscator` from the workspace (`pstack hardening` adds
+  `^4.2.2`; run `npm install`). No migration turns it on. Levels, measured on a 2.8 MB Angular
+  chunk (gzip growth):
+
+  | Level    | Profile                                                                                                    | Gzip                  |
+  | -------- | ---------------------------------------------------------------------------------------------------------- | --------------------- |
+  | `light`  | short (mangled) names, half the strings in a rotated, shuffled array, no wrappers                          | ≈ +20%                |
+  | `medium` | hexadecimal names, three quarters of the strings, string-array wrappers                                    | ≈ +67%                |
+  | `strong` | `medium`, plus rc4 string encoding and control-flow flattening (0.1) on the chunk holding the decrypt code | ≈ +210% on that chunk |
+
+  Every level is CSP-safe (`target: browser-no-eval`): no self-defending or debug protection,
+  globals and properties are not renamed, and each file gets its own identifier prefix and a
+  seed from its content. Main often holds the decrypt code and, in production builds without a
+  vendor chunk, the Angular framework: measure start-up time. (v0.31.0: `light` was the
+  `strong` profile in v0.30.x.)
+
+- **`obfuscateOptions`** tunes the level, e.g. `{ "stringArrayThreshold": 0.3 }` or
+  `{ "identifierNamesGenerator": "mangled" }`. Allowed keys: `stringArray`,
+  `stringArrayThreshold`, `stringArrayRotate`, `stringArrayShuffle`, `stringArrayEncoding`,
+  `stringArrayIndexShift`, `stringArrayWrappersCount`, `stringArrayWrappersType`,
+  `stringArrayWrappersChainedCalls`, `identifierNamesGenerator`, `controlFlowFlattening`,
+  `controlFlowFlatteningThreshold`, `deadCodeInjection`, `deadCodeInjectionThreshold`,
+  `numbersToExpressions`, `simplify`, `splitStrings`, `splitStringsChunkLength`,
+  `transformObjectKeys`, `unicodeEscapeSequence`, `reservedNames`, `reservedStrings`. Anything
+  else (eval-based protection, domain lock, renaming globals or properties, the target) fails the
+  build. `pstack hardening --obfuscate-options='{"stringArrayThreshold":0.3}'` sets it
+  (`none` clears it).
+- **`sri: true`** passes `--subresource-integrity` to the Angular build, so the webpack runtime
+  checks every lazy chunk and index.html carries `integrity` on its scripts and styles. The
+  hashes Angular wrote are swapped for the hashes of the stripped and obfuscated files, and the
+  index.html values are recomputed, so the browser refuses any file changed after the build. With
+  cipher aes-gcm the build also sets `ri` in `__pstack`: `envReady` rejects with "integrity
+  required" and decrypts nothing while a `<script src>` on the page has no `integrity`
+  attribute. cryptojs builds get the browser check only. The application builder (esbuild) loads
+  lazy chunks with `import()`, which carries no hash: the build warns that they are not covered.
+- **Integrity set in `angular.json`.** If the Angular build already wrote integrity
+  (`subresourceIntegrity: true`) while pstack `sri` is off, the hashes are still swapped and
+  refreshed after strip and obfuscate. After the swap, every hash in the webpack runtime must match
+  an output file, else the build fails. A `deployUrl` is not supported with `sri`.
+- **Limits of the runtime check.** It covers same-origin `<script src>` (the files the build
+  serves); third-party scripts such as a tag manager or chat widget are left to your CSP allowlist,
+  and the build lists their hosts. It checks that the attribute is present (the browser checks the
+  value) and does not cover inline scripts. (v0.30.1: v0.30.0 also required integrity on
+  third-party scripts, which blocked decryption on pages that load them.)
+- **Service worker.** When the output has `ngsw.json`, its `hashTable` is recomputed after every
+  rewrite, so the service worker accepts the final files. With `secure: true` the server rewrites
+  `index.html` (the SSI nonce), so that one entry can never match.
+
+**Release per environment (v0.32.0).** `pstack build` builds every app for one environment and
+prints a summary:
+
+```bash
+pstack build --env=uat --all --dry-run                  # the plan only
+pstack build --env=uat --all
+pstack build --env=prod --projects=portal,admin --parallel=2 --continue --report=dist/build.json
+```
+
+- **What it builds:** the release target (`@mouryaamit/nx-polystack:build`) of Angular and Ionic
+  apps, and `build-web` of Flutter apps (`--flutter-platforms=web,android,ios` adds
+  `build-android` / `build-ios`). The configuration is the one named after the env, else the one
+  whose `env` option matches. Apps without one are listed, not failed.
+- **How:** `npx nx run <app>:<target>:<configuration>`, one at a time with the build output shown;
+  `--parallel=N` (up to 8) runs N at once with each line prefixed by the app name. The first
+  failure stops the run (the rest are listed as skipped) unless `--continue` is given. The exit
+  code is 1 when a build failed.
+- **Summary:** status, time and output folder size per build, and the total time;
+  `--report=<file>` writes it as JSON too. The size is of the whole output folder, so
+  files left from an earlier build count too; builds of one app (Flutter platforms) never run
+  side by side.
+
+**Base href per configuration.** `pstack app --base-href=/portal/` writes `baseHref` on the `uat`
+and `prod` configurations of the release target (Flutter: `build-web`).
+`pstack release --app=portal` shows them; `--base-href=/portal/` sets every non-DEV
+configuration (or `--configuration=<name>` only), `--base-href=none` removes it.
+
+**CSP and server config (v0.33.0).** Each Angular/Ionic app's `csp-allowlist.json` lists the
+extra sources its pages need; `pstack csp` writes `src/.htaccess` (Apache) and
+`server/nginx.conf` (Nginx) from it:
+
+```bash
+pstack csp --app=portal                                    # show the policy, write missing files
+pstack csp --app=portal --add=script-src:https://www.googletagmanager.com,connect-src:https://api.example.com
+pstack csp --app=portal --remove=connect-src:https://old.example.com
+pstack csp --app=portal --force                            # also replace hand-written files
+```
+
+- **Allowlist keys:** `script-src`, `style-src`, `img-src`, `font-src`, `connect-src`,
+  `frame-src`, `media-src`, `worker-src`, `manifest-src`, `form-action`, `frame-ancestors`, plus
+  `permissions-policy` (a string). Sources are hosts (`https://api.example.com`,
+  `https://*.example.com`, `wss://…`, with optional port and path), schemes (`https:`, `wss:`,
+  `data:`, `blob:`), `'self'`, or `'wasm-unsafe-eval'` in `script-src`. Quoted keywords such as `'unsafe-inline'`/`'unsafe-eval'`, `*`,
+  and `data:`/`blob:` in `script-src` are refused.
+- **Policy:** `script-src 'self' 'nonce-…'` and `style-src 'self' 'nonce-…'` plus the allowlist,
+  `style-src-attr 'unsafe-inline'` (Angular `[style]` bindings), `img-src`/`font-src` with
+  `data:`, `object-src 'none'`, `base-uri 'self'`, `form-action 'self'`,
+  `frame-ancestors 'none'` (or the listed ones), `upgrade-insecure-requests`, plus
+  X-Frame-Options, X-Content-Type-Options, Referrer-Policy, HSTS and Permissions-Policy.
+- **Nonce per request:** the release build with `secure: true` writes
+  `<!--#echo var="CSP_NONCE" -->` into the nonce attributes and `<meta property="csp-nonce">`
+  (placeholder nonces such as `random-csp-nonce` already in the page are replaced too; v0.32 and
+  earlier wrote `UNIQUE_ID`). Apache fills it by SSI from `UNIQUE_ID` with `@` replaced (a nonce
+  may not hold `@`); Nginx replaces it with `$request_id` through `sub_filter`. The CSP header carries
+  the same value; `index.html` is sent with `Cache-Control: no-store`. `runtime/csp-nonce` gives
+  the nonce to elements Angular adds later.
+- **Generated vs hand-written:** generated files start with
+  `# Generated by pstack csp from csp-allowlist.json`; `pstack csp` rewrites those and missing
+  ones, and keeps any other file unless `--force`.
+- **Critical CSS:** Angular's inlined critical CSS loads the stylesheet with an `onload`
+  handler, which the strict `script-src` blocks; new apps set
+  `optimization.styles.inlineCritical: false`, and `pstack csp` warns when a build still inlines
+  it.
+- **Nginx and a base href:** the generated server block serves the app at `/`; adjust `root` and
+  `location` when it lives under a base href.
+- **Apache requirements:** mod_rewrite, mod_headers, mod_include, mod_unique_id and mod_setenvif,
+  and `AllowOverride FileInfo Options=IncludesNOEXEC` (or `All`) for the folder — the default
+  `AllowOverride None` ignores the file, and without `Options` rights Apache answers 500.
+- **Nonce strength:** Nginx's `$request_id` is 16 random bytes per request. Apache's `UNIQUE_ID`
+  is unique but not random per request (a per-process random part plus time and a counter), so
+  someone who sees one response can guess later nonces from the same process; prefer Nginx, or a
+  nonce from your app server, where that matters. A server that sets its own random `UNIQUE_ID` (for
+  example through mod_lua, with mod_unique_id off) is used as is. A missing module fails closed: the header
+  carries `'nonce-(null)'` and the page `(none)`, so scripts are blocked.
+- **Nginx notes:** needs nginx 1.11+ (`$request_id`) and `include mime.types` in the `http` block;
+  `sub_filter` is skipped when a precompressed `index.html.gz`/`.br` is served (gzip_static).
+- **Tag managers:** an inline GTM snippet needs the page nonce (the release build adds it to inline
+  scripts); the scripts GTM loads later must be listed in `script-src` and may need more.
+- **Upgrading from v0.32 or earlier:** the build placeholder changed from `UNIQUE_ID` to
+  `CSP_NONCE`, and earlier generated `.htaccess`/`nginx.conf` files carry no marker, so
+  `pstack csp` treats them as hand-written. Under an Apache `Alias` (URL path differs from the folder),
+  add `RewriteBase /<base href>/`. Run `pstack csp --app=<app> --force` once (after
+  copying any hand-made changes into `csp-allowlist.json`).
+
+**Importing an existing policy (v0.38.0).** `--import` merges a CSP an app already has into its
+`csp-allowlist.json`, then renders the server files as usual:
+
+```bash
+pstack csp --app=portal --import=apps/portal/src/.htaccess --dry-run    # see what would change
+pstack csp --app=portal --import=apps/portal/src/.htaccess --force      # merge, replace the old file
+pstack csp --app=portal --import=policy.json                            # { "script-src": [...], ... }
+pstack csp --app=portal --import="connect-src https://api.example.com; img-src https://cdn.example.com"
+```
+
+- Sources: a `Content-Security-Policy` header value (inline or in a file), an Apache `.htaccess`
+  (`Header … Content-Security-Policy "…"`) or Nginx config (`add_header …`; Report-Only headers are
+  not read), or JSON — directive → sources, also under `directives` or `suggestedPolicy.directives`.
+  A file path is read relative to the folder you run the command in.
+- The import is merged into what is there; existing entries are never removed. Imported sources
+  an entry already allows are not added: duplicates (any case) and paths under a listed host
+  (`https://cdn.example.com/x.js` when `https://cdn.example.com` is listed; `*.example.com` covers
+  its subdomains; a host without a scheme covers `https://` only). A config with several CSP
+  headers is merged with a note (a browser enforces each of them).
+- The report lists what was added (`+`), already allowed (`=`), refused by the strict policy and
+  not taken by the generated policy, each with the reason. Refused / not taken:
+  `'unsafe-inline'`, `'unsafe-eval'`, bare schemes in script/style-src, `http://` hosts, and
+  directives the generated policy does not take (`script-src-elem`, `style-src-elem` — their hosts
+  are listed so you can add them with `--add` — `object-src`, `default-src`, …). Nonces and hashes
+  are skipped: the server adds the nonce per request.
+
+**Adding an environment later (v0.34.0).** New apps always start with `dev`, `uat` and `prod`.
+`pstack env` adds another environment to some apps, or all of them, copied from an existing
+one:
+
+```bash
+pstack env --name=qa --app=portal --api-url=https://qa.example.com/api
+pstack env --name=sit --app=portal,admin --from=prod --production=false --base-href=/sit/
+pstack env --name=perf --all
+```
+
+For each app it adds:
+
+- **Angular/Ionic:** `environments/<app>/environment.<env>.ts` copied from the `--from`
+  environment's file (default `uat`, or `prod` for apps without `uat`). `envName` is set to the
+  new env, api urls are replaced with `--api-url`, and `production` is set when
+  `--production` is given. For apps with a release target, secret fields become
+  `${<APP>_<ENV>_<KEY>}` placeholders (for example `${PORTAL_QA_PASSWORD}`), which the release
+  build fills from CI variables or `.env.local` (a missing one fails the build): in `listed`
+  mode the listed keys, in `all` mode the non-public fields that look sensitive (password, token,
+  key, secret…) or already hold a placeholder. URLs and plain settings are copied. Apps without a
+  release target get the values copied (nothing would fill a placeholder), and nested listed keys
+  are copied with a note. The file goes where the release build reads it:
+  `environments/<envProject>/environment.<env>.ts`.
+- **Angular `build` and `serve` configurations:** the source build configuration (budgets,
+  optimisation, other file replacements) with the env file swapped.
+- **Release configuration:** the source one (hardening, obfuscation, SRI, base href) with `env`
+  and `buildConfiguration` set. `--base-href` overrides the base href. The domain lock is not
+  copied: pass `--domains`, or set it later with `pstack encryption --domains`.
+- **Flutter:** `env/<env>.json` copied (env name and api url updated; values are copied as
+  they are — dart-defines have no placeholders), and `build-web`,
+  `build-android` and `build-ios` configurations copied (`--base-href` on `build-web`).
+- **npm scripts** (`serve:`/`build:<app>:<env>`, Ionic `:android`/`:ios`, Flutter
+  `:web`/`:apk`/`:ios`), and the AI-assistant block is refreshed.
+
+`--app` or `--all` is required. Everything is checked first; a new env that already exists, or a
+missing `--from` configuration, stops the command with every problem listed and nothing
+written.
+
+**App generator options (v0.35.0).** `pstack app` gives every new app a dev-server port, a `clean`
+target and, for Angular/Ionic, the shared assets and styles folders:
+
+```bash
+pstack app --type=angular --name=admin                      # next free port from 4200
+pstack app --type=angular --name=admin --port=4300          # explicit port (1024-65535)
+pstack app --type=angular --name=admin --env-layout=per-env # environment.dev|uat|prod.ts
+pstack shared --all                                         # wire the shared folders into existing apps
+nx run admin:clean                                          # or npm run clean:admin
+```
+
+- **Port.** The lowest port from 4200 that no app of the workspace serves on (a serve target
+  without a port counts as 4200), set as `serve.options.port` (Flutter: the `flutter-build`
+  executor's new `port` option, used for `--web-port`). A `--port` another app uses is refused.
+- **Shared assets and styles.** `libs/shared/assets` and `libs/shared/styles` are created on first
+  use (projects `shared-assets` and `shared-styles`; a workspace that already has `libs/assets` /
+  `libs/styles` uses those, and a `libs/shared` that is itself a library gets `libs/assets` and
+  `libs/styles` instead). New Angular/Ionic apps copy the assets to `assets/shared/`, can
+  `@use 'theme';` (the Sass include path holds the styles folder) and list both projects in
+  `implicitDependencies`. `pstack shared --app=<a,b>|--all` does the same for existing apps.
+- **`--env-layout=per-env`** (Angular/Ionic): `environments/<app>/environment.{dev,uat,prod}.ts`
+  and a shared `environments/environment.ts` (created when missing) that the app imports; the
+  development, uat and production build configurations replace it with the app's file. The release
+  build reads `environment.dev.ts` for DEV. The default layout is unchanged.
+- **`clean`** (`@mouryaamit/nx-polystack:clean`) removes `dist/<app root>` and
+  `coverage/<app root>`; Flutter apps also run `flutter clean` (a warning when Flutter is not
+  installed). Only paths below `dist/`, `coverage/` or `tmp/`, or the project's own output
+  folders (`www`, `build`, … under its root), are removed; anything else is refused.
+- **`pstack update`** (migration `app-clean-and-port`) adds `clean` to apps without one (Angular
+  outputs from the build `outputPath`) and, when several apps serve without a port (all on 4200),
+  keeps 4200 for the first by name and gives the others the next free ports. It does not wire the
+  shared folders.
+
+**Quality checks (v0.36.0).** Type errors, broken imports and unused imports are caught before
+review:
+
+```bash
+nx run portal:typecheck                      # tsc --noEmit -p apps/portal/tsconfig.app.json
+nx affected -t lint typecheck test build     # what CI runs
+pstack infra --with=none --lint-staged=block # make ESLint block commits again (warn: report only)
+```
+
+- **`typecheck`** on every app and lib with a `tsconfig.app.json` / `tsconfig.lib.json`
+  (`nx:run-commands`, `tsc --noEmit -p …`), cached through nx.json `targetDefaults`. New
+  Angular/Ionic apps and TypeScript libs get it; `pstack infra --with=quality` adds it to every
+  project without one (for example after `pstack migrate`). CI runs it in the affected step.
+- **ESLint**: `import/no-unresolved` (resolved through `tsconfig.base.json` paths) and
+  `unused-imports/no-unused-imports`, both warnings, in an override of the root `.eslintrc.json`;
+  packages `eslint-plugin-import`, `eslint-import-resolver-typescript` and
+  `eslint-plugin-unused-imports` (the version that matches the workspace's `@typescript-eslint`).
+- **lint-staged**: new workspaces run ESLint on commit through
+  `tools/scripts/lint-staged-eslint.js` (the workspace ESLint, no npx), which fixes what it can and
+  reports the rest without
+  blocking the commit (Prettier still formats). `pstack infra --lint-staged=block|warn` switches.
+- **`pstack update`** (migration `quality-checks`) adds the typecheck targets, the nx.json default,
+  the CI step (when the workflow has the standard `nx affected -t lint test build` line) and the
+  ESLint warnings with their packages. It does not change the commit hook. Run
+  `npx nx run-many -t typecheck` once afterwards: libraries are now type-checked as a whole.
+
+**Session timeout and PII masking libs (v0.37.0).** Two Angular 15 starter libs, Angular and RxJS
+only (no third-party packages), buildable by default (`--variant=internal|buildable|publishable`):
+
+```bash
+pstack lib --type=session --name=session    # @<scope>/shared-session
+pstack lib --type=pii --name=pii-mask       # @<scope>/shared-pii-mask
+```
+
+- **`session`**: `SessionTimeoutService` with `start(loginTime?)`, `stop()`, `extend()`, `state$`
+  (`stopped` / `active` / `warning` / `timedOut`), `warning$` (seconds left), `timeout$` (`idle` or
+  `absolute`, once per session) and `stoppedElsewhere$` (another tab signed out);
+  `SessionTimeoutModule.forRoot({ idleMs, warningMs, absoluteMs })` in the root module; a non-modal
+  `<prefix>-session-warning` component (countdown, focus on its first button, screen-reader
+  announcements at thresholds, `[texts]` for other languages). Tabs share activity, timeouts and
+  logouts (BroadcastChannel, localStorage as fallback; the key includes the app's base path, so two
+  apps on one domain stay apart); a tab waking from sleep checks the others' last activity before
+  timing out. Bad start times are refused and unreadable times end the session (fail closed).
+  Timers run outside Angular's zone; nothing runs during server-side rendering. It never signs
+  anyone out or touches tokens: the app does that on `timeout$` and `stoppedElsewhere$`.
+- **`pii`**: `maskPii(value, format)`, the `piiMask` pipe and the `[<prefix>PiiMask]` directive
+  (writes text, never HTML). Formats: `pan`, `aadhaar`, `mobile`, `email`, `account`, `card`, `ifsc`
+  (shown as it is); custom formats and the mask character through `PiiMaskModule.forRoot(…)`. A
+  value that does not match its format is masked completely, in any script (Devanagari digits,
+  regional-script names); at most half of a value is ever shown. Display only: stored and sent
+  values are unchanged.
+- The timing (`session-clock.ts`) and masking (`pii-mask.ts`) logic has no Angular imports, so it
+  can be unit-tested directly.
+
+**Running:**
+
+```bash
+npx nx run portal:release:dev
+npx nx run portal:release:uat
+npx nx run portal:release:prod
+```
+
+---
+
+### `:capacitor` — Capacitor commands for Ionic apps
+
+Runs `npx cap <command> <platform>` inside the app folder. If the app's `node_modules` is missing it runs
+`npm install` there first. `sync` and `copy` check that the web build exists (`dist/apps/<project>`, or `webDir`).
+
+| Option     | Description                                                                         |
+| ---------- | ----------------------------------------------------------------------------------- |
+| `command`  | `sync`, `open`, `add` or `copy` (set per target: `cap-sync`, `cap-open`, `cap-add`) |
+| `platform` | `android` or `ios` — pass as `--platform=android`                                   |
+| `webDir`   | Web build output relative to the workspace root (default `dist/apps/<project>`)     |
+
+```bash
+npx nx run field-ops:cap-sync --platform=android
+npx nx run field-ops:cap-open --platform=ios
+```
+
+---
+
+### `:flutter-build` — Flutter build wrapper
+
+Wraps `flutter build` with `--dart-define-from-file` environment wiring and optional obfuscation.
+
+```bash
+npx nx run mobile:flutter-build:web
+npx nx run mobile:flutter-build:apk
+npx nx run mobile:flutter-build:ios
+```
+
+---
+
+### `:flutter-export` — FlutterFlow export
+
+Exports a FlutterFlow project into the local `apps/<name>/` directory using the FlutterFlow CLI.
+
+```bash
+npx nx run mobile:flutter-export
+```
+
+---
+
+## 8. Helper modules
+
+Import helpers directly from the package in your own scripts or tools:
+
+```typescript
+import {
+  resolveCiContext,
+  encryptEnvFile,
+  injectBuildMeta,
+  injectCspNonce,
+  injectSri,
+  stripExif,
+  addNpmScripts,
+  addTsPath,
+  generateAngularEnvFiles,
+  mergeNxTargets,
+  backupAndOverwrite,
+} from '@mouryaamit/nx-polystack';
+```
+
+| Helper                                   | Description                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------ |
+| `resolveCiContext()`                     | Resolves branch, commit SHA, and build number from CI env vars or git    |
+| `encryptEnvFile(file, keys)`             | AES-encrypts named keys in an environment TypeScript file                |
+| `injectBuildMeta(distDir, ctx)`          | Injects `<meta name="x-build">` into `dist/index.html`                   |
+| `injectCspNonce(distDir)`                | Replaces nonce placeholders with SSI variables for Apache/Nginx          |
+| `injectSri(distDir, allowlist)`          | Adds `integrity=` + `crossorigin=` to local `<script>` and `<link>` tags |
+| `stripExif(dir)`                         | Recursively strips EXIF/IPTC/XMP metadata from images                    |
+| `addNpmScripts(tree, scripts)`           | Adds entries to root `package.json` scripts (Nx Tree mutator)            |
+| `addTsPath(tree, alias, path)`           | Adds a path alias to `tsconfig.base.json` (Nx Tree mutator)              |
+| `generateAngularEnvFiles(tree, name)`    | Creates `environments/<name>/environment*.ts` stubs                      |
+| `mergeNxTargets(tree, project, targets)` | Merges targets into a project's `project.json`                           |
+| `backupAndOverwrite(src, dest)`          | Creates a `.bak` copy of a file then overwrites it                       |
+
+---
+
+## 9. Release packaging
+
+Releases are published to npm from this repository's `Publish` workflow when a `vX.Y.Z` tag is pushed.
+
+---
+
+## 10. Troubleshooting
+
+### `pstack: command not found` after global install
+
+Check that the npm global bin directory is in your `PATH`:
+
+```bash
+npm config get prefix    # e.g. /usr/local
+# Ensure /usr/local/bin is in PATH
+```
+
+### `Error: no nx.json found in the current directory`
+
+The `pstack app` command must be run from the root of an existing Nx workspace. Run `pstack preset` first
+if you are starting from scratch.
+
+### Generator changes nothing (`Nothing to generate.`)
+
+The target project path may already exist. Pass `--force` via Nx:
+
+```bash
+npx nx g @mouryaamit/nx-polystack:app --type=angular --name=portal --force
+```
+
+The `pstack` CLI does not support `--force` directly — use the Nx generator form for this.
+
+### `Error: env is required` from the `:build` executor
+
+The `:build` executor expects `env` to be set via an Nx configuration, not as a top-level option.
+Ensure your `project.json` has `configurations` with `"env": "DEV|UAT|PROD"`:
+
+```jsonc
+"configurations": {
+  "dev": { "env": "DEV" }
+}
+```
+
+Then run with: `npx nx run <project>:build:dev`
+
+### Shebang missing on `bin/cli.js`
+
+Re-run `npm run build`. The build script automatically adds `#!/usr/bin/env node`
+if it was stripped by the TypeScript compiler.
+
+### Version mismatch between `pstack --version` and installed package
+
+`pstack --version` reads the `version` field from the bundled `package.json` at runtime. If the
+version shown differs from what was installed, you may have a stale global install:
+
+```bash
+npm i -g @mouryaamit/nx-polystack@latest
+```
+
+Inside a workspace whose local plugin version differs from the global CLI, `pstack -v` prints the global
+version followed by `workspace plugin: X`.
+
+---
+
+_See also:_  
+_`README.md` — quick-start and plugin architecture_