devendra-skill-package 1.0.2

package/.github/skills/encryption-decryption-utility/SKILL.md

@@ -0,0 +1,645 @@
+---
+name: encryption-decryption-utility
+description: Generate and install transparent encryption/decryption scaffolding for any supported platform (Angular, Web, Node.js, Android, iOS, Flutter, React, React Native). Produces a platform-appropriate config file, service, interceptor/middleware, and module wiring patch. Supports seven cryptographic approaches: RSA-OAEP+AES-256-GCM (Web Crypto), RSA+AES-256-CBC (jsencrypt/crypto-js), AES-256-CBC shared key (crypto-js), React Native JS production mode (AES-256-GCM + RSA-OAEP via react-native-quick-crypto with per-request ephemeral keys, response decryption, keychain storage), React Native Native mode (OS-level crypto via javax.crypto.Cipher on Android + CryptoKit on iOS), EC (ECDH+AES-256-GCM) mode for React Native (both JS and Native layers, per-request and session-init variants), and React JS web production mode (AES-256-GCM + RSA-OAEP or ECDH-Session via built-in Web Crypto API, per-request ephemeral keys, response decryption, browser-safe storage — no extra crypto packages). Includes HMAC signing support and per-URL exclusion lists. All scripts are zero-dependency Node.js (built-ins only).
+---
+
+# Purpose
+
+Generate a complete, platform-appropriate encryption/decryption scaffold for a target project.  
+The skill detects existing encryption code, prompts for configuration, writes all required files,
+patches module wiring, and validates via a build run.  
+The generated code is deterministic: the same config always produces the same files.
+
+> **CRITICAL — Common Misinterpretation to Avoid**
+>
+> The scan detection step (Step 2) is a **shell-script gate**, not a feature to implement.
+> Do NOT create source files, types, protocols, use cases, or architecture layers for scanning or conflict resolution.
+> Do NOT produce `ScanEncryptionUseCase`, `EncryptionLocation`, `ConflictResolutionChoice`, or any equivalent.
+> Those are implementation details of the install script, not app code.
+> The only source files this skill writes are: the config, the shared service, and the interceptor/middleware.
+
+## Skill Assets
+
+Use these bundled files during execution:
+
+- `template.md` — execution template (layer selection gate, config snapshot, project analysis)
+- `references/architecture.md` — Mode A/B architecture, request contract, security constraints
+- `references/backend-alignment.md` — backend contract spec (approaches 4 and 5)
+- `references/dependency-guidance.md` — library selection, version compatibility, install rules
+- `references/security-checklist.md` — security gates to verify before delivery
+- `references/error-handling-playbook.md` — failure paths for all platforms
+- `references/ec-implementation.md` — ECDH+AES-256-GCM implementation reference: per-request and session-init EC, Hermes Buffer compatibility helpers, HKDF-SHA256, EC key service, EC wiring into api.ts
+- `references/native-rsa-implementation.md` — RSA + Native layer reference: full Kotlin/Swift NativeCryptoModule with detailed inline comments, registration steps, JS bridge
+- `Instructions.md` — how to copy and run this skill in a new project; execution breakdown, dependency install order, TypeScript verification, backend alignment
+- `templates/config-questionnaire.md` — full numbered questionnaire with defaults
+- `templates/implementation-plan.md` — fill out before writing any files
+- `templates/delivery-checklist.md` — confirm all items before final delivery
+
+Recommended order:
+1. Use `templates/config-questionnaire.md` to collect and validate all inputs.
+2. Use `templates/implementation-plan.md` to map implementation to existing project structure.
+3. Use `references/dependency-guidance.md` before any package install.
+4. Use `references/architecture.md` during module and interceptor integration.
+5. Use `references/backend-alignment.md` to share the backend contract with the server team.
+6. Use `references/error-handling-playbook.md` for secure failure paths.
+7. Use `references/security-checklist.md` and `templates/delivery-checklist.md` before finalizing.
+
+## Scope
+
+- Analyze existing project structure first and follow established conventions.
+- Integrate encryption/decryption into the existing API layer with minimal disruption.
+- Use secure storage for tokens and sensitive user data.
+- Keep ephemeral cryptographic material in memory only.
+- Do not create unnecessary folders or duplicate existing modules.
+
+## Mandatory Rule: Ask Questions First
+
+Before writing any code or files, collect all required configuration answers using `templates/config-questionnaire.md` and wait for responses.
+Do not generate files until every required answer is received and validated.
+Apply documented defaults automatically for unanswered non-critical fields.
+
+---
+
+# One-Run Execution Contract
+
+This skill must complete in a single end-to-end run whenever the required inputs are provided.
+
+- Ask questions **one at a time** — each question is a single prompt; wait for the answer before asking the next.
+- Do not bundle multiple questions into a single prompt.
+- Do not split implementation into staged "continue" steps.
+- If a field has a documented default, apply the default and continue without asking.
+- Ask follow-up questions only when a security-critical value is missing and has no safe default.
+- After all answers are available, complete all implementation, integration wiring, env updates, and validation in the same run.
+- Return one consolidated setup report at the end.
+
+**Minimum completion scope (React Native JS mode — approach 4):**
+1. Crypto modules (encrypt/decrypt via react-native-quick-crypto)
+2. RSA key retrieval/cache/retry
+3. API interceptor integration (request + response)
+4. In-memory request key mapping + guaranteed cleanup
+5. Secure token/data storage via keychain
+6. Runtime boot wiring so token state and encryption flags are initialized before first API call
+7. Feature flags and env values
+8. HMAC signing when enabled
+9. Compile/lint validation relevant to changed files
+
+**Minimum completion scope (Native mode — approach 5, all of above plus):**
+1. Native crypto bridge (NativeCryptoModule.kt + NativeCryptoPackage.kt, NativeCryptoModule.swift + .m bridge)
+2. JS bridge interface (native-crypto.module.ts)
+3. Interceptors updated to use native bridge calls
+4. ENCRYPTION_LAYER env flag wired
+5. NativeModules.NativeCryptoModule availability validated at JS startup
+6. Compile/lint validation relevant to changed files
+
+**Minimum completion scope (EC mode — approach 6):**
+1. EC types added to `types.ts` (EcPublicKeyResponse, EcEncryptedEnvelope, RequestCryptoMaterial)
+2. `ec-key.service.ts` — EC public key fetch/validate (65-byte, first byte 0x04)/cache/retry
+3. `ec-crypto.util.ts` — Hermes-safe helpers (toBase64, byteCopy, QCBuffer), HKDF-SHA256, ecEncryptPayload + ecDeriveKey (per-request) OR deriveSessionKey + sessionEncrypt + sessionDecrypt (session-init)
+4. `encryption-config.ts` — ENCRYPTION_MODEL=ec, EC_PUBLIC_KEY_ENDPOINT, EC_KEY_RETRY
+5. `api.ts` patched with ENCRYPTION_MODEL routing (EC branch + RSA branch)
+6. Per-request AES keys derived via HKDF and stored in in-memory request map; deleted after response
+7. `keychain.service.ts` for token storage
+8. `index.js` polyfill prepended
+9. Feature flags and env values
+10. Compile/lint validation relevant to changed files
+
+**Minimum completion scope (React JS web production mode — approach 7):**
+1. `crypto-utils.ts` — Base64 utilities, nonce generator (no Buffer dependency, pure browser APIs)
+2. `aes.service.ts` — AES-256-GCM key generation, encrypt, decrypt via `crypto.subtle`
+3. `rsa.service.ts` — RSA public key import (`importKey('spki')`) + RSA-OAEP encrypt via `crypto.subtle`
+4. `rsa-key.service.ts` — RSA key fetch/cache/retry service (or ECDH session service for ECDH-Session mode)
+5. `encryption.interceptor.ts` — Axios request + response interceptors with in-memory request key map
+6. `storage.service.ts` — `sessionStorage` wrapper or HTTP-only cookie guidance
+7. `encryption-config.ts` — feature flags + env values with correct framework prefix
+8. `types.ts` — `EncryptedEnvelope`, `EncryptedResponse` TypeScript types
+9. `axiosInstance.ts` wired with `applyProductionEncryptionInterceptor` + bootstrap call
+10. Feature flags and `.env.*` files with correct prefix (VITE_ / REACT_APP_ / NEXT_PUBLIC_)
+11. TypeScript/lint validation relevant to changed files
+12. (ECDH-Session sub-mode only) `base64url.ts`, `aad.ts`, `ecdhSession.ts`, `aesGcm.ts`, `ecdhSessionService.ts`
+
+---
+
+# When to Trigger This Skill
+
+- User wants to add end-to-end request encryption to a project
+- User wants to migrate a project to a stronger cryptographic approach
+- User asks to generate or scaffold `EncryptionService`, `EncryptionInterceptor`, or `EncryptionConfig`
+- User asks to enable HMAC signing on API requests
+- User asks to exclude specific URLs from encryption
+
+---
+
+# When NOT to Use
+
+- When only decryption on the backend is needed (backend-only work — no frontend scaffolding required)
+- When the project already has a complete, tested encryption layer (run detect.js first to confirm)
+- When a platform not listed in `assets/platform-matrix.json` is requested
+
+> **What this skill does NOT produce:**
+> Scan-related domain types, use cases, conflict-resolution enums, reporter classes, or any other non-encryption-service source files.
+> The end state is always: one config, one service, one interceptor/middleware — wired and building.
+
+---
+
+# Inputs
+
+| Input              | Source                    | Required | Notes                                                                          |
+|--------------------|---------------------------|----------|--------------------------------------------------------------------------------|
+| `projectPath`      | `--project-path` CLI arg  | Yes      | Absolute path to the target project root                                       |
+| `platform`         | Interactive prompt        | Yes      | One of: angular, web, node, android, ios, flutter, react, react-native         |
+| `approach`         | Interactive prompt        | Yes      | 1–6 or 7; valid range depends on platform (see platform-matrix.json)           |
+| `publicKeyPem`     | Interactive prompt        | Cond.    | Required for approaches 1, 2, 4, 5                                             |
+| `privateKeyPem`    | Interactive prompt        | No       | Only if response bodies are also encrypted (approaches 1/2 non-RN only)        |
+| `sharedKey`        | Interactive prompt        | Cond.    | Required for approach 3                                                        |
+| `rsaKeyEndpoint`     | Interactive prompt        | Cond.    | Approach 4/5: URL of RSA public key endpoint; default `<API_BASE_URL>/api/security/public-key` |
+| `rsaKeySource`       | Interactive prompt        | Cond.    | Approach 4/5: `api` (default) or `env`                                         |
+| `rsaResponseFormat`  | Interactive prompt        | Cond.    | Approach 4/5 api mode: expected shape of RSA key endpoint response; default `{ public_key: string, key_id: string, expires_at?: string }` |
+| `rsaKeyCachePolicy`  | Interactive prompt        | Cond.    | Approach 4/5: key caching policy; default `in-memory only` (never persist RSA key to disk or storage) |
+| `encryptionLayer`    | Interactive prompt        | Cond.    | React Native only: `rn` (default, approach 4) or `native` (approach 5)         |
+| `encryptionModel`    | Interactive prompt        | Cond.    | React Native only: `rsa` (default) or `ec` (ECDH+AES-256-GCM, approach 6)     |
+| `ecKeyEndpoint`                | Interactive prompt        | Cond.    | Approach 6: URL of EC public key endpoint; default `<API_BASE_URL>/api/security/ec-public-key` |
+| `ecContractType`               | Interactive prompt        | Cond.    | Approach 6: `per-request` (default) or `session-init`                          |
+| `ecCreateSessionEndpoint`      | Interactive prompt        | Cond.    | Approach 6 session-init: token/session endpoint URL after init; no default — must be confirmed |
+| `ecDeviceIdSource`             | Interactive prompt        | Cond.    | Approach 6 session-init: how the stable `device_id` is generated/retrieved; no default        |
+| `ecResponseEncoding`           | Interactive prompt        | Cond.    | Approach 6 session-init: response encoding (`standard-base64` or `base64url`); no default     |
+| `ecEncryptedAesKeyHandling`    | Interactive prompt        | Cond.    | Approach 6 session-init: whether `encrypted_shared_aes_key` from backend is `used` or `ignored`|
+| `minIosVersion`                | Interactive prompt        | Cond.    | Native mode only: minimum iOS version; default 13 (CryptoKit); < 13 → CommonCrypto fallback   |
+| `apiClientType`      | Interactive prompt        | Cond.    | Approach 4/5: `axios` (default), `fetch`, or `custom`                          |
+| `encryptionToggle`   | Interactive prompt        | Cond.    | Approach 4/5: `env-flag` (default) or `always-on`                              |
+| `hmac`               | Interactive prompt        | No       | Enable HMAC signing; secret set as `ENCRYPTION_HMAC_SECRET` env var            |
+| `excludeUrls`        | Interactive prompt        | No       | Comma-separated URL prefixes to skip                                           |
+| `webEncryptionMode`  | Interactive prompt        | Cond.    | Approach 7: `rsa-oaep` (default) or `ecdh-session`                             |
+| `framework`          | Interactive prompt        | Cond.    | Approach 7: `vite`, `cra`, or `nextjs` — determines env variable prefix        |
+| `tokenStorage`       | Interactive prompt        | Cond.    | Approach 7: `session-storage` (default) or `http-only-cookie`                  |
+| `ecdhSessionInitUrl` | Interactive prompt        | Cond.    | Approach 7 ECDH-Session: session init endpoint URL; no default — must be confirmed |
+| `ecdhHkdfInfo`       | Interactive prompt        | Cond.    | Approach 7 ECDH-Session: HKDF `info` string (backend-specific); no default    |
+| `ecdhAadShape`       | Interactive prompt        | Cond.    | Approach 7 ECDH-Session: canonical AAD JSON shape (alphabetically sorted keys); no default if AAD required |
+
+---
+
+# Outputs
+
+| Output                      | Description                                                                        |
+|-----------------------------|------------------------------------------------------------------------------------|
+| Config file                 | Platform-specific encryption settings file                                         |
+| Service file                | `EncryptionService` with encrypt/decrypt methods                                   |
+| Interceptor/middleware file | HTTP layer integration (interceptor or middleware)                                 |
+| Module wiring patch         | Patched registration in AppModule/NetworkModule/axiosInstance                      |
+| RSA key service             | (Approach 4/5 only) Fetch, cache, retry RSA public key from API or env             |
+| Response decryption         | (Approach 4/5 only) Response interceptor with request-scoped AES key map           |
+| Keychain storage module     | (Approach 4/5 only) Secure token/data storage via react-native-keychain            |
+| Native crypto bridge        | (Approach 5 only) NativeCryptoModule.kt, NativeCryptoPackage.kt, NativeCryptoModule.swift, NativeCryptoModule.m |
+| Envelope type definitions   | (Approach 4/5 only) `EncryptedEnvelope` and `EncryptedResponse` TypeScript types  |
+| EC type definitions         | (Approach 6 only) `EcPublicKeyResponse`, `EcEncryptedEnvelope`, `RequestCryptoMaterial` TypeScript types |
+| EC key service              | (Approach 6 only) Fetch, validate (65-byte P-256), cache, retry EC public key     |
+| EC crypto utility           | (Approach 6 only) `ecEncryptPayload`/`ecDeriveKey` (per-request) or `deriveSessionKey`/`sessionEncrypt`/`sessionDecrypt` (session-init), Hermes-safe helpers |
+| Web crypto utilities        | (Approach 7 only) `crypto-utils.ts`, `aes.service.ts`, `rsa.service.ts`, `rsa-key.service.ts` — zero npm packages, pure Web Crypto API |
+| Browser storage module      | (Approach 7 only) `storage.service.ts` — `sessionStorage` wrapper or HTTP-only cookie guidance |
+| Web encryption interceptor  | (Approach 7 only) Axios request + response interceptors with in-memory request key map and guaranteed cleanup |
+| ECDH-Session modules        | (Approach 7 ECDH-Session sub-mode only) `base64url.ts`, `aad.ts`, `ecdhSession.ts`, `aesGcm.ts`, `ecdhSessionService.ts` |
+| Backend alignment spec      | (Approach 4/5 only) Specification document for the backend team; Part B for approach 6 (EC) |
+| Setup report                | 6-field deterministic summary printed to stdout                                    |
+
+---
+
+# Dependencies
+
+| Dependency                               | Purpose                                                                              |
+|------------------------------------------|--------------------------------------------------------------------------------------|
+| `assets/platform-matrix.json`            | Platform compatibility and file paths                                                |
+| `assets/encryption-config-template.json` | Default config values                                                                |
+| `scripts/detect.js`                      | Scan project for existing encryption code                                            |
+| `scripts/install.js`                     | Write generated files to the target project                                          |
+| `scripts/setup.js`                       | Interactive wizard and orchestrator                                                  |
+| `references/approach-1-webcrypto.md`     | Web Crypto API flow, payload shape, iOS mapping                                      |
+| `references/approach-2-rsa-aes-cbc.md`  | jsencrypt+crypto-js flow, Java backend example                                       |
+| `references/approach-3-aes-sharedkey.md`| AES-CBC shared key flow, key generation                                              |
+| `references/angular-crypto.md`           | Angular interceptor wiring and file paths                                            |
+| `references/web-crypto.md`               | Web fetch wrapper wiring and file paths                                              |
+| `references/node-crypto.md`              | Node.js middleware wiring and file paths                                             |
+| `references/android-crypto.md`           | Android OkHttp interceptor wiring and file paths                                     |
+| `references/ios-crypto.md`               | iOS URLRequest mutator wiring and file paths                                         |
+| `references/flutter-crypto.md`           | Flutter Dio interceptor wiring and file paths                                        |
+| `references/react-crypto.md`             | React Axios interceptor wiring and file paths (approaches 1–3)                       |
+| `references/react-web-crypto.md`         | React JS web production mode: approach 7 implementation reference (RSA-OAEP and ECDH-Session via built-in Web Crypto API, browser-safe storage, no Buffer) |
+| `references/architecture.md`             | Mode A (JS) and Mode B (Native) architecture: component breakdown, data flow, request/response contract, security constraints                                   |
+| `references/react-native-crypto.md`      | React Native production-grade crypto: AES-256-GCM, per-request keys, RSA key service, response decryption, keychain storage, native bridge (approaches 4 & 5) |
+| `references/backend-alignment.md`        | Backend contract spec for approaches 4 & 5: envelope format, decryption steps, nonce validation, key rotation, error codes, integration test scenarios         |
+| `references/dependency-guidance.md`      | Library selection for all platforms, RN version compatibility table, install rules, conflict handling, post-install verification                                 |
+| `references/security-checklist.md`       | Security checklist covering all platforms and approaches — run before marking implementation complete                                                           |
+| `references/error-handling-playbook.md`  | Error handling playbook for all platforms: key fetch failure, auth tag mismatch, missing request map, storage failure, native module failures (approach 5)      |
+| `references/ec-implementation.md`        | EC (ECDH+AES-256-GCM) full implementation: per-request and session-init variants, Hermes Buffer compatibility helpers (`toBase64`, `byteCopy`, `QCBuffer`), HKDF-SHA256, EC key service with 65-byte point validation, EC wiring in api.ts, environment variables, deliverables table |
+| `references/native-rsa-implementation.md`| RSA + Native layer reference with full Kotlin/Swift NativeCryptoModule code, registration in MainApplication, ObjC bridge, JS bridge interface — load when approach 5 is selected |
+| `Instructions.md`                         | How to run this skill in a new project: prerequisites, execution breakdown, dependency install order, TypeScript verification steps, backend alignment, adapting to non-Axios clients |
+| `template.md`                             | Execution template — layer selection gate, config snapshot, project analysis; fill out at the start of each run                                                 |
+| `templates/config-questionnaire.md`      | Full numbered questionnaire with documented defaults — use in Step 5 to collect and validate all inputs before writing any files                                 |
+| `templates/delivery-checklist.md`        | Delivery checklist — all items that must be confirmed before final delivery                                                                                     |
+| `templates/implementation-plan.md`       | Implementation plan template — fill out before writing any files                                                                                                |
+| Node.js >= 18, built-in modules only     | `fs`, `path`, `readline`, `child_process`                                            |
+
+---
+
+# Execution Steps
+
+Follow these steps in order. Do not skip steps.
+
+## Step 1 — Validate inputs
+
+1. Read `assets/platform-matrix.json`. Confirm the file exists and is valid JSON.
+2. Read `assets/encryption-config-template.json`. Confirm it is valid JSON.
+3. Confirm `scripts/detect.js`, `scripts/install.js`, and `scripts/setup.js` exist and are executable.
+
+## Step 2 — Detect existing encryption
+
+1. Run: `node scripts/detect.js --project-path <projectPath>`
+2. If exit code = 2 (error): Report the error and halt.
+3. If exit code = 1 (FOUND): Print the matched files, then display the following prompt exactly and wait for user input. Do NOT continue until the user selects an option:
+
+```
+Existing encryption logic detected. Choose how to proceed:
+  1. Reuse existing logic (use existing service/interceptor, generate only missing parts)
+  2. Replace with new implementation
+  3. Refactor and centralize existing logic (scaffold common module, do not overwrite existing)
+  4. Cancel setup
+```
+
+   - Option 1 (reuse): Pass `--detection-mode reuse` to `install.js`. Existing files are skipped; only missing files are generated. Wiring file is patched normally.
+   - Option 2 (replace): Pass `--detection-mode replace` to `install.js`. Existing behavior — all files are overwritten.
+   - Option 3 (refactor): Pass `--detection-mode refactor` to `install.js`. Scaffold files (`*.scaffold.*`) are written alongside existing files. No files are overwritten. Wiring file is NOT patched. Migration instructions are printed.
+   - Option 4 (cancel): Halt immediately. Exit code 2.
+
+## Step 3 — Resolve platform and approach
+
+1. Confirm `platform` is a key in `assets/platform-matrix.json`.
+2. Confirm `approach` is listed in `platform.approaches[]` for the selected platform.
+3. If the combination is blocked (e.g. node+approach1): Explain the constraint and ask the user to choose a valid approach.  
+   Reference `assets/platform-matrix.json` for the definitive compatibility list.
+
+## Step 4 — Load reference files
+
+1. Load the approach reference file that matches approach:
+   - approach 1 → `references/approach-1-webcrypto.md`
+   - approach 2 → `references/approach-2-rsa-aes-cbc.md`
+   - approach 3 → `references/approach-3-aes-sharedkey.md`
+   - approach 4 → `references/react-native-crypto.md` (section: RN JS production mode)
+   - approach 5 → `references/react-native-crypto.md` (section: Native mode)
+   - approach 6 → `references/ec-implementation.md` (per-request or session-init ECDH+AES-256-GCM)
+   - approach 7 → `references/react-web-crypto.md` (React JS Web Crypto API production mode)
+2. Load the platform reference file that matches platform:
+   - `references/<platform>-crypto.md`
+3. For `react-native` with approaches 4 or 5, also load:
+   - `references/backend-alignment.md` — envelope format, decryption steps, nonce rules, error codes
+   - `references/security-checklist.md` — security gates to verify before delivery
+   - `references/error-handling-playbook.md` — failure paths including native mode
+4. For `react-native` with approach 5, additionally load:
+   - `references/native-rsa-implementation.md` — full Kotlin/Swift NativeCryptoModule with registration steps
+5. For `react-native` with approach 6, additionally load:
+   - `references/ec-implementation.md` — EC key service, HKDF-SHA256, Hermes Buffer helpers, per-request and session-init patterns
+   - `references/backend-alignment.md` — Part B (EC contract)
+   - `references/security-checklist.md` — EC section
+   - `references/error-handling-playbook.md`
+6. For `react` with approach 7, additionally load:
+   - `references/react-web-crypto.md` — Web Crypto API production mode, RSA-OAEP and ECDH-Session implementations, framework detection, browser storage rules
+   - `references/security-checklist.md` — Web section
+   - `references/error-handling-playbook.md` — Web Crypto API error scenarios
+7. Before writing any files, fill out `templates/implementation-plan.md` mentally (project discovery, dependency plan, file list, runtime behaviour).
+
+## Step 5 — Collect key material
+
+1. Collect all inputs as defined in the Inputs table.
+2. Identify project structure (API client location, interceptor location, config/env module, token storage module, app startup file) before writing any files — do not duplicate existing modules; extend them.
+3. If approach 1 or 2 and no `publicKeyPem` provided, warn the user that encryption cannot function.
+4. If approach 3 and no `sharedKey` provided, warn the user.
+4. **Approach 4 (React Native JS production mode):**
+   - Ask the layer selection question first: `Which encryption layer? [rn (default) / native]`
+   - If `rn` selected → approach 4. Collect:
+     - RSA padding: default RSA-OAEP (recommend; PKCS1 v1.5 requires explicit approval)
+     - RSA public key source: `api` (default) or `env`
+     - If `api`: confirm endpoint URL (default `<API_BASE_URL>/api/security/public-key`), retry count (default 3), response format (default `{ public_key: string, key_id: string, expires_at?: string }`), key caching policy (default: in-memory only — never persist RSA key to disk or storage)
+     - If `env`: collect and validate PEM/Base64 key value
+     - RSA padding: default RSA-OAEP (PKCS1 v1.5 requires explicit written approval; not acceptable for new deployments in 2026)
+     - API client: Axios (default), Fetch, or Custom
+     - API layer path: default `src/services/api.ts`
+     - Enable secure keychain storage for tokens: default Yes
+     - Encryption toggle: `env-flag` (default) or `always-on`
+     - Platform scope: Android + iOS (default)
+     - HMAC signing: default No
+     - Exclude URL prefixes: optional
+   - If `native` selected → approach 5. Collect same as approach 4, plus:
+     - Minimum iOS version (default 13 for CryptoKit; if < 13, use CommonCrypto fallback — `CCCryptorGCM` for AES-256-GCM + `SecKeyCreateEncryptedData` for RSA-OAEP)
+     - Verify Android minSdkVersion >= 23 in project `android/app/build.gradle` before proceeding; halt with guidance if below
+5. **Approach 6 (EC / ECDH+AES-256-GCM):**
+   - Ask questions **one at a time** — each question is a single prompt; wait for the answer before asking the next.
+   - Ask EC contract type first: `per-request` (default) or `session-init`
+   - EC public key source: `api` (default) or `env`
+   - If `api`: confirm endpoint URL (default `<API_BASE_URL>/api/security/ec-public-key`), retry count (default 3)
+   - If `env`: collect and validate the key (must be 65-byte uncompressed P-256 point in base64)
+   - Session-init additional questions (ALL are blocking — no safe defaults — ask each individually):
+     1. Session init endpoint URL (`SESSION_INIT_ENDPOINT`)
+     2. Token/session endpoint URL (`CREATE_SESSION_ENDPOINT`) — credential exchange after encryption session init
+     3. HKDF `info` string (backend-specific — do NOT assume `'enc'`)
+     4. Nonce format
+     5. Nonce length
+     6. Nonce character set restrictions
+     7. Response encoding: standard base64 or base64url
+     8. Whether AAD is required, and if yes, the canonical JSON shape (alphabetically sorted keys)
+     9. Response IV source (nonce-as-IV, separate `iv` field, or other)
+     10. `DEVICE_ID_SOURCE` — how the stable `device_id` is generated/retrieved
+     11. Whether `encrypted_shared_aes_key` returned by backend should be `used` or `ignored`
+   - API client: Axios (default), Fetch, or Custom
+   - API layer path: default `src/services/api.ts`
+   - Encryption layer: `rn` (default, JS crypto) or `native` (ECDH in JS, AES in native)
+   - HMAC signing: default No
+   - Exclude URL prefixes: optional
+   - **All session-init EC contract questions are blocking** — they have no safe defaults. Do not proceed until the user provides all items above.
+6. **Approach 4/5/6 input validation:**
+   - Validate all user-provided URLs are HTTPS.
+   - Validate RSA public key PEM format if provided via env (approach 4/5).
+   - Validate EC public key is a 65-byte uncompressed P-256 point (first byte `0x04`) if provided via env (approach 6).
+   - Validate API layer path exists in the project before editing.
+
+## Input Validation Requirements (All Platforms)
+
+- Validate all user-provided URLs are HTTPS.
+- Validate RSA public key format — PEM headers (`-----BEGIN PUBLIC KEY-----`) must be present.
+- Validate selected API layer path exists in the project before editing.
+- Validate platform scope against current project targets.
+- Shared key must be at least 32 characters (approach 3). Reject and re-prompt on failure.
+- If any required answer is missing and has no safe default, ask one follow-up batch and wait.
+- If a safe default exists, apply it automatically and continue without asking.
+- The only question that remains blocking without a default is the RSA public key value when env mode is explicitly chosen.
+
+## Step 6 — Generate and install files
+
+1. Build a resolved config object from `assets/encryption-config-template.json` merged with collected inputs.
+2. Write the resolved config to a temporary file (do not persist).
+3. Run: `node scripts/install.js --config-json <tempFile>`
+4. Delete the temp file immediately after install.js exits, regardless of exit code.
+5. On exit code 0: Continue to Step 6a.
+6. On exit code 1 or 2: Report the error and halt.
+
+## Step 6a — Standalone Angular wiring (NgModule-free projects)
+
+Applies only when `platform = angular`.
+
+1. Check if `src/app/app.module.ts` exists in the project.
+2. If it does NOT exist, the project uses the standalone component model (no NgModule).
+   - `install.js` will automatically patch `src/app/app.config.ts` using `standaloneWiringFile` from `platform-matrix.json`.
+   - Verify `app.config.ts` contains `provideHttpClient(withInterceptorsFromDi())` and the `HTTP_INTERCEPTORS` provider after patching.
+   - Add `allowedCommonJsDependencies` for `crypto-js` / `jsencrypt` to `angular.json` (approaches 2/3) — read values from `platform-matrix.json[platform].allowedCommonJsDependencies`.
+
+## Step 6b — React Native production wiring (approaches 4, 5, and 6)
+
+Applies only when `platform = react-native` and `approach = 4`, `5`, or `6`.
+
+1. **Analyze project structure** before writing any file:
+   - Identify existing API client location, interceptor location, config/env module, storage module, app startup file.
+   - Do not duplicate existing modules; extend them.
+2. **Install dependencies** (check React Native version from `package.json` first):
+   - Approach 4: `react-native-quick-crypto`, compatible RSA library, `react-native-keychain`
+   - Approach 5: `react-native-aes-crypto`, `react-native-rsa-native`, `react-native-keychain`
+   - Approach 6: `react-native-quick-crypto` (provides `createECDH`, `createCipheriv`, `createHmac`, `randomBytes`), `react-native-keychain`, `buffer` package (standard polyfill)
+   - Verify Android `minSdkVersion >= 23` for approach 5; halt with guidance if below.
+   - Verify iOS deployment target `>= 13.0` for CryptoKit (approach 5); plan CommonCrypto fallback if below.
+3. `install.js` writes the following files for approach 4:
+   - `src/services/security/types.ts` — `EncryptedEnvelope` and `EncryptedResponse` TypeScript interfaces
+   - `src/services/security/encryption.service.ts` — per-request AES-256-GCM encrypt using `react-native-quick-crypto`
+   - `src/services/security/decryption.service.ts` — AES-256-GCM decrypt + auth tag split
+   - `src/services/security/rsa-key.service.ts` — fetch/cache/retry RSA public key from endpoint or env
+   - `src/services/security/keychain.service.ts` — `react-native-keychain` wrapper for token storage
+   - `src/services/security/hmac.service.ts` — HMAC-SHA256 signing (when HMAC enabled)
+   - `src/services/security/encryption-config.ts` — `EXCLUDED_PATHS`, feature flags, env references
+   - Updated request interceptor + response interceptor with in-memory request map and guaranteed cleanup
+   - Updated `index.js` — `ENCRYPTION_ENABLED` env bootstrap
+4. `install.js` writes the following **additional** files for approach 5 (all of approach 4, plus):
+   - `android/app/src/main/java/.../NativeCryptoModule.kt` — `encryptAES`, `decryptAES`, `encryptRSA` via `javax.crypto.Cipher`
+   - `android/app/src/main/java/.../NativeCryptoPackage.kt` — package registration
+   - `ios/NativeCryptoModule.swift` — CryptoKit `AES.GCM` + `SecKeyCreateEncryptedData` (no `try!`)
+   - `ios/NativeCryptoModule.m` — ObjC bridge file
+   - `src/services/security/native-crypto.module.ts` — JS bridge interface (`nativeEncryptAES`, `nativeDecryptAES`, `nativeEncryptRSA`)
+   - Updated `.env` with `ENCRYPTION_LAYER=native`
+5. `install.js` writes the following files for approach 6 (EC mode):
+   - `src/services/security/types.ts` — add `EcPublicKeyResponse`, `EcEncryptedEnvelope`, `RequestCryptoMaterial` alongside existing RSA types
+   - `src/services/security/ec-key.service.ts` — EC public key fetch/cache/retry with 65-byte point validation
+   - `src/services/security/ec-crypto.util.ts` — `ecEncryptPayload` (per-request) or `deriveSessionKey`/`sessionEncrypt`/`sessionDecrypt` (session-init), plus Hermes-safe helpers (`toBase64`, `byteCopy`, `QCBuffer`), HKDF-SHA256
+   - `src/services/security/keychain.service.ts` — same as approach 4
+   - `src/services/security/hmac.service.ts` — HMAC-SHA256 signing (when HMAC enabled)
+   - `src/services/security/encryption-config.ts` — `ENCRYPTION_MODEL=ec`, `EC_PUBLIC_KEY_ENDPOINT`, `ENCRYPTION_LAYER`, feature flags
+   - Updated `src/services/api.ts` — patch to add `ENCRYPTION_MODEL` routing: EC branch uses `ecKeyService` + `ecEncryptPayload`/`ecDeriveKey`; RSA branch unchanged
+   - For EC + Native: `ecDeriveKey` (ECDH in JS) + existing `NativeCryptoModule` for AES (no new Kotlin/Swift files)
+   - Updated `.env` / `.env.example` with `ENCRYPTION_MODEL=ec`, `EC_PUBLIC_KEY_ENDPOINT`
+6. **AES key lifecycle rule (approaches 4, 5, and 6 per-request):** Per-request AES keys/derived keys are generated in JS using `randomBytes(32)` (or HKDF), stored in-memory in a request map keyed by `requestId`, passed into encrypt/decrypt calls, and **deleted immediately after response processing** — success or failure. Never written to storage.
+7. **Response interceptor rule:** On `KEY_ID_NOT_FOUND` (401): refresh the active key service (RSA or EC) and retry exactly once. On auth tag mismatch: trigger force logout/session reset. On missing request map entry: fail securely without retry.
+8. **Session-init EC rule:** After session init, the derived session AES key is held in memory only. If the app restarts and only the token is stored, the encryption session must be re-established before encrypted APIs can work. Persist only the auth token.
+9. **Backend alignment spec:** Print the full backend contract from `references/backend-alignment.md` so the user can share it with their server team. For EC, print Part B (EC contract). Include: envelope format, decryption steps, nonce validation, error codes, and pre-integration questions.
+10. After all files are written, run the build verification step (Step 7) then verify every item in `references/security-checklist.md` (React Native section) and `templates/delivery-checklist.md` before printing the setup report.
+
+## Step 6c — React JS web production wiring (approach 7)
+
+Applies only when `platform = react` and `approach = 7`.
+
+1. **Verify secure origin** before proceeding: confirm the app is served over HTTPS or localhost. `crypto.subtle` is `undefined` on plain HTTP origins — warn the user and halt if the deployment target is plain HTTP.
+2. **Detect framework/bundler** (ask if not yet answered):
+   - Vite → env prefix `VITE_`
+   - Create React App → env prefix `REACT_APP_`
+   - Next.js → env prefix `NEXT_PUBLIC_`
+3. **Check `tsconfig.json`**: confirm `"lib"` includes `"DOM"` (required for `crypto.subtle` typings). Patch if missing.
+4. **Install dependencies** — approach 7 requires no crypto packages:
+   - Confirm `axios` is present; install if missing.
+   - Never install `crypto-js`, `node-forge`, Buffer polyfill, or any `react-native-*` package.
+5. **RSA-OAEP mode** (`webEncryptionMode = rsa-oaep`, default) — `install.js` writes:
+   - `src/services/security/crypto-utils.ts` — Base64 encode/decode (`btoa`/`atob`/`TextEncoder`/`Uint8Array`), nonce generator (`crypto.getRandomValues`)
+   - `src/services/security/aes.service.ts` — `generateAESKey` (`crypto.subtle.generateKey`), `encryptAESGCM`, `decryptAESGCM` (tagLength 128)
+   - `src/services/security/rsa.service.ts` — `importRSAPublicKey` (`importKey('spki', ...)` from PEM after stripping headers), `encryptRSAOAEP`
+   - `src/services/security/rsa-key.service.ts` — fetch, cache (in-memory), retry (3× default), `KEY_ID_NOT_FOUND` refresh + single retry
+   - `src/services/security/hmac.service.ts` — HMAC-SHA256 via `crypto.subtle` (when HMAC enabled)
+   - `src/services/security/storage.service.ts` — `sessionStorage` wrapper for non-token data; HTTP-only cookie guidance for auth tokens; `localStorage` forbidden for sensitive data
+   - `src/services/security/encryption-config.ts` — `ENCRYPTION_ENABLED`, `RSA_PUBLIC_KEY_ENDPOINT`, `ENCRYPTION_HMAC_SECRET` with correct framework env prefix
+   - `src/services/security/types.ts` — `EncryptedEnvelope`, `EncryptedResponse` TypeScript interfaces
+   - `src/services/security/encryption.interceptor.ts` — request interceptor (generate AES key, store in `Map<requestId, {cryptoKey, iv}>`, attach envelope); response interceptor (decrypt + cleanup map entry); guaranteed cleanup on both success and error
+   - `src/api/axiosInstance.ts` — patched with `applyProductionEncryptionInterceptor` + `bootstrapEncryption()` call before first request
+   - `.env.example` / `.env.local` — feature flag env vars with correct prefix
+6. **ECDH-Session mode** (`webEncryptionMode = ecdh-session`) — collect blocking inputs first (ask one at a time, no defaults):
+   - Session init endpoint URL
+   - HKDF `info` string (backend-specific — do NOT assume `'enc'`)
+   - AAD requirement and canonical JSON shape (alphabetically sorted keys; use template literal, not `JSON.stringify`)
+   - Response encoding (standard base64 or base64url)
+   - Device ID source
+   Then `install.js` writes all of RSA-OAEP files above (except `rsa.service.ts`, `rsa-key.service.ts`) plus:
+   - `src/core/security/ecdh-session/base64url.ts` — Base64URL encode/decode (no Buffer)
+   - `src/core/security/ecdh-session/aad.ts` — AAD builder (alphabetical key order enforced)
+   - `src/core/security/ecdh-session/ecdhSession.ts` — `generateECDHKeyPair`, `exportPublicKey`, `deriveSessionKey` via `crypto.subtle.generateKey` + `crypto.subtle.deriveKey` (HKDF-SHA256, native — no manual HMAC chain); private key exported as JWK for `sessionStorage` restore; derived AES key `extractable: false`, never stored
+   - `src/core/security/ecdh-session/aesGcm.ts` — AES-256-GCM encrypt/decrypt with AAD
+   - `src/core/security/ecdh-session/ecdhSessionService.ts` — session init, session restore from `sessionStorage`, `clearSession` (called on 401 or `DECRYPTION_FAILED`)
+   - Updated `encryption.interceptor.ts` — ECDH-Session variant with `X-Request-ID` (UUID), `X-Nonce` (12-byte Base64URL), `X-Timestamp` (ISO 8601 UTC) headers on every request
+7. **AES key lifecycle rule (approach 7):** Per-request AES keys are generated per request, stored in-memory in a `Map<requestId, {cryptoKey: CryptoKey; iv: Uint8Array}>`, and deleted immediately after response processing — success or failure. Never written to storage.
+8. **Response interceptor rule (approach 7):** On `KEY_ID_NOT_FOUND` (401): refresh RSA key and retry exactly once (no retry loop). On `DOMException` (auth tag mismatch) during decryption: fail securely — do not fall back to unencrypted response. On missing request map entry: log a warning and pass the response through without decryption.
+9. **ECDH-Session error handling:** 401 response → `clearSession()` + `ERR_SESSION_EXPIRED`. `DECRYPTION_FAILED`/`INVALID_PAYLOAD` (400) → `clearSession()` + `ERR_CRYPTO_REJECTED`. 500 responses → pass through without session invalidation.
+10. After all files are written, run the build verification step (Step 7) then verify every item in `references/security-checklist.md` (Web section) and `templates/delivery-checklist.md` before printing the setup report.
+
+## Step 7 — Run build verification
+
+1. Read `buildCommand` for the platform from `assets/platform-matrix.json`.
+2. Run the build command in the project root.
+3. On failure: Retry up to 3 times, then report exit code 4.
+4. On success: Continue to Step 8.
+
+## Step 8 — Print setup report
+
+Print the setup report as defined in Output Format.
+
+---
+
+# Rules
+
+1. **Never hardcode** file paths, package names, or build commands — always read from `assets/platform-matrix.json`.
+2. **Never print** the HMAC secret or any private key material to stdout or disk. HMAC secret is read at runtime from `ENCRYPTION_HMAC_SECRET` environment variable.
+3. **Validate inputs**: `publicKeyPem` must contain valid PEM headers; `sharedKey` must be at least 32 characters. Reject and re-prompt on failure.
+4. **Block `privateKeyPem` for browser platforms**: Never accept or store `privateKeyPem` for `angular` or `web` platforms. Private keys must stay on the server. If the user provides one, warn them and set `privateKeyPem: null` in the generated config.
+5. **Idempotent**: Running setup.js with the same inputs must always produce the same files.
+6. **Skip FormData**: Never encrypt multipart/form-data — always pass through.
+7. **Catch errors silently in interceptors (approaches 1–3)**: Encryption failure must never cause a request to fail; fall back to sending unencrypted and log at debug level only.
+8. **Never overwrite module wiring**: Use `patchFile()` (marker-based append) — never replace the entire file.
+9. **Approach 4/5 — AES keys are ephemeral**: Never persist AES keys or IVs. Never reuse IVs. Clear request map immediately after each response (success or failure).
+10. **Approach 4/5 — Fail secure on auth tag mismatch**: Invalid GCM auth tag must trigger session reset/force logout — not a silent fallback.
+11. **Approach 4/5 — RSA key retry is bounded**: Retry at most 3 times (configurable); block encrypted calls if key is unavailable after retries.
+12. **Approach 4/5 — KEY_ID_NOT_FOUND**: Refresh RSA key and retry exactly once. No retry loop.
+13. **Approach 4/5 — No sensitive logging**: Never log AES keys, IVs, auth tags, plaintext payloads, or RSA key material.
+14. **Approach 5 — Ephemeral AES keys are NOT stored in Android Keystore**: Android Keystore is for persistent long-lived keys. Per-request AES keys live only in the JS memory map.
+15. **Approach 5 — `try!` is forbidden**: All Swift CryptoKit code must use `do/try/catch`. Never use `try!` in production.
+16. **Approach 4/5 — PKCS1 v1.5 is rejected for new deployments**: RSA-OAEP SHA-256 is mandatory. PKCS1 v1.5 requires explicit written approval and is not acceptable for new deployments in 2026.
+17. **Approach 4/5 — RSA key endpoint must be HTTPS**: Never fetch the public key over HTTP. Validate URL scheme at setup time.
+18. **Approach 4/5 — SSL pinning recommended**: For high-security environments, configure certificate pinning with a current and backup fingerprint before deploying to production.
+19. **Approach 4/5 — Never mix JS and Native crypto in the same request lifecycle**: The encryption layer (JS or Native) must be consistent for the full request/response cycle. Do not call JS crypto for encryption and native crypto for decryption, or vice versa.
+20. **All platforms — Never bypass existing API architecture**: Extend the existing interceptor/client; never replace it or create a parallel HTTP layer that bypasses auth, logging, or error handling.
+21. **Approach 6 — EC public key must be validated on every fetch**: decoded length must equal 65 bytes and first byte must be `0x04` (uncompressed P-256 point). Reject and retry if invalid.
+22. **Approach 6 — Ephemeral EC private key is discarded immediately after `computeSecret()`**: Never store the ECDH private key in memory beyond the single key derivation call.
+23. **Approach 6 — Derived AES key is never transmitted**: Only the 65-byte ephemeral public key is sent in the envelope. The AES key lives only in the in-memory request map.
+24. **Approach 6 — Never use `Buffer.toString('base64')` on Hermes**: Use the `toBase64()` helper from `ec-crypto.util.ts`. Hermes typed arrays break the standard base64 polyfill.
+25. **Approach 6 — Never use `Buffer.slice()` views with quick-crypto native code**: Always call `byteCopy()` before passing any sliced buffer to a cipher, HMAC, or HKDF call.
+26. **Approach 6 — Session-init blocking questions**: All of the following are backend-specific and have no safe defaults. Ask each **one at a time** and do not proceed until the user provides all: (1) session init endpoint URL, (2) token/session endpoint URL, (3) HKDF `info` string, (4) nonce format, (5) nonce length, (6) nonce character set, (7) response encoding (standard-base64 vs base64url), (8) AAD requirement and canonical JSON shape, (9) response IV source, (10) `DEVICE_ID_SOURCE`, (11) `encrypted_shared_aes_key` handling (used/ignored).
+27. **Approach 6 — EC key endpoint must be HTTPS**: Validate URL scheme at setup time. Same rule as RSA (Rule 17).
+28. **Approach 7 — `crypto.subtle` requires a secure origin**: The Web Crypto API is `undefined` on plain HTTP origins. The app must be served over HTTPS or `localhost`. Check at startup and surface a clear error if unavailable — never silently swallow the failure.
+29. **Approach 7 — No Buffer polyfill, no `crypto-js`, no `node-forge`**: All crypto operations use the built-in Web Crypto API (`window.crypto.subtle`). Never install or import these packages for approach 7.
+30. **Approach 7 — RSA-OAEP is mandatory**: Same rule as Rule 16. PKCS1 v1.5 requires explicit written approval and is not acceptable for new deployments in 2026.
+31. **Approach 7 — RSA public key import uses `'spki'` format**: Strip PEM headers before passing to `crypto.subtle.importKey`. Never pass the raw PEM string to the API.
+32. **Approach 7 — AES keys are ephemeral, never stored**: Per-request AES key and IV live only in the in-memory `Map<requestId, {cryptoKey, iv}>`. Delete the map entry immediately after response processing, success or failure.
+33. **Approach 7 — Derived AES key must be non-extractable (ECDH-Session)**: Pass `extractable: false` to `crypto.subtle.deriveKey`. Never store the derived AES key anywhere, including `sessionStorage`. Only the ECDH private key (as JWK) may be stored in `sessionStorage` for session restore.
+34. **Approach 7 — `localStorage` is forbidden for tokens or session material**: Use `sessionStorage` for non-critical state or HTTP-only cookies for auth tokens. Never store token, session key, or AES key in `localStorage`.
+35. **Approach 7 — Never use `Math.random()` for cryptographic purposes**: All nonce and key generation must use `crypto.getRandomValues()` or Web Crypto API key generation. `Math.random()` is not cryptographically secure.
+36. **Approach 7 — HMAC secret must come from env var at runtime**: Never hardcode `ENCRYPTION_HMAC_SECRET` in source files or commit it to version control. Read it from the framework-prefixed env var at runtime only.
+37. **Approach 7 — `DOMException` on decryption is a hard failure**: An AES-GCM authentication tag mismatch throws `DOMException`. Treat this as a security failure — do not fall back to returning the raw ciphertext. Propagate as `ERR_CRYPTO_REJECTED`.
+38. **Approach 7 — ECDH-Session blocking questions have no safe defaults**: HKDF `info` string, AAD shape, session init URL, and device ID source are all backend-specific. Ask each one at a time and do not proceed until all are provided.
+39. **Approach 7 — `tsconfig.json` must include `"DOM"` in `lib`**: Without it, `crypto.subtle` TypeScript types are unavailable and compilation will fail. Patch `tsconfig.json` automatically if this lib is missing.
+40. **Approach 7 — CORS headers must include custom encryption headers**: `Access-Control-Allow-Headers` on the backend must allow `X-Request-ID`, `X-Nonce`, `X-Request-Signature`, `X-Device-ID`, and `X-Timestamp`. Include this requirement in backend alignment guidance.
+
+---
+
+# Output Format
+
+## Setup report (stdout, always)
+```
+=== SETUP REPORT ===
+Platform                : <platform>
+Approach                : <approach>
+HMAC enabled            : <true|false>
+URL exclusions          : <comma-separated list or blank>
+Files written/patched   : <integer>
+Build status            : <PASS|FAIL>
+====================
+```
+
+## Per-file output (from install.js)
+```
+WROTE   <absolute path>
+PATCHED <absolute path>
+INSTALL_RESULT : SUCCESS
+```
+
+---
+
+# Final State Checklist
+
+After a successful run, verify:
+- [ ] One centralized config file exists with encryption settings
+- [ ] One shared EncryptionService exists with encrypt and decrypt methods (existing one reused if previously centralized)
+- [ ] One interceptor/middleware exists that calls EncryptionService transparently
+- [ ] The network/HTTP layer is patched to use the interceptor
+- [ ] Build passes with zero errors
+- [ ] **No scan-related types, use cases, or reporter classes exist in the output**
+- [ ] **No conflict-resolution enums or domain layer abstractions exist in the output**
+- [ ] **No duplicate EncryptionService files — exactly one per project**
+
+---
+
+# Example 1 — Angular + Approach 1 (RSA-OAEP + AES-256-GCM)
+
+```bash
+node scripts/setup.js --project-path /projects/my-angular-app
+```
+
+Prompts:
+```
+Select platform [angular/web/node/android/ios/flutter]: angular
+Select approach [1/2/3]: 1
+Enter public key PEM: <paste RSA-2048 public key>
+Decrypt responses too? (yes/no) [no]: no
+Enable HMAC signing? (yes/no) [no]: no
+  HMAC enabled. Set the ENCRYPTION_HMAC_SECRET environment variable in your app before running.
+Exclude any URL prefixes from encryption? (comma-separated, or leave blank):
+```
+
+Expected output snippets:
+```
+WROTE   /projects/my-angular-app/src/environments/environment.ts
+WROTE   /projects/my-angular-app/src/app/core/encryption/encryption.service.ts
+WROTE   /projects/my-angular-app/src/app/core/encryption/encryption.interceptor.ts
+PATCHED /projects/my-angular-app/src/app/app.config.ts
+NOTE  Angular standalone project detected. Patched app.config.ts instead of app.module.ts.
+INSTALL_RESULT : SUCCESS
+
+=== SETUP REPORT ===
+Platform                : angular
+Approach                : 1
+HMAC enabled            : false
+URL exclusions          :
+Files written/patched   : 4
+Build status            : PASS
+====================
+```
+
+---
+
+# Example 2 — Android + Approach 3 (AES-256-CBC shared key)
+
+```bash
+node scripts/setup.js --project-path /projects/my-android-app
+```
+
+Prompts:
+```
+Select platform [angular/web/node/android/ios/flutter]: android
+Select approach [2/3]: 3
+Enter shared secret key (32+ chars recommended): <paste secret>
+Enable HMAC signing? (yes/no) [no]: yes
+  HMAC enabled. Set the ENCRYPTION_HMAC_SECRET environment variable in your app before running.
+Exclude any URL prefixes from encryption? (comma-separated, or leave blank): /api/health,/api/status
+```
+
+Expected output snippets:
+```
+WROTE   /projects/my-android-app/app/src/main/java/com/example/encryption/EncryptionConfig.kt
+WROTE   /projects/my-android-app/app/src/main/java/com/example/encryption/EncryptionService.kt
+WROTE   /projects/my-android-app/app/src/main/java/com/example/encryption/EncryptionInterceptor.kt
+PATCHED /projects/my-android-app/app/src/main/java/com/example/network/NetworkModule.kt
+INSTALL_RESULT : SUCCESS
+
+=== SETUP REPORT ===
+Platform                : android
+Approach                : 3
+HMAC enabled            : true
+URL exclusions          : /api/health, /api/status
+Files written/patched   : 4
+Build status            : PASS
+====================
+```