indraq_cli 1.5.8 → 1.9.1

package/README.md

@@ -1,1686 +1,1517 @@
-<p align="center">
-  <img src="docs/assets/indraq-logo.png" alt="IndraQ Innovations" width="620" />
-</p>
-
-<h1 align="center">IndraQ CLI</h1>
-
-<p align="center">
-  <strong>One command-line tool for IndraQ engineering operations.</strong>
-</p>
-
-<p align="center">
-  Docker & GHCR deployments · Jenkins automation · Expo / React Native Android builds · Live terminal logs
-</p>
-
-<p align="center">
-  <img alt="npm" src="https://img.shields.io/npm/v/indraq_cli?logo=npm&label=npm" />
-  <img alt="Node 22+" src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white" />
-  <img alt="Java 21" src="https://img.shields.io/badge/Java-21%20recommended-ED8B00?logo=openjdk&logoColor=white" />
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" />
-  <img alt="License" src="https://img.shields.io/npm/l/indraq_cli" />
-  <img alt="Version" src="https://img.shields.io/badge/version-1.5.8-264B63" />
-</p>
-
-> [!IMPORTANT]
-> **IndraQ CLI is an engineering operations CLI created by IndraQ Innovations.** It is publicly installable from npm. The tool is designed so new internal capabilities can be added as separate modules instead of growing into one giant script.
-
----
-
-## Index
-
-1. [What is IndraQ CLI?](#what-is-indraq-cli)
-2. [Explain it like I am new](#explain-it-like-i-am-new)
-3. [What changed in v1.5.8?](#what-changed-in-v158)
-4. [Requirements](#requirements)
-5. [Install Java 21](#install-java-21)
-6. [Install IndraQ CLI](#install-indraq-cli)
-7. [Run the doctor](#run-the-doctor)
-8. [Configuration home](#configuration-home)
-9. [Configure Jenkins](#configure-jenkins)
-10. [Configure Docker / GHCR](#configure-docker--ghcr)
-11. [Configure Mobile App](#configure-mobile-app)
-12. [Docker deployment](#docker-deployment)
-13. [Mobile build overview](#mobile-build-overview)
-14. [Mobile build matrix](#mobile-build-matrix)
-15. [Mobile build commands](#mobile-build-commands)
-16. [Mobile build flags](#mobile-build-flags)
-17. [Android versioning and artifact names](#android-versioning-and-artifact-names)
-18. [How local source reaches Jenkins](#how-local-source-reaches-jenkins)
-19. [Root .env behavior](#root-env-behavior)
-20. [Mobile Jenkins setup](#mobile-jenkins-setup)
-21. [Configuration and secret storage](#configuration-and-secret-storage)
-22. [Upgrade from v1.4 / v1.5](#upgrade-from-v14--v15)
-23. [Command reference](#command-reference)
-24. [Troubleshooting](#troubleshooting)
-25. [Frequently asked questions](#frequently-asked-questions)
-26. [Project architecture](#project-architecture)
-27. [Final checklist](#final-checklist)
-28. [License](#license)
-
----
-
-## v1.5.8 — Git-safe shared configuration
-
-Project configuration is now intentionally shareable without exposing Jenkins credentials:
-
-```text
-COMMIT / SHARE
-.indraq/jenkins.json
-.indraq/docker.json
-.indraq/mobile.json
-
-LOCAL ONLY / IGNORE
-.indraq/jenkins.local.json
-```
-
-IndraQ reuses an existing project `.gitignore`, adds `.indraq/jenkins.local.json` only when the exact rule is missing, and does not add an ignore-all `.indraq/` rule. Re-running configuration is idempotent, so the same ignore entry is never appended repeatedly. Actual Jenkins username/token/password data stays outside the repository under the user's home directory.
-
-Docker deployments also continue to preserve Docker's existing GHCR credential store; IndraQ does not run `docker login ghcr.io` during deployment.
-
----
-
-## What is IndraQ CLI?
-
-IndraQ CLI is a program you install once on a developer computer and then use from **any project folder**.
-
-Instead of remembering many Docker, GitHub, Jenkins, Android, and build commands, you run a small IndraQ command such as:
-
-```bash
-indraq deploy:dev
-```
-
-or:
-
-```bash
-indraq build mobile:staging
-```
-
-The CLI validates the request, uses the saved configuration for the current project, performs the work, and shows failures directly in the same VS Code terminal.
-
-### One installation, many projects
-
-Install globally once:
-
-```bash
-npm install -g indraq_cli
-```
-
-Then use it anywhere:
-
-```text
-C:\Projects\accounting-service> indraq deploy:dev
-C:\Projects\mobile-app>        indraq build mobile:dev
-C:\Projects\another-app>      indraq configure
-```
-
-Each project keeps its own `.indraq/` configuration. The CLI itself is not installed separately in every project.
-
----
-
-## Explain it like I am new
-
-Imagine you built a school project.
-
-You have the project files on your computer. You want another computer called **Jenkins** to build or deploy them for you.
-
-Without IndraQ CLI, you may need to:
-
-1. remember many commands;
-2. open Jenkins in the browser;
-3. choose the correct job;
-4. fill many parameters;
-5. copy environment variables;
-6. wait for the build;
-7. keep refreshing logs.
-
-With IndraQ CLI, you configure the project once and later type one command.
-
-For a mobile app:
-
-```text
-Your VS Code project
-        │
-        │  indraq build mobile:prod
-        ▼
-IndraQ CLI
-        │
-        ├── checks you are at the project root
-        ├── validates Expo / React Native
-        ├── reads the saved Production settings
-        ├── reads root .env automatically
-        ├── creates a clean source snapshot
-        ├── sends it to Production Jenkins
-        └── shows Jenkins logs here
-                │
-                ▼
-       Production Jenkins
-                │
-                ├── installs dependencies
-                ├── prepares Android
-                ├── builds APK/AAB
-                └── publishes the artifact
-```
-
-You do **not** need to give Jenkins a Git URL, Git branch, app subdirectory, or pasted `.env` content for this mobile workflow.
-
----
-
-## What changed in v1.5.8?
-
-v1.5.8 keeps the working Jenkins, mobile-build, GHCR, and complete-help behavior from v1.5.7 and tightens project configuration sharing.
-
-### Git-safe project configuration in v1.5.8
-
-- IndraQ no longer adds `.indraq/` to the project `.gitignore`.
-- Only `.indraq/jenkins.local.json` is added at the project root as the machine-local Jenkins binding.
-- Existing `.gitignore` files are reused rather than replaced.
-- Existing exact ignore entries are detected, so repeated configuration does not duplicate them.
-- `.indraq/jenkins.json`, `.indraq/docker.json`, and `.indraq/mobile.json` remain available to Git and can be shared with another developer.
-- Jenkins username/token/password remain outside the repo under `~/.indraq/jenkins/...`; another developer receives server/config metadata but not your login credential.
-- Known old IndraQ-generated ignore-all rules are migrated carefully; unrelated user-authored Git rules are preserved.
-
-
-### Jenkins-console-quality logs and server Gradle reuse in v1.5.8
-
-- The terminal log streamer now reads Jenkins **`logText/progressiveHtml`**, the same progressive endpoint used by the classic Jenkins web console. Jenkins therefore removes/renders hidden `ConsoleNote` annotations before the CLI displays the text, so internal `ha:////...` payloads no longer pollute VS Code output.
-- HTML markup is converted back to plain terminal text while preserving usernames, timestamps, Pipeline lines, errors, and normal line spacing. `progressiveText` remains only as a compatibility fallback with explicit ConsoleNote filtering.
-- Failed mobile builds now end with a short **Key Jenkins error lines** summary plus the direct Jenkins build URL.
-- The mobile Jenkinsfile still normalizes Windows CRLF in `android/gradlew`, but v1.5.8 also restores the Jenkins server's shared Gradle cache at `$HOME/.gradle` instead of creating an empty per-project Gradle cache.
-- Gradle execution prefers the exact cached project-wrapper distribution. If no exact wrapper distribution is cached, an installed Jenkins-server Gradle from the same major version can be reused. The project wrapper remains the final fallback.
-- If a wrapper download is genuinely necessary, the temporary Jenkins copy of `gradle-wrapper.properties` gets `networkTimeout=120000` (120 seconds) instead of failing at Gradle's short default timeout.
-- `FULL_RESET` no longer deletes Jenkins' shared Gradle cache. It clears project-local npm/Expo caches and generated Android state only.
-- Jenkins queue updates are printed as normal lines instead of carriage-return cursor updates.
-
-### Jenkins/Git behavior hardened in v1.5.x
-
-- Mobile always targets the Jenkins job **`Mobile app Cli build`**. The job name is no longer configurable per project.
-- The mobile Jenkinsfile no longer contains the Groovy-invalid escaped-dot expression that caused `unexpected char: '\'` during pipeline compilation.
-- Mobile Jenkins HTTP uploads now preserve the Jenkins web-session cookie together with the CSRF crumb, fixing HTTP 403 responses when Jenkins is configured with username/password authentication. API-token authentication remains supported.
-- Mobile build output now says explicitly that `.env` is excluded only from the source archive and is uploaded separately to Jenkins.
-- `.indraq/mobile.json`, `.indraq/docker.json`, and `.indraq/jenkins.json` are intended to be committed to Git.
-- `.indraq/jenkins.local.json`, Jenkins username/token/password, `.env`, and `jenkins-cli.jar` are machine-local and never meant to be committed.
-- Docker CLI deployments now start Jenkins with `ACTION=DEPLOY`, `IMAGE_TAG`, optional `IMAGE_DIGEST`, and `DEPLOYMENT_SOURCE=INDRAQ_CLI`.
-- Expo versions are synchronized to `app.json` when possible. React Native CLI versions are synchronized to `android/app/build.gradle` / `build.gradle.kts` when those values are simple literals. Jenkins still enforces the requested version during the actual Android build.
-
-### App name is now part of Mobile configuration
-
-Every mobile project stores an app name. IndraQ uses this name when it creates the final APK/AAB filename.
-
-### Android Version and versionCode
-
-New projects start with:
-
-```text
-Version:     0.1
-versionCode: 1
-```
-
-Both counters auto-increment **after a successful Jenkins build** by default. Failed or cancelled builds do not consume a version.
-
-The version rule is simple: the final numeric part increases by one.
-
-```text
-0.1   → 0.2
-0.9   → 0.10
-1.2.3 → 1.2.4
-```
-
-`versionCode` increments by one:
-
-```text
-1 → 2 → 3 → 4
-```
-
-You can change either value or turn either auto-increment switch off from:
-
-```text
-indraq configure
-  → Mobile App
-  → Version & versionCode
-```
-
-When auto-increment is disabled, IndraQ does not block the build. It prints a soft warning reminding you that the same value will be reused.
-
-### Predictable Android artifact names
-
-APK/AAB files produced by the IndraQ mobile Jenkinsfile now follow:
-
-```text
-<AppName>_<Version>_<versionCode>_<YYYY-MM-DD>_<HHmm>.<apk|aab>
-```
-
-Example:
-
-```text
-Nefazo_0.1_1_2026-08-30_2051.apk
-```
-
-The date/time is always generated in **Asia/Kolkata (IST)**. Time contains hours and minutes only.
-
-### Mobile still always uses Production Jenkins
-
-The Jenkins rule remains intentionally simple:
-
-```text
-indraq build mobile:dev     → Production Jenkins
-indraq build mobile:staging → Production Jenkins
-indraq build mobile:prod    → Production Jenkins
-```
-
-Docker continues to support both Development and Production Jenkins:
-
-```text
-indraq deploy:dev  → Development Jenkins
-indraq deploy:prod → Production Jenkins
-```
-
-### Existing v1.4 mobile projects migrate automatically
-
-Existing `.indraq/mobile.json` files are upgraded automatically. Project type, app name, version/versionCode, auto-increment settings, and environment defaults are preserved when present. Older configurable mobile Jenkins job names are removed because mobile now always targets **`Mobile app Cli build`**.
-
----
-
-## Requirements
-
-### Developer computer
-
-| Requirement | Why | Check |
-|---|---|---|
-| **Node.js 22+** | Runs IndraQ CLI | `node --version` |
-| **npm** | Installs / updates the CLI | `npm --version` |
-| **Git** | GitHub identity/org discovery and optional source revision metadata | `git --version` |
-| **Docker GHCR login** | Registry authentication used for image push | `docker login ghcr.io` (one-time, when needed) |
-| **Docker** | Docker deployment module | `docker --version` |
-| **Java** | Runs Jenkins CLI | `java -version` |
-| **tar** | Packages the local mobile source snapshot | `tar --version` |
-| **Jenkins account** | Starts Jenkins jobs | Jenkins username + API token |
-
-> [!TIP]
-> Node.js **24** is recommended for IndraQ developer machines, but v1.5.8 supports Node.js **22 and newer**.
-
-### Jenkins mobile build machine
-
-The provided mobile Jenkinsfile expects the Jenkins agent to have:
-
-- Java;
-- Node.js and npm;
-- Android SDK;
-- `sdkmanager`;
-- Bash;
-- `tar` / `sha256sum`;
-- Jenkins **File Parameter** plugin;
-- writable `/opt/mobile-builder`;
-- Android SDK at `/opt/android-sdk` unless you edit the Jenkinsfile;
-- the Jenkins account should have a writable `$HOME/.gradle` cache (normally `/var/jenkins_home/.gradle`);
-- optionally, a system `gradle` executable may be installed. IndraQ uses it only when its major version matches the project wrapper.
-
----
-
-## Install Java 21
-
-Java is required because Jenkins distributes its CLI as `jenkins-cli.jar`.
-
-### Windows
-
-Open PowerShell:
-
-```powershell
-winget install EclipseAdoptium.Temurin.21.JDK
-```
-
-Then **fully close and reopen VS Code**.
-
-Verify:
-
-```powershell
-java -version
-where.exe java
-```
-
-### Ubuntu / Debian
-
-```bash
-sudo apt update
-sudo apt install -y openjdk-21-jdk
-java -version
-```
-
-### macOS
-
-Using Homebrew:
-
-```bash
-brew install --cask temurin@21
-java -version
-```
-
-> [!IMPORTANT]
-> If `java -version` fails, fix Java before running Jenkins configuration.
-
----
-
-## Install IndraQ CLI
-
-Install globally:
-
-```bash
-npm install -g indraq_cli
-```
-
-Verify:
-
-```bash
-indraq --version
-```
-
-Expected for this release:
-
-```text
-1.5.3
-```
-
-Update later:
-
-```bash
-npm install -g indraq_cli@latest
-```
-
-Uninstall:
-
-```bash
-npm uninstall -g indraq_cli
-```
-
----
-
-## Run the doctor
-
-Before debugging a mysterious machine problem, run:
-
-```bash
-indraq doctor
-```
-
-It checks:
-
-- Node.js version;
-- Java;
-- Git;
-- `tar`;
-- how the `indraq` command resolves on your machine.
-
-This is especially useful on Windows if another file named `IndraQ` is shadowing the npm executable.
-
----
-
-## Configuration home
-
-Run from the project you want to configure:
-
-```bash
-indraq configure
-```
-
-You will see:
-
-```text
-IndraQ CLI Configuration
-
-? What do you want to configure?
-> Jenkins
-  Docker / GHCR
-  Mobile App
-  ------------------------------
-  Review current project configuration
-  Exit
-```
-
-The rule is simple:
-
-> **Persistent settings are changed with `indraq configure`. One-time build changes are supplied as flags.**
-
----
-
-## Configure Jenkins
-
-Choose:
-
-```text
-Configure
-  └── Jenkins
-```
-
-The Jenkins menu is:
-
-```text
-> Development
-  Production — used by all mobile builds
-  ------------------
-  Review Jenkins connections
-  Back
-```
-
-There are only **two Jenkins infrastructure environments** in a project.
-
-| Jenkins connection | Used by |
-|---|---|
-| **Development** | `indraq deploy:dev` |
-| **Production** | `indraq deploy:prod` **and every mobile build** |
-
-This means:
-
-```text
-Mobile Development  ┐
-Mobile Staging      ├──→ Production Jenkins
-Mobile Production  ┘
-```
-
-A command such as `indraq build mobile:dev` means **build the app using its Development mobile settings on Production Jenkins**. It does not mean “use Development Jenkins.”
-
-For each Jenkins connection, IndraQ asks for:
-
-```text
-Jenkins URL/domain
-Jenkins username
-Jenkins API token or password
-```
-
-It then:
-
-1. downloads `<jenkins>/jnlpJars/jenkins-cli.jar`;
-2. stores the secret outside the project;
-3. runs Jenkins `who-am-i`;
-4. rejects wrong credentials immediately;
-5. saves the verified non-secret connection metadata in `.indraq/jenkins.json`.
-
-Configure Jenkins once per project. Normal Docker/mobile build commands reuse the saved connection and credentials.
-
-Use a Jenkins API token instead of an account password whenever possible.
-
----
-
-## Configure Docker / GHCR
-
-Choose:
-
-```text
-Configure
-  └── Docker / GHCR
-```
-
-The menu lets you independently change:
-
-```text
-Development
-Production
-GitHub / GHCR destination
-Review
-Back
-```
-
-Development and Production each store:
-
-- image name;
-- Dockerfile path.
-
-GitHub/GHCR stores:
-
-- personal account or organization;
-- selected GHCR owner.
-
-The Docker deployment Jenkins connection is configured separately under **Jenkins**.
-
-When `indraq deploy:dev` or `indraq deploy:prod` has built and pushed the image, the CLI starts the Jenkins job whose name matches the image repository name (for example `ghcr.io/indraq-innovations/immortality-accounting-service` maps to Jenkins job `immortality-accounting-service`) and supplies exactly:
-
-```text
-ACTION=DEPLOY
-IMAGE_TAG=<primary pushed tag>
-IMAGE_DIGEST=<sha256 digest, when available>
-DEPLOYMENT_SOURCE=INDRAQ_CLI
-```
-
-This is the CLI path; the Jenkinsfile may still keep its Generic Webhook Trigger for other deployment sources if you want it.
-
----
-
-## Configure Mobile App
-
-Choose:
-
-```text
-Configure
-  └── Mobile App
-```
-
-The menu is:
-
-```text
-> Project settings
-  Version & versionCode
-  Development
-  Staging
-  Production
-  ------------------
-  Review Mobile App configuration
-  Back
-```
-
-### Project settings
-
-IndraQ asks for:
-
-```text
-Mobile app name
-Project type
-  - Expo
-  - React Native CLI
-```
-
-The app name is saved per project and is used in the final APK/AAB filename.
-
-The mobile Jenkins job is **not configurable**. Every mobile build targets exactly:
-
-```text
-Mobile app Cli build
-```
-
-All mobile Development, Staging, and Production builds use the project's **Production Jenkins** connection. The CLI verifies that `Mobile app Cli build` exists before uploading source.
-
-### Version & versionCode settings
-
-Choose:
-
-```text
-Mobile App
-  → Version & versionCode
-```
-
-You can configure these independently:
-
-```text
-Version
-versionCode
-Auto-increment Version
-Auto-increment versionCode
-```
-
-Defaults:
-
-```text
-Version:                    0.1
-versionCode:                1
-Auto-increment Version:     ON
-Auto-increment versionCode: ON
-```
-
-Auto-increment happens only after Jenkins reports `SUCCESS`. A failed build leaves both saved values unchanged.
-
-If you manually change Version/versionCode while a Jenkins build is still running, IndraQ will not overwrite your newer values when that build finishes.
-
-### Version values survive Git clones
-
-`.indraq/mobile.json` is project configuration and should be committed. That means another developer who clones/pulls the repository receives the same next Version/versionCode.
-
-IndraQ also synchronizes the configured values into the Android-facing project file when it can do so safely:
-
-```text
-Expo             → app.json → expo.version + expo.android.versionCode
-React Native CLI → android/app/build.gradle(.kts) → versionName + versionCode
-```
-
-Before a remote build, Jenkins applies the requested values again after Expo prebuild / before Gradle, so the artifact uses the values shown in the CLI build plan.
-
-After a successful build with auto-increment enabled, commit the changed `.indraq/mobile.json` and synced app-version file(s). Failed builds do not increment the shared values.
-
-### Environment settings
-
-Each mobile environment stores:
-
-- default build output;
-- default build profile.
-
-Profiles:
-
-| Profile | Meaning |
-|---|---|
-| **FAST** | Fresh source snapshot; reuse project npm cache plus the Jenkins server shared Gradle cache |
-| **CLEAN** | Clean generated project build state before building |
-| **FULL_RESET** | Clear project npm/Expo/generated Android state while preserving the Jenkins server shared Gradle cache |
-
-After saving one environment you return to the Mobile App menu, so you can configure another environment without rerunning the command.
-
----
-
-## Docker deployment
-
-Development:
-
-```bash
-indraq deploy:dev
-```
-
-Alias:
-
-```bash
-indraq deploy:development
-```
-
-Production:
-
-```bash
-indraq deploy:prod
-```
-
-Alias:
-
-```bash
-indraq deploy:production
-```
-
-Docker deployment still follows this flow:
-
-```text
-validate Docker / GitHub / Java / Jenkins
-        ↓
-build Docker image
-        ↓
-push image to GHCR
-        ↓
-find Jenkins job with same name as image
-        ↓
-run Jenkins pipeline
-        ↓
-stream logs into terminal
-```
-
----
-
-## Mobile build overview
-
-> [!IMPORTANT]
-> **Every mobile build runs on the saved Production Jenkins connection.** `mobile:dev`, `mobile:staging`, and `mobile:prod` are mobile application environments, not Jenkins environments.
-
-
-The mobile module deliberately does **not** ask for:
-
-- Git repository URL;
-- Git branch;
-- app subdirectory;
-- pasted env text;
-- "save env" checkbox.
-
-Why? Because the CLI is already running inside the developer's project.
-
-### Root directory rule
-
-Run mobile builds from the directory containing the mobile app's `package.json`.
-
-Correct:
-
-```text
-my-mobile-app/
-├── package.json       ← run command here
-├── .env
-├── src/
-├── android/           ← React Native CLI
-└── ...
-```
-
-Wrong:
-
-```text
-my-mobile-app/android/ ← do not run it here
-```
-
-IndraQ does not silently search parent folders. If `package.json` is not in the current directory, the build stops.
-
----
-
-## Mobile build matrix
-
-Invalid combinations are blocked both by the CLI **and** by the Jenkinsfile.
-
-| Project type | Environment | Allowed output |
-|---|---|---|
-| Expo | Development | **Development Client only** |
-| Expo | Staging | **Release APK** or **Release AAB** |
-| Expo | Production | **Release APK** or **Release AAB** |
-| React Native CLI | Development | **Debug APK only** |
-| React Native CLI | Staging | **Release APK** or **Release AAB** |
-| React Native CLI | Production | **Release APK** or **Release AAB** |
-
-The CLI does not show impossible choices during configuration.
-
-For example, Expo Development automatically becomes:
-
-```text
-Build output: Development Client
-```
-
-There is no pointless APK/AAB menu for that combination.
-
----
-
-## Mobile build commands
-
-Development:
-
-```bash
-indraq build mobile:dev
-```
-
-Alias:
-
-```bash
-indraq build mobile:development
-```
-
-Staging:
-
-```bash
-indraq build mobile:staging
-```
-
-Production:
-
-```bash
-indraq build mobile:prod
-```
-
-Alias:
-
-```bash
-indraq build mobile:production
-```
-
-### First build
-
-If required mobile configuration is missing, the CLI asks only for the missing settings and saves them.
-
-### Later builds
-
-Once configured:
-
-```bash
-indraq build mobile:staging
-```
-
-uses the saved Staging output/profile without asking the same questions again.
-
-Before uploading anything, IndraQ prints a build plan and asks for confirmation.
-
----
-
-## Mobile build flags
-
-Flags override saved defaults **for one build only**.
-
-They do not permanently change `mobile.json`.
-
-### Output override
-
-```bash
-indraq build mobile:staging --output aab
-```
-
-Accepted output aliases:
-
-```text
-dev-client / development-client
-debug / debug-apk
-apk / release-apk
-aab / release-aab
-```
-
-The matrix is still enforced. For example, this is rejected:
-
-```bash
-indraq build mobile:dev --output aab
-```
-
-for an Expo Development project.
-
-### Profile override
-
-```bash
-indraq build mobile:prod --profile clean
-```
-
-Available profiles:
-
-```text
-fast
-clean
-full-reset
-```
-
-### Verbose Gradle logs
-
-```bash
-indraq build mobile:prod --verbose
-```
-
-### Dry run
-
-Validate everything and print the plan without uploading source or starting Jenkins:
-
-```bash
-indraq build mobile:staging --dry-run
-```
-
-### Skip final confirmation
-
-Useful for a developer who already knows exactly what will run:
-
-```bash
-indraq build mobile:prod --yes
-```
-
-Example combination:
-
-```bash
-indraq build mobile:prod --output aab --profile clean --verbose --yes
-```
-
----
-
-## Android versioning and artifact names
-
-IndraQ v1.5.8 currently manages **Android** versioning only. iOS version/build-number management is intentionally out of scope for now.
-
-### What value does a build use?
-
-A build uses the values currently stored in `.indraq/mobile.json`.
-
-Example before the build:
-
-```text
-Version:     0.1
-versionCode: 1
-```
-
-The Jenkins build receives exactly `0.1` and `1`, applies them to the generated/native Android Gradle project, and produces the APK/AAB with those values.
-
-Only after Jenkins finishes successfully are enabled counters advanced for the next build.
-
-### Auto-increment examples
-
-With both switches ON:
-
-```text
-Build 1 uses: 0.1 / 1
-Success
-Next saved:   0.2 / 2
-
-Build 2 uses: 0.2 / 2
-Success
-Next saved:   0.3 / 3
-```
-
-If `Auto-increment Version` is OFF:
-
-```text
-Version stays 0.1
-versionCode may still move 1 → 2 → 3
-```
-
-If `Auto-increment versionCode` is OFF, IndraQ prints a warning before every mobile build because Android release stores normally expect a higher versionCode for upgrades.
-
-### Artifact filename
-
-The Jenkins mobile pipeline renames the primary APK/AAB to:
-
-```text
-<AppName>_<Version>_<versionCode>_<YYYY-MM-DD>_<HHmm>.<extension>
-```
-
-Example:
-
-```text
-Nefazo_User_1.4_27_2026-08-30_2051.aab
-```
-
-Rules:
-
-- timezone: `Asia/Kolkata` (IST);
-- date: `YYYY-MM-DD`;
-- time: 24-hour `HHmm`;
-- seconds are intentionally omitted;
-- unsafe filename characters in the configured app name are replaced with `_`.
-
----
-
-## How local source reaches Jenkins
-
-This is the mobile source-upload design.
-
-The old mobile Jenkins pipeline cloned a Git URL. The new flow builds the files that are **actually on the developer's computer right now**.
-
-```mermaid
-flowchart TD
-    A[Developer runs indraq build mobile:prod] --> B[Verify current directory is project root]
-    B --> C[Validate Expo / React Native project]
-    C --> D[Create clean temporary source snapshot]
-    D --> E[Calculate SHA-256]
-    E --> F[Upload snapshot to Jenkins]
-    F --> G[Jenkins verifies SHA-256]
-    G --> H[Extract source]
-    H --> I[Build Android]
-    I --> J[Archive APK / AAB]
-    J --> K[Stream logs + artifact URL to terminal]
-```
-
-### What is excluded from the source snapshot?
-
-IndraQ excludes common generated/sensitive files such as:
-
-```text
-.git/
-.indraq/
-node_modules/
-coverage/
-dist/
-build/
-.vscode/
-.idea/
-.env
-.env.*
-*.apk
-*.aab
-android/.gradle/
-android/app/build/
-ios/Pods/
-```
-
-The source archive is created in the system temporary directory, uploaded, then deleted locally.
-
-### Why SHA-256?
-
-The CLI calculates a SHA-256 hash before upload. Jenkins calculates it again before extraction.
-
-If they do not match, the build stops.
-
----
-
-## Root .env behavior
-
-You no longer paste `.env` into Jenkins.
-
-For build outputs that need an environment file, IndraQ automatically uses:
-
-```text
-<mobile-project-root>/.env
-```
-
-The `.env` file is:
-
-1. **not included** inside the source archive;
-2. uploaded separately as a Jenkins file parameter;
-3. copied into the temporary build source;
-4. never printed in logs;
-5. removed from the Jenkins workspace in `post { always { ... } }`.
-
-> [!CAUTION]
-> Jenkins file parameters can remain in Jenkins build data according to your controller/plugin retention behavior. The workspace copy is deleted, but highly sensitive production secrets should still follow your normal Jenkins retention and secret-management policy.
-
-If a required `.env` is missing, the build stops before source upload.
-
-Expo Development Client does not require `.env`, but if a root `.env` exists IndraQ still supplies it automatically.
-
----
-
-## Mobile Jenkins setup
-
-The mobile source-upload workflow requires the Jenkins **File Parameter** plugin.
-
-### Step 1 — install the plugin
-
-In Jenkins:
-
-```text
-Manage Jenkins
-  → Plugins
-  → Available plugins
-  → search: File Parameter
-  → install "File Parameter"
-```
-
-Plugin ID:
-
-```text
-file-parameters
-```
-
-### Step 2 — use the IndraQ v1.5 mobile Jenkinsfile
-
-This repository includes:
-
-```text
-templates/jenkins/Jenkinsfile-Mobile-App
-```
-
-Use that pipeline for the Jenkins mobile build job.
-
-It declares two large file parameters:
-
-```text
-SOURCE_BUNDLE
-ENV_FILE
-```
-
-plus normal metadata/build parameters supplied automatically by the CLI.
-
-> [!IMPORTANT]
-> If you replace an existing Pipeline Jenkinsfile with this one, run/save the job once if Jenkins needs an initial run to register the new parameter definitions. After that the CLI uses `buildWithParameters` automatically.
-
-### Step 3 — Jenkins agent paths
-
-Default paths in the template:
-
-```text
-ANDROID_HOME=/opt/android-sdk
-ANDROID_SDK_ROOT=/opt/android-sdk
-MOBILE_BUILDER_HOME=/opt/mobile-builder
-```
-
-Change the Jenkinsfile if your Jenkins agent uses different paths.
-
-### Step 4 — configure the CLI
-
-```bash
-indraq configure
-```
-
-Configure the Jenkins connection once:
-
-```text
-Jenkins
-  → Production
-```
-
-Enter the Production Jenkins URL, username, and API token. **All mobile Development, Staging, and Production builds use this Production Jenkins connection.**
-
-Then configure the mobile project:
-
-```text
-Mobile App
-  → Project settings
-```
-
-Set the app name and project type. On Jenkins, create/rename the mobile Pipeline job to exactly:
-
-```text
-Mobile app Cli build
-```
-
-The CLI checks this exact job on Production Jenkins before every mobile build.
-
-### Live logs
-
-Mobile source upload is triggered through Jenkins HTTP `buildWithParameters`, then IndraQ follows the queue item, discovers the build number, and streams Jenkins **`logText/progressiveHtml`** into VS Code. This is the same progressive console endpoint used by the classic Jenkins browser console, so Jenkins' hidden `ConsoleNote` metadata is rendered/removed before IndraQ converts the remaining HTML to readable terminal text.
-
-If Jenkins fails, the CLI exits with failure, prints a short **Key Jenkins error lines** summary, and prints the direct Jenkins build URL. The complete live output remains above it.
-
----
-
-## Configuration and secret storage
-
-Project-local configuration:
-
-```text
-<project>/.indraq/
-├── jenkins.json          # shared — commit
-├── docker.json           # shared — commit
-├── mobile.json           # shared — commit
-├── jenkins.local.json    # machine-local — ignored
-└── .gitignore
-```
-
-The generated `.indraq/.gitignore` ignores **only machine-local files** such as `jenkins.local.json`. Shared project configuration is intentionally visible to Git.
-
-> [!IMPORTANT]
-> v1.5.8 never adds `.indraq/` as an ignore-all rule. If a project already has a root `.gitignore`, IndraQ reuses that same file and adds `.indraq/jenkins.local.json` only when that exact rule is missing. Re-running `indraq configure` does not duplicate the entry. Known ignore-all rules created by older IndraQ versions are migrated while unrelated user ignore rules are preserved.
-
-### `jenkins.json`
-
-Stores non-secret Jenkins metadata:
-
-```text
-Development Jenkins connection
-Production Jenkins connection
-```
-
-Usage is fixed and easy to remember:
-
-```text
-Docker DEV  → Development Jenkins
-Docker PROD → Production Jenkins
-Mobile DEV / STAGING / PROD → Production Jenkins
-```
-
-It stores Jenkins URL/transport only. It does **not** store Jenkins username, token, or password.
-
-The local `jenkins.local.json` contains only the machine's credential binding ID and is ignored by Git. The actual username + API token/password remain under the user's home directory.
-
-### `docker.json`
-
-Stores:
-
-```text
-GitHub / GHCR owner
-Development image + Dockerfile
-Production image + Dockerfile
-```
-
-### `mobile.json`
-
-Stores:
-
-```text
-stable project ID
-app name
-project type
-Android Version + versionCode
-auto-increment switches for Version + versionCode
-Development output/profile
-Staging output/profile
-Production output/profile
-```
-
-It does **not** store `.env` values.
-
-### Jenkins secret location
-
-Jenkins login credentials live outside the repository and never survive a Git clone:
-
-```text
-~/.indraq/
-└── jenkins/
-    └── <server-account-id>/
-        ├── jenkins-cli.jar
-        └── auth
-```
-
-Never commit this directory.
-
----
-
-## Upgrade from v1.4 / v1.5
-
-Update the public package:
-
-```bash
-npm install -g indraq_cli@latest
-```
-
-Verify:
-
-```bash
-indraq --version
-```
-
-Expected for this release:
-
-```text
-1.5.3
-```
-
-v1.5.8 automatically migrates older `.indraq/mobile.json` and Jenkins config layouts. Existing mobile environment/version settings are preserved. Older Jenkins username/server binding fields are split so only non-secret server metadata remains in tracked `jenkins.json`; the current machine binding is written to ignored `jenkins.local.json`.
-
-For projects coming from pre-versioning releases, Android version settings initialize as:
-
-```text
-Version:     0.1
-versionCode: 1
-Auto Version: ON
-Auto versionCode: ON
-```
-
-Because v1.5 did not store the configured app name, open:
-
-```text
-indraq configure
-  → Mobile App
-  → Project settings
-```
-
-and confirm the app name once.
-
-Docker/GHCR and Jenkins configuration remain compatible.
-
----
-
-## Command reference
-
-The CLI now has a complete built-in help system, so developers do not need to open this README just to remember syntax.
-
-```bash
-indraq --help
-indraq help
-indraq help configure
-indraq help docker
-indraq help mobile
-indraq help doctor
-```
-
-### Core commands
-
-| Command | Purpose |
-|---|---|
-| `indraq --version` | Show installed CLI version |
-| `indraq --help` | Show the complete command catalog, aliases, flags, mappings and examples |
-| `indraq help` | Same complete command catalog |
-| `indraq help <topic>` | Focused help for `configure`, `docker`, `mobile`, or `doctor` |
-| `indraq doctor` | Diagnose runtime / PATH prerequisites |
-| `indraq configure` | Open configuration home |
-
-### Docker commands
-
-| Command | Purpose |
-|---|---|
-| `indraq deploy:dev` | Docker Development build/push/deploy |
-| `indraq deploy:development` | Alias of `deploy:dev` |
-| `indraq deploy:prod` | Docker Production build/push/deploy |
-| `indraq deploy:production` | Alias of `deploy:prod` |
-| `indraq deploy build --env dev` | Long-form Development command |
-| `indraq deploy build --env development` | Long-form Development alias |
-| `indraq deploy build --env prod` | Long-form Production command |
-| `indraq deploy build --env production` | Long-form Production alias |
-| `indraq deploy configure` | Open configuration home |
-| `indraq deploy:configure` | Alias for `indraq configure` |
-
-### Mobile commands
-
-| Command | Purpose |
-|---|---|
-| `indraq build mobile:dev` | Mobile Development build |
-| `indraq build mobile:development` | Alias of `mobile:dev` |
-| `indraq build mobile:staging` | Mobile Staging build |
-| `indraq build mobile:prod` | Mobile Production build |
-| `indraq build mobile:production` | Alias of `mobile:prod` |
-
-Mobile flags:
-
-```text
---output <dev-client|development-client|client|debug|debug-apk|apk|release-apk|aab|release-aab>
---profile <fast|clean|full-reset>
---verbose
---dry-run
--y, --yes
-```
-
-### Jenkins routing reminder
-
-```text
-Docker Development → Development Jenkins
-Docker Production  → Production Jenkins
-Mobile Development → Production Jenkins
-Mobile Staging     → Production Jenkins
-Mobile Production  → Production Jenkins
-```
-
----
-
-## Troubleshooting
-
-### `Java is required for Jenkins CLI`
-
-Check:
-
-```bash
-java -version
-```
-
-Install Java 21 and reopen VS Code.
-
----
-
-### `tar is required`
-
-Check:
-
-```bash
-tar --version
-```
-
-Modern Windows 10/11, macOS, and most Linux distributions already provide `tar`.
-
-Ubuntu/Debian:
-
-```bash
-sudo apt install -y tar
-```
-
----
-
-### `You are not in a mobile project root`
-
-Run:
-
-```bash
-ls
-```
-
-or on PowerShell:
-
-```powershell
-Get-ChildItem
-```
-
-The current directory must contain:
-
-```text
-package.json
-```
-
-For React Native CLI it must also contain:
-
-```text
-android/
-android/gradlew
-```
-
----
-
-### `expo-dev-client is not installed`
-
-For Expo Development Client:
-
-```bash
-npx expo install expo-dev-client
-```
-
-Then retry.
-
----
-
-### `.env was not found`
-
-Create:
-
-```text
-<project-root>/.env
-```
-
-Do not paste it into Jenkins.
-
----
-
-### Jenkins HTTP 400 / file parameter error
-
-Make sure:
-
-1. Jenkins **File Parameter** plugin is installed;
-2. the job uses `templates/jenkins/Jenkinsfile-Mobile-App` from v1.5.8;
-3. Jenkins has registered the parameters;
-4. the Jenkins job is named exactly `Mobile app Cli build`.
-
----
-
-### Jenkins job not found
-
-For mobile, the job name is fixed. In Jenkins, create or rename the Pipeline to exactly:
-
-```text
-Mobile app Cli build
-```
-
-Then make sure `indraq configure → Jenkins → Production` points at that Jenkins controller and that this computer has valid Jenkins credentials.
-
-For Docker, the Jenkins job name must match the configured image name.
-
----
-
-### `indraq` opens another Windows file/application
-
-Run:
-
-```powershell
-where.exe indraq
-indraq doctor
-```
-
-The npm launcher should be the first `indraq` result.
-
----
-
-### npm shows `EEXIST` for `indraq.ps1`
-
-This usually means an old `npm link` launcher is still present.
-
-Remove the old global development link/package, then reinstall:
-
-```powershell
-npm unlink -g indraq_cli
-npm uninstall -g indraq_cli
-npm install -g indraq_cli
-```
-
----
-
-
-### `./gradlew: cannot execute: required file not found`
-
-This normally means the mobile source snapshot came from Windows and `android/gradlew` contains CRLF line endings. IndraQ normalizes the wrapper automatically on Jenkins before the build and invokes it through Bash.
-
-The Jenkins server provides the Android toolchain:
-
-```text
-Java                 → Jenkins server
-ANDROID_HOME          → /opt/android-sdk
-Android NDKs          → /opt/android-sdk/ndk/*
-Shared Gradle cache   → $HOME/.gradle (normally /var/jenkins_home/.gradle)
-Preferred Gradle      → exact cached wrapper distribution
-Server fallback       → installed Gradle when it is the same major version
-Final fallback        → project wrapper with 120-second download timeout
-```
-
-This restores the shared Gradle-cache behavior used by the earlier Git-checkout mobile pipeline. `FULL_RESET` deliberately preserves the server's `$HOME/.gradle` cache.
-
-### Gradle wrapper tries to download and times out
-
-v1.5.8 first checks the Jenkins server's shared wrapper cache. If the requested distribution is already cached, the wrapper uses it without internet access. If there is no exact cached wrapper but Jenkins has a system Gradle from the same major version, IndraQ reuses the server Gradle. Only when neither option exists does the project wrapper attempt a download, with `networkTimeout=120000` applied to the temporary Jenkins copy of `gradle-wrapper.properties`.
-
-If the Jenkins machine has neither a compatible installed Gradle nor the requested wrapper cached and it has no outbound access to Gradle distributions, install/cache the required Gradle version on that Jenkins machine once.
-
-### Jenkins logs contain `ha:////...`, look diagonal, or are unreadable in VS Code
-
-The `ha:////...` strings are Jenkins `ConsoleNote` annotations embedded in raw `progressiveText`. The Jenkins browser UI renders/hides those annotations. v1.5.8 now consumes Jenkins `logText/progressiveHtml`—the same progressive endpoint used by the classic web console—and converts the rendered output back to plain terminal text.
-
-The CLI also normalizes line endings and strips terminal control sequences. Upgrade to v1.5.8 or newer if you see raw `ha:////...` payloads or staircase/right-shifted output.
-
----
-
-## Frequently asked questions
-
-### Do I install IndraQ CLI in every project?
-
-No. Install globally once per computer:
-
-```bash
-npm install -g indraq_cli
-```
-
-Each project only gets its own `.indraq/` configuration.
-
-### Does the mobile build require me to push my latest code to Git first?
-
-No. The mobile builder snapshots the files currently on disk. Uncommitted changes are included.
-
-### Does Jenkins need access to my GitHub repository for mobile builds?
-
-Not for the v1.5 source-upload pipeline. The CLI sends the source snapshot directly.
-
-### Does Docker deployment still use GitHub/GHCR?
-
-Yes. Docker builds continue to push images to GHCR and then run the configured Jenkins deployment job.
-
-### Can Staging and Production have different mobile outputs?
-
-Yes. Example:
-
-```text
-Staging:    Release APK / FAST
-Production: Release AAB / CLEAN
-```
-
-### Can I build an APK once without changing my saved Production AAB default?
-
-Yes:
-
-```bash
-indraq build mobile:prod --output apk
-```
-
-The saved default remains unchanged.
-
-### Does IndraQ save `.env`?
-
-No. It reads the root `.env` at build time and uploads it separately when required.
-
-### When does Version/versionCode increment?
-
-After a **successful** Jenkins mobile build. The build uses the currently saved values first, then enabled counters advance for the next build. Failed/cancelled builds do not consume values.
-
-### Can I turn auto-increment off?
-
-Yes:
-
-```text
-indraq configure
-  → Mobile App
-  → Version & versionCode
-```
-
-Version and versionCode have separate switches. When either is OFF, the build continues but IndraQ prints a reminder warning.
-
-### What timezone is used in APK/AAB filenames?
-
-Always `Asia/Kolkata` (IST), using `YYYY-MM-DD_HHmm`.
-
-### Which Jenkins does Mobile use?
-
-**Production Jenkins only.** This is intentional.
-
-```text
-mobile:dev     → Production Jenkins
-mobile:staging → Production Jenkins
-mobile:prod    → Production Jenkins
-```
-
-The mobile Development/Staging/Production selection controls the app build environment and allowed output. It does not select a Jenkins controller.
-
-### Why can Docker use Development and Production Jenkins?
-
-Docker deployments represent infrastructure environments. `indraq deploy:dev` can deploy through Development Jenkins while `indraq deploy:prod` can use Production Jenkins. Mobile builds are build jobs rather than Docker environment deployments, so they always use the single Production Jenkins path.
-
----
-
-## Project architecture
-
-```text
-src/
-├── cli/
-│   ├── create-program.ts
-│   └── doctor.command.ts
-│
-├── modules/
-│   ├── configure/
-│   │   └── configure.command.ts
-│   │
-│   ├── deploy/
-│   │   ├── commands/
-│   │   ├── config/
-│   │   └── services/
-│   │
-│   └── mobile/
-│       ├── commands/
-│       │   ├── configure-mobile.command.ts
-│       │   └── build-mobile.command.ts
-│       ├── config/
-│       │   └── mobile-config.ts
-│       └── services/
-│           ├── project.service.ts
-│           ├── source-bundle.service.ts
-│           └── jenkins-mobile.service.ts
-│
-└── shared/
-    ├── config/
-    ├── git/
-    ├── github/
-    ├── jenkins/
-    └── runtime/
-
-templates/
-└── jenkins/
-    └── Jenkinsfile-Mobile-App
-```
-
-This is intentional. Future modules can be added without dumping unrelated logic into the deployment module.
-
-Possible future commands:
-
-```text
-indraq database ...
-indraq backup ...
-indraq server ...
-indraq secrets ...
-indraq diagnostics ...
-```
-
----
-
-## Final checklist
-
-### Developer machine
-
-- [ ] Node.js 22+ installed
-- [ ] npm installed
-- [ ] Java available with `java -version`
-- [ ] Git installed
-- [ ] `tar` available
-- [ ] Docker installed if using Docker deployment
-- [ ] `npm install -g indraq_cli` completed
-- [ ] `indraq doctor` passes
-
-### Docker deployment project
-
-- [ ] `indraq configure → Jenkins → Development/Production`
-- [ ] `indraq configure → Docker / GHCR`
-- [ ] Dockerfile exists
-- [ ] GitHub/GHCR authentication works
-- [ ] Jenkins deployment job names match image names
-
-### Mobile project
-
-- [ ] command is run from package.json root
-- [ ] Production Jenkins connection configured (`indraq configure → Jenkins → Production`)
-- [ ] Jenkins File Parameter plugin installed
-- [ ] Jenkins job uses the v1.5.8 mobile Jenkinsfile
-- [ ] Mobile project type configured
-- [ ] Jenkins job is named exactly `Mobile app Cli build` and exists on Production Jenkins
-- [ ] Development / Staging / Production defaults configured as needed
-- [ ] root `.env` exists for APK/AAB/debug builds
-- [ ] Expo Development Client has `expo-dev-client`
-- [ ] `.indraq/mobile.json` is not ignored and is committed so Version/versionCode survive across developers
-
----
-
-## License
-
-MIT License. See [`LICENSE`](LICENSE).
-
-<p align="center">
-  <img src="docs/assets/indraq-mark.png" alt="IndraQ" width="72" />
-</p>
-
-<p align="center">
-  <strong>Built and maintained by IndraQ Innovations.</strong>
-</p>
-
-
-### Jenkins mobile upload returns HTTP 403
-
-IndraQ CLI v1.5.8 preserves the Jenkins web-session cookie together with the CSRF crumb when a Jenkins username/password is used. Jenkins ties crumbs to the session that created them, so both values must travel together. API-token authentication is exempt from the crumb requirement.
-
-If a mobile build still returns HTTP 403, v1.5.8 prints Jenkins' own response message. A permission error means the configured Jenkins user needs **Job/Read** and **Job/Build** on the `Mobile app Cli build` job. A CSRF error means the Jenkins controller or reverse proxy is rejecting the crumb/session and the printed Jenkins message should be used for diagnosis.
+# IndraQ CLI
+
+IndraQ CLI is a cloud-first developer and DevOps command-line platform for creating projects, configuring reusable infrastructure credentials, managing users, and reconciling deployments across GHCR, Jenkins, AWS Route53, and Nginx Proxy Manager.
+
+The goal is simple: developers should work with understandable names such as `production`, `staging`, `api.example.com`, and `order-service` instead of remembering server IP addresses, Jenkins details, registry paths, or provider credentials for every project.
+
+## What IndraQ manages
+
+IndraQ has two kinds of configuration:
+
+### User-level reusable credentials
+
+Each IndraQ user owns their own provider credentials. They can reuse the same credentials across all projects they can access.
+
+Supported reusable providers:
+
+- AWS
+- Nginx Proxy Manager (NPM)
+- Jenkins Development
+- Jenkins Production
+- GitHub Container Registry (GHCR)
+
+Credentials are stored in IndraQ Cloud. They are not copied into every project.
+
+### Project-level infrastructure
+
+Each project stores only the infrastructure associated with that project, for example:
+
+- GHCR image repository
+- Jenkins deployment job
+- Route53 record
+- Route53 routing policy
+- Route53 health checks
+- NPM proxy host
+- selected shared environment
+- host/container ports
+
+A local IndraQ project keeps the Cloud project ID in `.indraq/project.json`. Provider secrets are not stored in the project folder.
+
+---
+
+# 1. Roles and permissions
+
+IndraQ Cloud supports three roles.
+
+| Role | Main access |
+| --- | --- |
+| `user` | View the organization project catalog, create projects, configure their own provider credentials, use shared environments, run prebuild/deploy only on projects where they have WRITE access, retrieve/rotate their own managed AWS IAM credential |
+| `manager` | Everything a user can do, plus create/manage normal users, rotate managed users' AWS keys, update/delete Cloud projects with a reason, manage project membership/resource access, and view audit logs |
+| `admin` | Full access, including create managers/admins, change roles, rotate any managed AWS key, manage projects/members/resource access, manage shared environments and Route53 health checks, configure AWS policy mappings, and view audit logs |
+
+Important rules:
+
+- Managers can create normal users only.
+- Only admins can create another manager or admin.
+- Only admins can change a user's IndraQ role.
+- Only admins can create/update/delete shared environments.
+- Every user has their own AWS/NPM/Jenkins/GHCR provider credentials.
+- Shared environments are visible to authenticated users, but only admins manage them.
+- Route53 health checks can be listed/selected by users and managers, but only admins create/delete them.
+- Organization projects are visible to every authenticated user; VIEW vs WRITE controls whether infrastructure can be changed.
+
+---
+
+# 2. System architecture
+
+A typical installation looks like this:
+
+```text
+Developer workstation
+        |
+        | indraq CLI
+        v
+IndraQ Cloud API
+        |
+        +-- PostgreSQL
+        |
+        +-- user credentials
+        |     +-- AWS
+        |     +-- NPM
+        |     +-- Jenkins DEV
+        |     +-- Jenkins PROD
+        |     +-- GHCR
+        |
+        +-- shared environments
+        |
+        +-- projects
+              +-- GHCR image
+              +-- Jenkins job
+              +-- Route53 record / health checks
+              +-- NPM proxy
+```
+
+Example shared environments:
+
+```text
+production-api     -> 10.0.0.10
+production-backup  -> 10.0.0.11
+staging            -> 10.0.1.10
+qa                 -> 10.0.2.20
+client-a           -> 192.0.2.25
+```
+
+Environment names are completely arbitrary. There is no fixed `PRIMARY` or `SECONDARY` environment type.
+
+For a Route53 FAILOVER record, the user chooses which environment acts as PRIMARY and which acts as SECONDARY for that particular DNS record.
+
+---
+
+# 3. Requirements
+
+## CLI workstation
+
+Required:
+
+- Node.js 22 or newer
+- npm
+- Git
+
+Recommended/required depending on the workflow:
+
+- Docker, for GHCR image login/build/push
+- network access to IndraQ Cloud API
+- network access to Jenkins/NPM/AWS/GitHub used by that user
+
+## Cloud server
+
+Required:
+
+- Node.js 22 or newer
+- PostgreSQL
+- a persistent `MASTER_KEY`
+- a strong `JWT_SECRET`
+
+## Jenkins
+
+For deployment creation and unified Jenkins user management, Jenkins must allow the account configured in IndraQ to perform the required administrative operations.
+
+The included reference pipeline is:
+
+```text
+docs/CREATE-DEPLOYMENT-reference.groovy
+```
+
+For its live parameter UI, Jenkins Active Choices is required. Role assignment for Jenkins users requires the Jenkins Role Strategy setup expected by your Jenkins instance.
+
+IndraQ handles Jenkins CSRF crumbs together with the Jenkins web session when `/scriptText` administration is required.
+
+---
+
+# 4. Install and start IndraQ Cloud API
+
+Open the Cloud API folder:
+
+```powershell
+cd cloud-api
+npm install
+```
+
+Copy the example environment file:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Edit `.env`:
+
+```env
+PORT=4010
+DATABASE_URL=postgresql://indraq:change-me@127.0.0.1:5432/indraq_cloud
+JWT_SECRET=replace-with-at-least-32-random-characters
+MASTER_KEY=replace-with-exactly-64-hex-characters
+BOOTSTRAP_ADMIN_EMAIL=admin@example.com
+BOOTSTRAP_ADMIN_PASSWORD=use-a-strong-password
+```
+
+Requirements:
+
+- `JWT_SECRET`: at least 32 characters
+- `MASTER_KEY`: exactly 64 hexadecimal characters (32 bytes)
+- `BOOTSTRAP_ADMIN_PASSWORD`: at least 12 characters
+
+Generate a valid master key with Node:
+
+```powershell
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Generate a JWT secret:
+
+```powershell
+node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+```
+
+Build and start:
+
+```powershell
+npm run build
+npm run dev
+```
+
+Production start:
+
+```powershell
+npm run build
+npm start
+```
+
+Expected startup message:
+
+```text
+IndraQ Cloud API listening on 4010
+```
+
+## Database migrations
+
+SQL migrations in `cloud-api/sql/` are applied automatically when the Cloud API starts.
+
+You do not normally need to run migration files manually.
+
+## Bootstrap administrator
+
+If no admin exists, the Cloud API creates the first administrator from:
+
+```env
+BOOTSTRAP_ADMIN_EMAIL=...
+BOOTSTRAP_ADMIN_PASSWORD=...
+```
+
+After the first administrator is created, remove the bootstrap password from the long-running production environment if your deployment process allows it.
+
+Do not change or lose `MASTER_KEY` after secrets have been stored. The same key is required to decrypt provider credentials later.
+
+---
+
+# 5. Build and install the CLI
+
+From the repository root:
+
+```powershell
+npm install
+npm run build
+npm test
+npm link
+```
+
+Confirm installation:
+
+```powershell
+indraq --version
+indraq --help
+```
+
+Run diagnostics:
+
+```powershell
+indraq doctor
+```
+
+---
+
+# 6. Login to IndraQ Cloud
+
+The official IndraQ Cloud API URL is built into the CLI (`https://api.indraq.com`). Users do not configure a backend URL.
+
+After installing the npm package, login directly:
+
+```powershell
+indraq login
+```
+
+Check the active identity:
+
+```powershell
+indraq whoami
+```
+
+Logout:
+
+```powershell
+indraq logout
+```
+
+The aliases below also work:
+
+```powershell
+indraq cloud login
+indraq cloud whoami
+indraq cloud logout
+```
+
+---
+
+# 7. Shared environments
+
+An environment is a friendly name bound to a reusable server IP.
+
+Examples:
+
+```text
+production
+production-backup
+staging
+qa
+client-a
+mumbai-app-01
+```
+
+There is no limit such as one primary and one secondary environment. Admins can create as many environments as required and name them freely.
+
+## Create an environment
+
+Admin only:
+
+```powershell
+indraq environment create
+```
+
+The wizard asks for values such as:
+
+- environment name
+- description
+- server IPv4 address
+- region (optional/useful for latency routing)
+- audit reason
+
+## List environments
+
+```powershell
+indraq environment list
+```
+
+## Update an environment
+
+```powershell
+indraq environment update production
+```
+
+## Delete an environment
+
+```powershell
+indraq environment delete production
+```
+
+Environments are shared infrastructure shortcuts. Provider credentials are still private per IndraQ user.
+
+---
+
+# 8. Configure reusable provider credentials
+
+The easiest entry point is:
+
+```powershell
+indraq configure
+```
+
+Or configure one provider directly:
+
+```powershell
+indraq provider configure aws
+indraq provider configure npm
+indraq provider configure jenkins-dev
+indraq provider configure jenkins-prod
+indraq provider configure ghcr
+```
+
+List configured provider profiles:
+
+```powershell
+indraq provider list
+```
+
+Secrets are never printed by `provider list`.
+
+## AWS provider
+
+```powershell
+indraq provider configure aws
+```
+
+The wizard validates AWS access and can configure:
+
+- AWS region
+- access key ID
+- secret access key
+- optional session token
+- default hosted zone
+- default managed IAM policies by IndraQ role
+
+### AWS policy mapping
+
+Admins can define managed policy ARNs for:
+
+```text
+USER
+MANAGER
+ADMIN
+```
+
+Managers can configure the policy mapping needed for normal users but cannot elevate users to manager/admin.
+
+When unified AWS user creation is used, IndraQ applies the policies for the selected Cloud role. If the role changes later, IndraQ removes old IndraQ-managed role policies before applying the new role mapping so stale elevated access is not intentionally retained by the CLI.
+
+You can still explicitly provide policies when using low-level IAM commands if required.
+
+## Nginx Proxy Manager provider
+
+```powershell
+indraq provider configure npm
+```
+
+Enter:
+
+- NPM URL
+- NPM administrator email
+- NPM administrator password
+
+IndraQ validates the credentials before storing them.
+
+## Jenkins provider
+
+Development Jenkins:
+
+```powershell
+indraq provider configure jenkins-dev
+```
+
+Production Jenkins:
+
+```powershell
+indraq provider configure jenkins-prod
+```
+
+Enter:
+
+- Jenkins URL
+- Jenkins username
+- Jenkins API token/password
+
+IndraQ validates authentication before storing the profile.
+
+## GHCR provider
+
+```powershell
+indraq provider configure ghcr
+```
+
+Enter:
+
+- registry host, normally `ghcr.io`
+- GitHub token with the package permissions needed by your workflow
+
+After authentication, IndraQ fetches:
+
+- the authenticated GitHub account
+- organizations visible to that token
+
+The user selects the owner instead of typing a hardcoded organization name.
+
+Example generated image path:
+
+```text
+ghcr.io/acme-platform/order-service
+```
+
+No organization name is hardcoded into IndraQ.
+
+If GitHub cannot enumerate the required organization for the supplied token, manual owner entry remains available as a fallback.
+
+---
+
+# 9. User management
+
+Use unified user management when the same person needs accounts across IndraQ Cloud, AWS, NPM, and Jenkins.
+
+## Create a user
+
+```powershell
+indraq user create
+```
+
+The wizard asks for:
+
+- username
+- providers to create/manage
+- Cloud role (`user`, `manager`, `admin`) when permitted
+- email
+- temporary first-login password generated by IndraQ (shown once to the operator)
+- provider-specific settings where required
+
+You can also use flags:
+
+```powershell
+indraq user create hk --providers cloud,aws,npm,jenkins --role user
+```
+
+Provider-selection flags also exist:
+
+```powershell
+--cloud
+--aws
+--npm
+--jenkins
+```
+
+### Role rules
+
+Manager creating a user:
+
+```text
+allowed role: user
+```
+
+Admin creating a user:
+
+```text
+allowed roles: user, manager, admin
+```
+
+### Unified creation safety
+
+Before creating accounts in multiple providers, IndraQ preflights Jenkins administration when Jenkins is selected.
+
+If a later provider fails after creation has started, IndraQ performs best-effort rollback of providers created by that command.
+
+Always review the provider result summary after a failed operation.
+
+## Update a user
+
+```powershell
+indraq user update hk
+```
+
+Examples:
+
+```powershell
+indraq user update hk --role manager
+indraq user update hk --providers cloud,aws
+```
+
+Only an admin can change Cloud roles.
+
+## Delete a user
+
+```powershell
+indraq user delete hk
+```
+
+Skip the confirmation only when you intentionally want non-interactive deletion:
+
+```powershell
+indraq user delete hk --yes
+```
+
+
+## First login and password reset
+
+When a manager/admin creates a Cloud user, IndraQ generates a temporary password. It is intended only for the first login. On first `indraq login`, the user must choose a new password before other Cloud commands are allowed. Managed NPM/Jenkins identities created by the unified user workflow are rotated to the same new password.
+
+Self-service password recovery uses an email OTP:
+
+```powershell
+indraq password reset
+indraq password reset --email user@example.com --cloud
+indraq password reset --email user@example.com --npm
+indraq password reset --email user@example.com --jenkins
+indraq password reset --email user@example.com --all
+```
+
+`--all` means Cloud + NPM + Jenkins. AWS is intentionally excluded because IndraQ AWS users use access keys rather than console passwords. The Cloud API requires SMTP configuration (`SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`).
+
+List/update/delete workflows are searchable and selectable rather than requiring users to remember exact identities. By default list commands return 10 rows; use `--search`, `--limit`, or `--all` where available. This applies to organization users, AWS IAM users/records, NPM users/proxies, Jenkins users/jobs, projects, environments, health checks, and logs.
+
+---
+
+# 10. AWS IAM CLI users and recoverable access keys
+
+AWS does not provide the original secret access key again after access-key creation.
+
+When IndraQ creates an AWS IAM user through the unified user workflow, IndraQ stores the generated AWS secret encrypted in IndraQ Cloud and links it to that Cloud user.
+IndraQ also attaches an `IndraQBaseRole` inline IAM policy automatically according to the selected IndraQ `user`, `manager`, or `admin` role. Optional AWS managed-policy mappings configured by an operator are reconciled on top of that base role.
+
+
+The user sees the key at creation time and can retrieve their own stored credential later after logging into their IndraQ account. Access keys can also be rotated through IndraQ without losing the encrypted recovery copy.
+
+Create an IAM CLI user directly:
+
+```powershell
+indraq iam user:create hk
+```
+
+Delete:
+
+```powershell
+indraq iam user:delete hk
+```
+
+Retrieve the current logged-in user's stored unified AWS credential:
+
+```powershell
+indraq iam credentials hk
+```
+
+Rotate an access key:
+
+```powershell
+indraq iam access-key rotate
+```
+
+A normal user can rotate only their own IndraQ-managed AWS key. Managers/admins can select managed organization users across the organization. IndraQ creates the replacement key, stores it encrypted, updates the target user's reusable AWS provider credential, and only then deletes the previous managed key. Rotation is audited. If the IAM user already has two keys, IndraQ stops rather than deleting an unknown/unmanaged key.
+
+Important security behavior:
+
+- the target Cloud user can retrieve their own stored AWS secret
+- normal users cannot resolve another user's provider credentials
+- retrieval is audited
+- provider-resolution responses use `Cache-Control: no-store`
+- AWS console login profiles are intentionally not created by these IAM CLI-user flows
+
+If an AWS key is exposed publicly, rotate/delete it immediately even if IndraQ has an encrypted copy.
+
+---
+
+# 11. Create a project with `indraq init`
+
+The recommended project entry point is:
+
+```powershell
+indraq init
+```
+
+Or initialize another directory:
+
+```powershell
+indraq init my-app
+```
+
+## Login check
+
+`init` verifies that the user is connected and authenticated to IndraQ Cloud. If required, it guides the user through Cloud configuration/login.
+
+## New project
+
+The wizard supports:
+
+- Frontend
+- Backend
+- Frontend + Backend
+- Mobile App
+
+Web/frontend options include supported project templates such as Vite/React/Next/vanilla depending on the selected flow.
+
+Backend scaffolding includes Express and optional integrations selected in the wizard.
+
+## Dependency installation
+
+For web projects, IndraQ links the project to Cloud **before** dependency installation.
+
+This is deliberate. If npm is unavailable, a registry is temporarily unreachable, or installation fails, the Cloud project is not lost.
+
+IndraQ:
+
+1. creates the project files
+2. creates/links the Cloud project
+3. runs npm installation
+4. retries compatible npm execution paths where appropriate
+5. reports any component where installation is still pending
+6. continues the project/infrastructure workflow
+
+If npm still cannot install dependencies, the CLI prints the exact folders where you should run:
+
+```powershell
+npm install
+```
+
+You can intentionally skip installation:
+
+```powershell
+indraq init --skip-install
+```
+
+Generated npm package names are sanitized so display names containing spaces or uppercase characters do not create invalid package names.
+
+## Full setup vs project only
+
+After project creation, choose:
+
+```text
+Full setup now — GHCR + Jenkins + Route53 + NPM
+```
+
+or:
+
+```text
+Project only — I will run prebuild later
+```
+
+Choosing project-only still leaves a valid Cloud-linked project.
+
+Run infrastructure setup later with:
+
+```powershell
+indraq prebuild
+```
+
+## Existing IndraQ project
+
+If `.indraq/project.json` already exists, `init` does not blindly recreate the application.
+
+It checks the existing Cloud project and offers to reconcile pending:
+
+- GHCR
+- Jenkins
+- Route53
+- NPM
+
+This means rerunning `indraq init` is useful when a previous setup was intentionally skipped or interrupted.
+
+## Existing non-IndraQ project
+
+If files already exist but the folder was not initialized by IndraQ, the CLI warns that generated files may be overwritten.
+
+It requires two confirmations, including typing:
+
+```text
+OVERWRITE
+```
+
+No existing project should be overwritten silently.
+
+---
+
+# 12. Project Cloud registration and linking
+
+## Register an existing application without running `init`
+
+If you already have a project and only want IndraQ to manage its Cloud identity/infrastructure, run this from the existing project folder:
+
+```powershell
+indraq project create
+```
+
+This command is intentionally non-destructive. It:
+
+- verifies your IndraQ Cloud login
+- detects sensible defaults from `package.json` when possible
+- asks for project type/framework/port metadata where needed
+- creates the Cloud project
+- creates only `.indraq/project.json` locally
+
+It does **not** scaffold source code, run `npm install`, generate a Dockerfile, create AWS records, create NPM proxies, create Jenkins jobs, configure GHCR, run prebuild, or deploy anything.
+
+Example for an existing Express API:
+
+```powershell
+cd cloud-api
+indraq project create cloud-api --kind backend --framework express --port 4010 --health /health
+```
+
+After that you can run infrastructure commands independently:
+
+```powershell
+indraq dockerfile create
+indraq jenkins create-deployment
+indraq healthcheck list
+indraq healthcheck create
+indraq healthcheck delete
+
+indraq dns create
+indraq proxy create
+```
+
+Or reconcile everything later:
+
+```powershell
+indraq prebuild
+```
+
+If an accessible Cloud project with the same name already exists, IndraQ offers to link the folder to it instead of silently creating a duplicate.
+
+## Sync older IndraQ project metadata
+
+For folders already initialized by an older IndraQ metadata format, create/update the Cloud project with:
+
+```powershell
+indraq project sync
+```
+
+Check infrastructure associations:
+
+```powershell
+indraq project status
+```
+
+The local project file becomes Cloud-oriented and primarily stores the project ID.
+
+Example:
+
+```json
+{
+  "schemaVersion": 3,
+  "projectId": "..."
+}
+```
+
+Provider passwords/tokens are not supposed to live in that file.
+
+## Re-link a folder when `.indraq/project.json` is missing
+
+If the local project reference is deleted accidentally, do **not** recreate the project. Run:
+
+```powershell
+indraq project link
+```
+
+IndraQ lists the Cloud projects the logged-in user is allowed to access. Selecting one recreates only `.indraq/project.json`; application files are not modified.
+
+Every authenticated organization user can discover and view the project catalog. `indraq project list` shows whether the current account has `VIEW` or `WRITE` access. Managers/admins can manage project membership with audited reasons:
+
+```powershell
+indraq project add user
+indraq project delete user
+```
+
+VIEW access allows discovery/linking/inspection. WRITE access is required for infrastructure-changing commands such as prebuild. Cloud project update/delete remains manager/admin controlled and audited.
+
+## Project resource access
+
+Project membership and provider-resource access are separate. Managers/admins can grant or revoke access to AWS, NPM, Jenkins, or all supported project resources:
+
+```powershell
+indraq access add user
+indraq access delete user
+```
+
+For AWS, IndraQ generates record-name/record-type/action conditions for granted Route53 records and exact health-check ARN permissions. AWS cannot safely hide individual records if `ListResourceRecordSets` is granted, so normal-user workflows rely on the IndraQ project inventory rather than broad hosted-zone listing.
+
+For Jenkins, IndraQ synchronizes Role Strategy item roles for the selected deployment jobs.
+
+For NPM, normal users retain NPM's creator-owned `visibility=user` model. IndraQ records project/resource grants but does not switch accounts to `visibility=all`, because that would expose proxy hosts created by other users.
+
+---
+
+# 13. Prebuild: reconcile the complete web deployment
+
+For a Cloud-linked web project, run:
+
+```powershell
+indraq prebuild
+```
+
+Prebuild is an infrastructure reconciler. It checks what already exists, creates missing resources, and repairs supported stale associations instead of assuming every run starts from zero.
+
+Typical order:
+
+```text
+User provider credentials
+        |
+        v
+GHCR project image
+        |
+        v
+Jenkins host-port validation
+        |
+        v
+Jenkins deployment job
+        |
+        v
+Route53 record + selected existing health checks
+        |
+        v
+Verify Route53 prerequisite
+        |
+        v
+NPM proxy + SSL
+```
+
+## Missing provider configuration
+
+If required reusable credentials are missing, IndraQ warns and offers to configure them instead of immediately failing with an unexplained configuration error.
+
+## Shared environment or custom target
+
+For infrastructure targets, users can select an admin-created shared environment.
+
+Where supported, a custom IP/hostname option remains available for exceptional cases.
+
+---
+
+# 14. Route53 DNS
+
+Standalone DNS wizard:
+
+```powershell
+indraq dns create
+```
+
+Other useful commands:
+
+```powershell
+indraq dns zones
+indraq dns records
+indraq dns update
+indraq dns delete
+```
+
+Supported routing choices for managed A-record flows:
+
+```text
+SIMPLE
+FAILOVER
+WEIGHTED
+LATENCY
+```
+
+## FAILOVER
+
+For FAILOVER, the user chooses any two environments:
+
+```text
+PRIMARY target   -> production
+SECONDARY target -> production-backup
+```
+
+The environments themselves are not permanently primary/secondary.
+
+The same environment can play a different role for another DNS record.
+
+## Route53 health checks
+
+DNS creation does **not** create health checks automatically. Users and managers select from health checks that already exist in Route53. Only an IndraQ admin can create or delete health checks:
+
+```powershell
+indraq healthcheck list
+indraq healthcheck create
+indraq healthcheck delete
+```
+
+`healthcheck list` is available for selection/search. `healthcheck create` asks for the real AWS endpoint settings (IP/FQDN, protocol, port, path where applicable, request interval, failure threshold, and latency measurement).
+
+Routing behavior is enforced:
+
+- `SIMPLE`: no health check is attached.
+- `FAILOVER`: select existing PRIMARY and SECONDARY health checks.
+- `WEIGHTED` / `LATENCY`: attaching an existing health check is optional.
+
+## WEIGHTED
+
+IndraQ asks for primary/secondary weights.
+
+## LATENCY
+
+IndraQ asks for the AWS regions associated with the selected targets when required.
+
+## SIMPLE
+
+Only one target is required.
+
+---
+
+# 15. Nginx Proxy Manager proxy and SSL
+
+Standalone proxy creation:
+
+```powershell
+indraq proxy create api.example.com
+```
+
+Update/delete:
+
+```powershell
+indraq proxy update api.example.com
+indraq proxy delete api.example.com
+```
+
+## Route53 prerequisite
+
+IndraQ verifies that the exact Route53 record exists before creating a new NPM proxy host.
+
+If the DNS record is missing, proxy creation stops before NPM creation. This avoids creating a proxy/certificate flow for a domain that has not been routed yet.
+
+## Forward target
+
+The user can select a shared environment, for example:
+
+```text
+production — 10.0.0.10
+staging    — 10.0.1.10
+```
+
+or choose a custom IP/hostname.
+
+## SSL choices
+
+NPM creation includes explicit SSL selection:
+
+```text
+Request Let's Encrypt certificate
+Use an existing NPM certificate
+No SSL
+```
+
+For Let's Encrypt, IndraQ asks for the required email and certificate options.
+
+For an existing certificate, IndraQ lists available NPM certificates when possible so users do not have to remember a certificate ID.
+
+---
+
+# 16. Jenkins deployment and port validation
+
+IndraQ checks the requested host port before final deployment creation.
+
+If the port is busy, the CLI reports it immediately and suggests available alternatives instead of waiting for a pipeline failure.
+
+Conceptually:
+
+```text
+Requested port: 6200
+        |
+        +-- free -> continue
+        |
+        +-- busy -> show suggested free ports -> ask again
+```
+
+Jenkins remains the final authority and should still validate the port during the pipeline/deployment itself.
+
+## Create only the Jenkins deployment
+
+If DNS/NPM setup is not wanted yet, trigger only the Jenkins seed job:
+
+```powershell
+indraq jenkins create-deployment
+```
+
+This performs the aggressive host-port check, uses the selected user's GHCR owner/image, invokes `CREATE-DEPLOYMENT`, records the Jenkins project resource, and does **not** modify Route53 or NPM.
+
+Create/reconcile deployment infrastructure:
+
+```powershell
+indraq deployment create
+```
+
+This is backed by the same prebuild reconciliation flow.
+
+Run an existing configured deployment:
+
+```powershell
+indraq deployment run --env production
+```
+
+Build/push/deploy:
+
+```powershell
+indraq deploy build --env production
+```
+
+The shared environment name is not restricted to `dev` or `prod`.
+
+---
+
+# 17. GHCR image naming
+
+The image path is built from the authenticated user's selected registry owner.
+
+Example provider configuration:
+
+```text
+Registry: ghcr.io
+Owner: acme-platform
+```
+
+Project:
+
+```text
+order-service
+```
+
+Generated repository:
+
+```text
+ghcr.io/acme-platform/order-service
+```
+
+For full-stack projects, components can use separate image names, for example:
+
+```text
+ghcr.io/acme-platform/order-service-frontend
+ghcr.io/acme-platform/order-service-backend
+```
+
+---
+
+# 18. NPM user management
+
+Create:
+
+```powershell
+indraq npm-user create
+```
+
+Update:
+
+```powershell
+indraq npm-user update user@example.com
+```
+
+Delete:
+
+```powershell
+indraq npm-user delete user@example.com
+```
+
+These commands use the current logged-in user's reusable NPM provider credential.
+
+---
+
+# 19. Dockerfile generation
+
+For an existing project:
+
+```powershell
+indraq dockerfile create
+```
+
+IndraQ does not try to guess which source/configuration files your application needs. Generated Dockerfiles copy the complete Docker build context with `COPY . .`; `.dockerignore` is the source of truth for files that must stay out of the image.
+
+Generated Alpine runtime images install `curl`, and Docker health checks use `curl -fsS`. This keeps container health validation available for Node and Nginx images without relying on whichever BusyBox utilities happen to be present.
+
+The generated `.dockerignore` excludes local dependencies, Git/IndraQ metadata, logs, coverage, caches, and previous build output. IndraQ intentionally does **not** ignore `.env` or `.env.*` files, so environment files present in the project directory are included in the Docker build context and baked into the resulting image according to the company's deployment policy.
+
+For Node backends and Next.js applications, the runtime stage copies the complete filtered build tree from the build stage, including generated output and production dependencies. For Vite/React static frontends, the build stage receives the complete filtered project context and Nginx serves only the compiled output directory.
+
+Dependency installation also works whether the project has a `package-lock.json` or not: IndraQ uses `npm ci` when a lockfile exists and falls back to `npm install` otherwise.
+
+Optional flags include framework, Node version, port, health endpoint, Compose generation, output directory, and force overwrite.
+
+Use command help for the current options:
+
+```powershell
+indraq dockerfile create --help
+```
+
+---
+
+# 20. Mobile projects
+
+IndraQ also includes mobile project configuration/build commands.
+
+See:
+
+```powershell
+indraq help mobile
+```
+
+or:
+
+```powershell
+indraq build --help
+```
+
+Web deployment reconciliation through Route53/NPM is intended for web frontend/backend components. Mobile build behavior is separate.
+
+---
+
+# 21. Audit logs
+
+Managers and admins can view audit logs:
+
+```powershell
+indraq logs
+```
+
+Sensitive Cloud/provider actions use audit reasons so administrative changes can be traced.
+
+Examples include:
+
+- user creation/deletion
+- provider credential changes
+- AWS credential storage/resolution
+- environment changes
+- project resource reconciliation
+
+---
+
+# 22. Doctor
+
+Run:
+
+```powershell
+indraq doctor
+```
+
+Doctor checks the local IndraQ/Node environment and useful project/provider conditions.
+
+Use it when setup feels inconsistent before manually editing local configuration files.
+
+---
+
+# 23. Recommended first-time setup
+
+## Administrator
+
+1. Start IndraQ Cloud API.
+2. Login as bootstrap admin.
+3. Create shared environments.
+4. Configure your own provider credentials.
+5. Configure AWS role-policy mappings if unified AWS user creation will be used.
+6. Create managers/users as required.
+
+Example:
+
+```powershell
+indraq login
+indraq environment create
+indraq environment create
+indraq provider configure aws
+indraq provider configure npm
+indraq provider configure jenkins-dev
+indraq provider configure jenkins-prod
+indraq provider configure ghcr
+indraq user create
+```
+
+## Developer
+
+1. Login to IndraQ Cloud.
+2. Configure the provider credentials that belong to you.
+3. Run `indraq init`.
+4. Select full infrastructure setup, or skip it and run `indraq prebuild` later.
+5. Start coding.
+
+Example:
+
+```powershell
+indraq login
+indraq configure
+indraq init my-service
+```
+
+---
+
+# 24. Recommended daily workflow
+
+Inside an existing project:
+
+```powershell
+indraq whoami
+indraq project status
+indraq prebuild
+indraq deploy build --env production
+```
+
+You do not need to re-enter AWS/NPM/Jenkins/GHCR credentials for every project.
+
+---
+
+# 25. Common troubleshooting
+
+## `npm install` fails during `indraq init`
+
+IndraQ links the Cloud project before dependency installation and should preserve setup even when installation fails.
+
+Look for the component paths printed by the CLI, then run:
+
+```powershell
+cd <component-folder>
+npm install
+```
+
+Also verify:
+
+```powershell
+node --version
+npm --version
+npm config get registry
+```
+
+Use Node.js 22 or newer.
+
+## Jenkins returns `403 No valid crumb was included`
+
+The current Jenkins administration client fetches the Jenkins crumb together with its session cookies and sends them together to `/scriptText`.
+
+If a 403 continues:
+
+- verify the configured Jenkins account can access the required administration endpoint
+- verify reverse proxies are not stripping session cookies/headers
+- verify Jenkins security settings/plugins expected by your setup
+- prefer a Jenkins API token where appropriate
+
+Run the provider configuration again if credentials changed:
+
+```powershell
+indraq provider configure jenkins-dev
+```
+
+or:
+
+```powershell
+indraq provider configure jenkins-prod
+```
+
+## Port is already in use
+
+IndraQ should detect the busy Jenkins host port before creating the deployment and offer suggested alternatives.
+
+Choose another suggested port and continue.
+
+## NPM proxy creation says Route53 is missing
+
+Create/reconcile DNS first:
+
+```powershell
+indraq dns create
+```
+
+or run:
+
+```powershell
+indraq prebuild
+```
+
+Then retry the proxy.
+
+## GHCR organization is missing from the selection
+
+The organization list is based on what the GitHub token can see.
+
+Check token access. If the required owner still cannot be enumerated, use the manual-owner fallback in the GHCR provider wizard.
+
+## AWS secret is not visible in AWS anymore
+
+AWS does not re-display an existing secret access key.
+
+If the AWS user was created through IndraQ's unified user workflow and the encrypted credential was stored successfully, the logged-in target user can run:
+
+```powershell
+indraq iam credentials <aws-username>
+```
+
+Otherwise rotate/create a new AWS access key rather than attempting to recover an unavailable secret from AWS.
+
+## Cloud API refuses to start because of `MASTER_KEY`
+
+`MASTER_KEY` must be exactly 64 hexadecimal characters.
+
+Generate one with:
+
+```powershell
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Do not replace an existing production master key if encrypted credentials already exist.
+
+---
+
+# 26. Security model
+
+## Passwords
+
+IndraQ Cloud account passwords are hashed with bcrypt.
+
+## Reusable provider secrets
+
+Provider secrets must be usable again for AWS/Jenkins/NPM/GHCR API calls, so they cannot be stored as one-way password hashes.
+
+They are encrypted at rest using AES-256-GCM with the Cloud API `MASTER_KEY`.
+
+## Project files
+
+Project folders should not contain reusable provider secrets.
+
+The normal design is:
+
+```text
+local project -> project ID
+Cloud user    -> reusable encrypted provider credentials
+Cloud project -> infrastructure associations
+```
+
+## AWS IAM users
+
+IndraQ's IAM-user flow is intended for CLI/API users. AWS console login profiles are intentionally not created.
+
+## Exposed credentials
+
+If any AWS key, GitHub token, Jenkins token, NPM password, or other credential is pasted into logs/chat/tickets or otherwise exposed, rotate it immediately. Encryption in IndraQ Cloud does not make a publicly exposed credential safe.
+
+---
+
+# 27. Main command reference
+
+Use `--help` on any command for the authoritative current flags.
+
+```text
+indraq configure
+indraq doctor
+
+indraq login
+indraq logout
+indraq whoami
+
+indraq environment create
+indraq environment list
+indraq environment update
+indraq environment delete
+
+indraq provider configure
+indraq provider list
+
+indraq user list
+indraq user create
+indraq user update
+indraq user delete
+indraq password reset
+
+indraq iam user:create
+indraq iam user:delete
+indraq iam credentials
+
+indraq dns zones
+indraq dns records
+indraq dns create
+indraq dns update
+indraq dns delete
+
+indraq proxy create
+indraq proxy update
+indraq proxy delete
+
+indraq npm-user create
+indraq npm-user update
+indraq npm-user delete
+
+indraq init
+indraq project create
+indraq project link
+indraq project sync
+indraq project status
+indraq prebuild
+
+indraq deployment create
+indraq deployment run
+indraq deploy build
+
+indraq dockerfile create
+indraq logs
+```
+
+For the complete live command reference:
+
+```powershell
+indraq --help
+```
+
+---
+
+# 28. Legacy compatibility commands
+
+Provider credentials now live directly in IndraQ Cloud.
+
+The old-style credential commands remain only for compatibility:
+
+```powershell
+indraq credentials sync
+indraq credentials restore
+```
+
+They do not represent the recommended local-file-to-Cloud workflow.
+
+Use instead:
+
+```powershell
+indraq provider configure <provider>
+indraq provider list
+```
+
+---
+
+# 29. Release verification
+
+Before deploying or distributing the CLI, run:
+
+```powershell
+npm install
+npm run build
+npm test
+```
+
+Cloud API:
+
+```powershell
+cd cloud-api
+npm install
+npm run build
+```
+
+Then perform a real integration test in your own environment because mocked regression tests cannot verify private AWS, Jenkins, NPM, GHCR, DNS, firewall, or server configuration.
+
+A useful end-to-end test is:
+
+1. login
+2. create/list environments
+3. configure provider credentials
+4. create a disposable project with `indraq init`
+5. choose full setup
+6. verify Jenkins port validation
+7. verify Route53 routing and AWS health checks
+8. verify NPM SSL/proxy
+9. verify GHCR image owner/path
+10. rerun `indraq prebuild` and confirm resources are reconciled rather than duplicated
+
+---
+
+# License
+
+MIT. See `LICENSE`.