indraq_cli 1.9.1 → 2.0.0

package/README.md

@@ -1,1517 +1,1043 @@
-# 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`.
+<div align="center">
+  <img src="docs/assets/indraq-logo.png" alt="IndraQ" width="430" />
+
+  <h1>IndraQ CLI</h1>
+
+  <p><strong>One developer command center for project setup, access, infrastructure and deployments.</strong></p>
+
+  <p>
+    <img alt="npm" src="https://img.shields.io/badge/npm-v2.0.0-CB3837?logo=npm&logoColor=white" />
+    <img alt="Node.js" src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white" />
+    <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-CLI-3178C6?logo=typescript&logoColor=white" />
+    <img alt="License" src="https://img.shields.io/badge/license-MIT-blue" />
+  </p>
+
+  <p>
+    <a href="#quick-start">Quick start</a> ·
+    <a href="#recommended-workflow-in-chronological-order">Workflow</a> ·
+    <a href="#command-reference">Commands</a> ·
+    <a href="#common-real-world-flows">Common flows</a> ·
+    <a href="#security-model">Security</a> ·
+    <a href="#troubleshooting">Troubleshooting</a>
+  </p>
+</div>
+
+> [!NOTE]
+> This guide matches **IndraQ CLI v2.0.0**. For the exact flags supported by your installed version, use `indraq <command> --help`.
+
+IndraQ CLI removes repetitive DevOps work from the developer path. Instead of opening Jenkins, AWS, Nginx Proxy Manager, GHCR and multiple configuration files for every project, you use one consistent CLI from the terminal.
+
+```mermaid
+flowchart LR
+    A[Login] --> B[Configure providers once]
+    B --> C[Create or link project]
+    C --> D[Prebuild infrastructure]
+    D --> E[Build & deploy]
+    E --> F[Operate / audit]
+```
+
+The key design is simple: **user credentials stay reusable and personal; project infrastructure stays attached to the project.** This lets the same provider configuration work across every project the user is allowed to access.
+
+
+> [!TIP]
+> **v2.0 lifecycle rule:** deleting a person deletes their Cloud/AWS/NPM/Jenkins identity, but **does not delete the project**. Jenkins DEV/PROD cleanup checks every configured controller. Adding another user to that project inherits its existing resource grants and synchronizes the provider-native access that can be safely scoped per user.
+
+<details>
+<summary><strong>📚 Table of contents</strong></summary>
+
+- [Why use IndraQ?](#why-use-indraq)
+- [The mental model](#the-mental-model)
+- [Roles and permissions](#roles-and-permissions)
+- [Quick start](#quick-start)
+- [Recommended workflow](#recommended-workflow-in-chronological-order)
+- [Command reference](#command-reference)
+  - [Help, diagnostics and authentication](#a-help-diagnostics-and-authentication)
+  - [Providers and environments](#b-reusable-providers-and-shared-environments)
+  - [Users and roles](#c-organization-users-and-roles)
+  - [Project access](#d-project-membership-and-resource-access)
+  - [Project lifecycle](#e-project-lifecycle)
+  - [Infrastructure and deployment](#f-infrastructure-reconciliation-and-deployment)
+  - [Jenkins](#g-jenkins-pipelines-deployments-and-users)
+  - [AWS IAM](#h-aws-iam-and-managed-access-keys)
+  - [Route53](#i-route53-dns-and-health-checks)
+  - [Nginx Proxy Manager](#j-nginx-proxy-manager-proxy-hosts-and-users)
+  - [Mobile builds](#k-mobile-builds)
+  - [Audit logs](#l-audit-logs)
+- [Common real-world flows](#common-real-world-flows)
+- [Security model](#security-model)
+- [Troubleshooting](#troubleshooting)
+- [Cloud API operator notes](#platform-operator-indraq-cloud-api)
+- [Release checklist](#before-publishing-a-cli-release)
+
+</details>
+
+---
+
+## Why use IndraQ?
+
+| Problem without IndraQ | What IndraQ does |
+| --- | --- |
+| Developers remember IPs, ports, Jenkins jobs and registry paths | Uses named environments and stored project associations |
+| Provider credentials are copied between projects | Stores reusable credentials once in IndraQ Cloud |
+| New projects need repetitive folder, Docker and environment setup | `indraq init` scaffolds the project safely |
+| DNS, proxy and Jenkins setup drift apart | `indraq prebuild` reconciles them as one workflow |
+| User access has to be changed in several systems | Unified user create/update/delete synchronizes providers |
+| Jenkins jobs require opening the browser and remembering parameters | CLI can discover, prompt for and run any visible pipeline |
+| AWS keys are difficult to recover or rotate safely | IndraQ can store managed IAM credentials encrypted and rotate them |
+| Nobody knows who changed infrastructure | Manager/admin operations are audited in IndraQ Cloud |
+
+The result is not just fewer commands. The important benefit is **repeatability**: two developers following the same IndraQ workflow should reach the same infrastructure state without having to know every provider-specific detail.
+
+---
+
+## The mental model
+
+IndraQ is easiest to understand as three connected layers:
+
+```mermaid
+flowchart TB
+    U[Developer / Admin] --> CLI[IndraQ CLI]
+    CLI --> CLOUD[IndraQ Cloud]
+
+    CLOUD --> CREDS[Reusable provider credentials]
+    CREDS --> AWS[AWS]
+    CREDS --> NPM[Nginx Proxy Manager]
+    CREDS --> JDEV[Jenkins Dev]
+    CREDS --> JPROD[Jenkins Prod]
+    CREDS --> GHCR[GHCR]
+
+    CLOUD --> ENV[Shared named environments]
+    ENV --> PROD[production → 10.0.0.10]
+    ENV --> STAGE[staging → 10.0.1.10]
+
+    CLOUD --> PROJECT[Project associations]
+    PROJECT --> DNS[Route53]
+    PROJECT --> PROXY[Proxy / SSL]
+    PROJECT --> PIPE[Jenkins deployment]
+    PROJECT --> IMAGE[Container image]
+```
+
+### 1. Reusable provider credentials
+
+Each IndraQ user can store their own credentials for AWS, Nginx Proxy Manager, Jenkins Development, Jenkins Production and GHCR. They are stored in IndraQ Cloud and reused across projects instead of being copied into every repository.
+
+### 2. Shared environments
+
+Admins define friendly environment names such as `production`, `production-backup`, `staging` and `qa`. Developers select the name instead of memorizing an IP address.
+
+### 3. Project infrastructure
+
+A Cloud project remembers the infrastructure associated with that application: image, Jenkins job, Route53 records and routing, health checks, NPM proxy/SSL, environment, ports and deployment metadata.
+
+The local repository normally needs only the Cloud project reference:
+
+```text
+.indraq/project.json
+```
+
+---
+
+## Roles and permissions
+
+| Role | Typical responsibility |
+| --- | --- |
+| `user` | Work on permitted projects, configure personal providers, prebuild/deploy, use shared environments and manage their own supported credentials |
+| `manager` | Everything a user can do, plus manage normal users, project membership/resource access, managed user AWS keys and audit logs |
+| `admin` | Full organization control, including managers/admins, role changes, shared environments and admin-only Route53 health-check operations |
+
+Important role rules:
+
+- Managers can create and manage normal `user` accounts.
+- Only admins can create managers/admins or change an existing IndraQ role.
+- The last active admin cannot be deleted or demoted.
+- An admin cannot use the role endpoint to demote their own active session.
+- Role promotion/demotion is synchronized across linked managed providers before the Cloud role is committed.
+
+Provider role mapping is intentional. Nginx Proxy Manager only provides `user` and `admin`, so IndraQ maps `manager` and `admin` to NPM `admin`. AWS and Jenkins use their IndraQ-managed role/policy mappings.
+
+```mermaid
+flowchart LR
+    U[user] -->|admin promotes| M[manager]
+    M -->|admin promotes| A[admin]
+    A -->|admin demotes| M
+    M -->|admin demotes| U
+
+    M -. role sync .-> AWS[AWS policy]
+    M -. role sync .-> NPM[NPM role]
+    M -. role sync .-> J[Jenkins role]
+```
+
+---
+
+# Quick start
+
+## 1. Install
+
+Requirements:
+
+- Node.js **22+**
+- npm
+- Git
+- Docker when building/pushing Docker images
+- network access to the IndraQ Cloud and providers you use
+
+Install the published CLI:
+
+```powershell
+npm install -g indraq_cli
+```
+
+Check it:
+
+```powershell
+indraq --version
+indraq doctor
+indraq --help
+```
+
+When developing the CLI itself:
+
+```powershell
+npm install
+npm run build
+npm test
+npm link
+```
+
+---
+
+## 2. Login
+
+```powershell
+indraq login
+```
+
+Check the current identity:
+
+```powershell
+indraq whoami
+```
+
+The normal CLI uses the official IndraQ Cloud endpoint built into the package. Users do not need to configure an API URL manually.
+
+If the account was created with a temporary password, the first login requires a new password before normal Cloud operations continue.
+
+---
+
+## 3. Configure your providers once
+
+The easiest entry point is:
+
+```powershell
+indraq configure
+```
+
+It provides one menu for:
+
+```text
+Reusable provider credentials
+Current project infrastructure / prebuild
+Mobile settings
+Provider status
+```
+
+You can also configure a 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
+```
+
+Review what is configured without exposing secrets:
+
+```powershell
+indraq provider list
+```
+
+---
+
+## 4. Create or connect a project
+
+For a brand-new application:
+
+```powershell
+indraq init
+```
+
+For an existing codebase that should become a new Cloud project without scaffolding it:
+
+```powershell
+indraq project create
+```
+
+For a folder that belongs to an existing Cloud project:
+
+```powershell
+indraq project link
+```
+
+Check the current association:
+
+```powershell
+indraq project status
+```
+
+---
+
+## 5. Prepare infrastructure
+
+```powershell
+indraq prebuild
+```
+
+For web projects, prebuild is the main infrastructure reconciliation command. It discovers the current state and prepares only what the project needs.
+
+```mermaid
+flowchart LR
+    P[indraq prebuild] --> G[GHCR image]
+    P --> R[Route53 DNS / routing]
+    P --> H[Health checks]
+    P --> N[NPM proxy / SSL]
+    P --> J[Jenkins deployment]
+    G --> S[Project resource associations]
+    R --> S
+    H --> S
+    N --> S
+    J --> S
+```
+
+Use it for the first deployment **and** whenever infrastructure needs to be reconciled later.
+
+---
+
+## 6. Deploy
+
+Deploy with a named shared environment:
+
+```powershell
+indraq deploy build --env staging
+```
+
+Common shortcuts:
+
+```powershell
+indraq deploy:dev
+indraq deploy:prod
+```
+
+The deployment flow builds the Docker image, pushes it to the configured registry and runs the configured Jenkins deployment.
+
+---
+
+# Recommended workflow in chronological order
+
+```mermaid
+flowchart LR
+    D[1 · doctor] --> L[2 · login]
+    L --> C[3 · configure]
+    C --> E[4 · environments]
+    E --> P[5 · project]
+    P --> S[6 · status]
+    S --> B[7 · prebuild]
+    B --> DEP[8 · deploy]
+    DEP --> LOG[9 · logs]
+```
+
+| Step | Command | Why it matters |
+| ---: | --- | --- |
+| 1 | `indraq doctor` | Verify the machine and CLI command resolution before debugging anything else |
+| 2 | `indraq login` | Authenticate to the organization control plane |
+| 3 | `indraq configure` | Store reusable provider credentials once |
+| 4 | `indraq environment list` | See which admin-managed server targets are available |
+| 5 | `indraq init` / `project create` / `project link` | Establish the project correctly before infrastructure work |
+| 6 | `indraq project status` | Confirm which Cloud project and resources the folder is using |
+| 7 | `indraq prebuild` | Reconcile DNS, proxy, image and Jenkins infrastructure |
+| 8 | `indraq deploy build --env <name>` | Build, push and deploy the application |
+| 9 | `indraq logs` | Audit administrative/infrastructure activity when investigating changes |
+
+For normal daily work after initial setup, developers usually spend most of their time around `project status`, `prebuild`, deployment commands and Jenkins pipeline commands.
+
+---
+
+# Command reference
+
+> [!TIP]
+> Read these tables as a **map of intent**. When you know what you want to do but not the exact flags, find the command here and then run `indraq <command> --help`.
+
+`indraq --help` and `<command> --help` are the authoritative source for flags. The tables below explain **when to use each command and why it exists**.
+
+Most list/select commands support some combination of:
+
+```text
+--search <text>   filter results
+--limit <number>  control the number loaded
+--all             load all results
+```
+
+## A. Help, diagnostics and authentication
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq --help` | Show the complete live CLI command tree. Start here when you do not remember a command. |
+| `indraq <command> --help` | Show flags and subcommands for one command. Best source for exact current syntax. |
+| `indraq help [topic]` | Focused help for supported topics such as `configure`, `docker`, `mobile`, `aws` and `doctor`. |
+| `indraq doctor` | Diagnose Node.js and command-resolution problems. Run this before deeper troubleshooting. |
+| `indraq login` | Authenticate to IndraQ Cloud. Supports `--email` and `--password` for scripted use. |
+| `indraq logout` | Remove the current Cloud session from the machine. |
+| `indraq whoami` | Show the authenticated IndraQ identity. Useful before admin or production actions. |
+| `indraq password reset` | Email-OTP password recovery for Cloud, NPM, Jenkins or all password-based accounts. AWS keys are intentionally separate. |
+| `indraq cloud login` | Namespaced alias of `indraq login`. |
+| `indraq cloud logout` | Namespaced alias of `indraq logout`. |
+| `indraq cloud whoami` | Namespaced alias of `indraq whoami`. |
+
+Examples:
+
+```powershell
+indraq help aws
+indraq whoami
+indraq password reset --email user@example.com --all
+```
+
+---
+
+## B. Reusable providers and shared environments
+
+Configure these before expecting project automation to work.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq configure` | Main configuration home. Recommended interactive entry point for providers, current-project prebuild and mobile settings. |
+| `indraq provider configure [provider]` | Configure `aws`, `npm`, `jenkins-dev`, `jenkins-prod` or `ghcr` directly in Cloud. |
+| `indraq provider list` | Show configured providers without exposing secrets. Useful before `prebuild`, user provisioning or Jenkins operations. |
+| `indraq environment create` | **Admin:** create a reusable named server environment. Prevents users from memorizing IPs. |
+| `indraq environment list` | List shared environments and targets. |
+| `indraq environment update [name]` | **Admin:** update an environment target. Projects can keep using the friendly environment name. |
+| `indraq environment delete [name]` | **Admin:** remove an environment. Use `--yes` only when intentionally bypassing confirmation. |
+| `indraq credentials configure [provider]` | Compatibility namespace for provider configuration. Prefer `provider configure`. |
+| `indraq credentials list` | Compatibility namespace for provider listing. Prefer `provider list`. |
+| `indraq credentials sync` | Legacy credential synchronization command retained for compatibility. |
+| `indraq credentials restore` | Legacy credential restore workflow retained for compatibility. |
+| `indraq server create` | Deprecated alias that creates a shared environment. Prefer `environment create`. |
+| `indraq server list` | Deprecated alias that lists shared environments. Prefer `environment list`. |
+
+Example:
+
+```powershell
+indraq environment create
+indraq environment list --all
+indraq provider configure jenkins-prod
+indraq provider list
+```
+
+---
+
+## C. Organization users and roles
+
+Unified user commands coordinate identities across IndraQ Cloud and selected configured providers.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq user list` | **Manager/admin:** list organization users. Use it before updates/deletion when you do not remember exact usernames. |
+| `indraq user create [username]` | **Manager/admin:** create a Cloud user and selected AWS/NPM/Jenkins identities. If both Jenkins DEV and PROD are configured, both are preflighted and managed. |
+| `indraq user update [username]` | Update selected providers. **Admin role changes are synchronized across linked managed providers before Cloud is changed.** |
+| `indraq user delete [username]` | Permanently delete the person's managed identities. Project definitions and infrastructure stay intact. |
+
+Useful examples:
+
+```powershell
+indraq user create nitin --providers cloud,aws,npm,jenkins --role user
+indraq user update nitin --role manager
+indraq user update nitin --role user
+indraq user delete nitin
+```
+
+### Role synchronization
+
+When an admin changes a role, for example:
+
+```powershell
+indraq user update nitin --role manager
+```
+
+IndraQ reconciles linked providers before committing the Cloud role:
+
+```mermaid
+flowchart LR
+    C[Role change requested] --> AWS[AWS policies]
+    AWS --> NPM[NPM role]
+    NPM --> JD[Jenkins DEV]
+    JD --> JP[Jenkins PROD]
+    JP --> CLOUD[IndraQ Cloud role · LAST]
+    AWS -. failure .-> RB[Best-effort rollback]
+    NPM -. failure .-> RB
+    JD -. failure .-> RB
+    JP -. failure .-> RB
+```
+
+If an external role update fails, the Cloud role is not committed and already-changed external providers are rolled back on a best-effort basis.
+
+### Permanent deletion in v2.0
+
+> [!WARNING]
+> `indraq user delete` is a **real delete**, not a soft-disable command. Use it only when the person should be removed from the organization.
+
+Deletion follows this order:
+
+```mermaid
+flowchart LR
+    U[User delete] --> AWS[AWS identity]
+    AWS --> NPM[NPM identity]
+    NPM --> JD[Jenkins DEV if configured]
+    JD --> JP[Jenkins PROD if configured]
+    JP --> C[Cloud identity · LAST]
+    C --> KEEP[Projects / DNS / proxy / GHCR / Jenkins jobs remain]
+```
+
+Important v2.0 behavior:
+
+- If the Cloud identity is selected for hard deletion, IndraQ automatically expands cleanup to linked managed AWS/NPM identities and to every configured Jenkins controller. You cannot accidentally hard-delete Cloud while leaving a known managed Jenkins identity behind.
+- Jenkins cleanup does **not** depend only on an old Cloud mapping; every Jenkins controller currently configured for the administrator is checked.
+- A Jenkins username that is already absent counts as success.
+- If an old release left a Jenkins identity behind, a later `user create` can reconcile that stale identity instead of being blocked by "user already exists".
+- Cloud deletion is last. If an external provider genuinely fails, the Cloud identity is retained so cleanup can be retried safely.
+- Project ownership/configuration is preserved or reassigned; user-specific memberships and grants are removed with the identity.
+
+---
+
+## D. Project membership and inherited access
+
+In v2.0, **project membership is the primary project-access boundary**. Adding a user to a project grants all resources that already belong to that project, then synchronizes provider-native permissions where the provider supports safe per-user scoping.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq project add user` | **Manager/admin:** add a user to a project and inherit all existing project resource grants. AWS/Jenkins native access is synchronized immediately. |
+| `indraq project delete user` | Remove project membership, delete that project's resource grants and resynchronize AWS/Jenkins permissions. |
+| `indraq access add user` | Optional granular override: grant only selected project resources instead of relying on full project inheritance. |
+| `indraq access delete user` | Revoke selected resource grants without removing the user from the whole project. |
+
+```mermaid
+flowchart TD
+    A[project add user] --> M[Cloud project membership]
+    M --> G[Grant all current project resources]
+    G --> AWS[AWS scoped IAM policy]
+    G --> J[Jenkins item roles]
+    G --> N[NPM project grant in IndraQ]
+    G --> H[GHCR project grant in IndraQ]
+    J --> D[User can run project pipelines]
+    D --> H2[Jenkins uses project GHCR credential]
+```
+
+> [!NOTE]
+> AWS and Jenkins support safe native per-user project scoping, so IndraQ applies it automatically. Nginx Proxy Manager does not offer a safe per-proxy multi-owner ACL, and GHCR direct local push/pull requires the user's own GitHub/GHCR token. IndraQ therefore records those project grants without leaking an administrator credential or changing NPM visibility to `all`. Jenkins deployments can still use the project's stored GHCR credential.
+
+Use `project delete user` when the person stays in the organization but should lose the entire project. Use `user delete` only when the person should be removed everywhere.
+
+---
+
+## E. Project lifecycle
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq init [directory]` | Safely create a new application and IndraQ project setup. Use `--skip-install` when you want files generated without dependency installation. |
+| `indraq project create [name]` | Register an **existing current folder** as a new Cloud project without scaffolding or infrastructure changes. |
+| `indraq project list` | List organization projects and your VIEW/WRITE access. |
+| `indraq project link` | Link/re-link the current folder to an existing accessible Cloud project. |
+| `indraq project sync` | Migrate older local IndraQ metadata to the Cloud model and keep the local project reference minimal. |
+| `indraq project status` | Show the current Cloud project and infrastructure associations, optionally for an environment. |
+| `indraq dockerfile create` | Generate Docker support for an existing project without running the full `init` workflow. |
+
+### `indraq init`
+
+Use this for a **new project**, not to overwrite a populated application accidentally.
+
+The wizard can create supported frontend, backend, full-stack and mobile structures, environment files, ignore files and Docker support. Framework/version choices are collected interactively. Dependency installation can be skipped:
+
+```powershell
+indraq init my-service --skip-install
+```
+
+### `indraq project create`
+
+Use this when code already exists and only Cloud registration is needed:
+
+```powershell
+indraq project create cloud-api --kind backend --framework express --port 4010 --health /health
+```
+
+It does **not** scaffold source code, run `npm install`, or automatically create DNS/proxy/Jenkins infrastructure.
+
+### `indraq dockerfile create`
+
+Common flags include:
+
+```text
+--framework <framework>
+--node-version <version>
+--output <directory>
+--port <port>
+--health <endpoint>
+--compose
+--force
+```
+
+---
+
+## F. Infrastructure reconciliation and deployment
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq prebuild` | Main web-infrastructure reconciliation command for GHCR, Route53, NPM and Jenkins. Run before first deployment and after infrastructure changes. |
+| `indraq deployment create` | Deployment-oriented entry point to the prebuild/reconciliation flow. |
+| `indraq deployment run --env <name>` | Run the configured deployment for a shared environment. |
+| `indraq deploy build --env <name>` | Build Docker image, push it and run the Jenkins deployment. Primary explicit deploy command. |
+| `indraq deploy configure` | Open the main configuration home from the deploy namespace. |
+| `indraq deploy:configure` | Legacy/top-level alias for configuration. |
+| `indraq deploy:dev` | Shortcut for deployment using the `dev`/development shared environment. |
+| `indraq deploy:prod` | Shortcut for deployment using the `prod`/production shared environment. |
+
+Useful prebuild flags:
+
+```text
+--env <environment>
+--secondary-env <environment>
+--routing SIMPLE|FAILOVER|WEIGHTED|LATENCY
+--host-port <port>
+--networks <list>
+--volumes <list>
+--flags <flags>
+--yes
+```
+
+Example failover preparation:
+
+```powershell
+indraq prebuild --env production --secondary-env production-backup --routing FAILOVER
+```
+
+The purpose of prebuild is **reconciliation**, not blind creation. It should discover what already exists and create/update what the project requires.
+
+---
+
+## G. Jenkins: pipelines, deployments and users
+
+Jenkins commands use the Jenkins credentials stored in the authenticated user's IndraQ Cloud profile.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq jenkins pipelines` | List all buildable jobs/pipelines visible to the Jenkins account, including jobs in folders. No default 10-job cap when `--limit` is omitted. |
+| `indraq jenkins run [job]` | Select/run any visible pipeline. IndraQ discovers its Jenkins parameters and prompts for values. |
+| `indraq jenkins pipeline:run [job]` | Long-form alias of `jenkins run`. |
+| `indraq jenkins create-deployment` | Trigger only the Jenkins `CREATE-DEPLOYMENT` workflow for a component; it does not create Route53/NPM resources. |
+| `indraq jenkins deployments` | List Jenkins deployment jobs. |
+| `indraq jenkins deployment:update [job]` | Reconcile a deployment through `CREATE-DEPLOYMENT`. |
+| `indraq jenkins deployment:delete [job]` | Delete a Jenkins deployment job after confirmation. |
+| `indraq jenkins users` | List Jenkins users visible to the configured admin-capable identity. |
+| `indraq jenkins user:update [username]` | Update a Jenkins user's password/roles directly. Unified organization role changes should normally use `indraq user update`. |
+| `indraq jenkins user:delete [username]` | Delete a Jenkins user directly. Unified organization deletion should normally use `indraq user delete`. |
+
+Choose Jenkins environment explicitly when useful:
+
+```powershell
+indraq jenkins pipelines --stage dev
+indraq jenkins pipelines --stage prod
+```
+
+### Run any Jenkins pipeline
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as IndraQ CLI
+    participant J as Jenkins
+    U->>C: indraq jenkins run
+    C->>J: Discover visible jobs
+    J-->>C: Jobs + parameter definitions
+    C-->>U: Prompt required / optional parameters
+    U->>C: Values
+    C->>J: Trigger build
+    J-->>C: Queue / build status
+    C-->>U: Result
+```
+
+Interactive selection:
+
+```powershell
+indraq jenkins run
+```
+
+Direct job name:
+
+```powershell
+indraq jenkins run api-admin-service --stage dev
+```
+
+Folder jobs are supported using their full job path when visible.
+
+IndraQ inspects the job's parameter definitions. Parameters with a usable Jenkins default are shown as **optional**; parameters without one are treated as **required**. Boolean, choice, password, text and string parameters get appropriate prompts.
+
+By default the CLI waits for completion. To queue and return immediately:
+
+```powershell
+indraq jenkins run api-admin-service --stage dev --no-wait
+```
+
+### Create only a Jenkins deployment
+
+Use this when DNS and proxy already exist or you intentionally want Jenkins only:
+
+```powershell
+indraq jenkins create-deployment --stage dev --component backend --image-name api-service --host-port 5010
+```
+
+Common optional deployment fields include networks, volumes and Docker flags.
+
+---
+
+## H. AWS IAM and managed access keys
+
+IndraQ IAM users are designed for CLI/API access. Console login is intentionally not part of the IAM-user flow.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq iam users` | List AWS IAM users. |
+| `indraq iam user:create [username]` | Create an IAM user and normally an access key; optional managed policy ARNs can be attached. |
+| `indraq iam user:update [username]` | Update attached managed policies for an IAM user. |
+| `indraq iam user:delete [username]` | Delete an IAM user and removable dependencies after confirmation. |
+| `indraq iam credentials [username]` | Reveal the authenticated user's own IndraQ-managed AWS access key/secret stored encrypted in Cloud. |
+| `indraq iam access-key rotate [username]` | Rotate an IndraQ-managed IAM access key safely; manager/admin can select managed organization users when authorized. |
+
+Examples:
+
+```powershell
+indraq iam users --all
+indraq iam user:create nitin
+indraq iam credentials nitin
+indraq iam access-key rotate nitin --reason "Quarterly credential rotation"
+```
+
+AWS does not reveal an old secret access key again after creation. For AWS identities created through the managed IndraQ workflow, the generated secret can be stored encrypted in IndraQ Cloud so the owner can retrieve it later through the authorized CLI command.
+
+During rotation, IndraQ creates/stores the replacement managed key before removing the previous managed key so the recovery record does not point to a key that was never successfully created.
+
+---
+
+## I. Route53 DNS and health checks
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq dns zones` | List Route53 hosted zones available to the configured AWS identity. |
+| `indraq dns records` | List records in a hosted zone. Use `--zone` when scripting. |
+| `indraq dns create [record]` | Create a Route53 record interactively or with flags. |
+| `indraq dns update [record]` | UPSERT/reconcile a Route53 record. |
+| `indraq dns delete [record]` | Select/delete Route53 record set(s). |
+| `indraq healthcheck list` | List/select Route53 health checks. |
+| `indraq healthcheck create` | **Admin:** create a Route53 health check. |
+| `indraq healthcheck delete [id]` | **Admin:** delete a Route53 health check. |
+
+Supported record types exposed by the command include:
+
+```text
+A
+CNAME
+TXT
+MX
+```
+
+Supported routing choices include:
+
+```text
+SIMPLE
+FAILOVER
+WEIGHTED
+LATENCY
+```
+
+Example:
+
+```powershell
+indraq dns create api.example.com --type A --environment production --routing SIMPLE
+```
+
+Failover example:
+
+```powershell
+indraq dns create api.example.com `
+  --type A `
+  --environment production `
+  --secondary-environment production-backup `
+  --routing FAILOVER
+```
+
+```mermaid
+flowchart TB
+    DNS[api.example.com] --> R53[Route53 failover]
+    R53 -->|PRIMARY · healthy| P[production]
+    R53 -->|PRIMARY · unhealthy| S[production-backup]
+    HC[Health check] -. status .-> R53
+```
+
+Health checks are especially important for failover designs because Route53 needs a reliable signal to decide whether a primary target is healthy.
+
+---
+
+## J. Nginx Proxy Manager: proxy hosts and users
+
+### Proxy hosts
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq proxy list` | List NPM proxy hosts. |
+| `indraq proxy create [domain]` | Create a reverse proxy, with optional certificate/SSL/WebSocket settings. |
+| `indraq proxy update [domain]` | Update an existing proxy host. |
+| `indraq proxy delete [domain]` | Delete a proxy host after confirmation. |
+
+Common proxy options include:
+
+```text
+--forward-host <host>
+--environment <name>
+--forward-port <port>
+--scheme http|https
+--certificate-id <id>
+--request-ssl
+--email <email>
+--force-ssl
+--http2
+--websocket / --no-websocket
+```
+
+Example:
+
+```powershell
+indraq proxy create api.example.com --environment production --forward-port 5000 --request-ssl --force-ssl --http2
+```
+
+### NPM users
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq npm-user list` | List Nginx Proxy Manager users. |
+| `indraq npm-user create` | Create an NPM user directly. |
+| `indraq npm-user update [identity]` | Update name, nickname, email, password, role or disabled state. |
+| `indraq npm-user delete [identity]` | Delete an NPM user directly. |
+
+For organization-wide lifecycle changes, prefer `indraq user create/update/delete` so Cloud, AWS, NPM and Jenkins stay synchronized.
+
+---
+
+## K. Mobile builds
+
+Mobile build shortcuts are grouped under `indraq build`.
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq build mobile:dev` | Build the mobile development environment. |
+| `indraq build mobile:development` | Alias of `mobile:dev`. |
+| `indraq build mobile:staging` | Build the mobile staging environment. |
+| `indraq build mobile:prod` | Build the mobile production environment. |
+| `indraq build mobile:production` | Alias of `mobile:prod`. |
+
+Useful per-build overrides:
+
+```text
+--output dev-client|debug-apk|apk|aab
+--profile fast|clean|full-reset
+--verbose
+--dry-run
+--yes
+```
+
+Before a real upload/build, validate the plan when useful:
+
+```powershell
+indraq build mobile:staging --dry-run
+```
+
+Use `indraq configure` → **Mobile App settings** for the persistent mobile configuration.
+
+---
+
+## L. Audit logs
+
+| Command | Usage / importance |
+| --- | --- |
+| `indraq logs` | **Manager/admin:** view IndraQ audit activity. Supports search/limit/all filtering. |
+
+Example:
+
+```powershell
+indraq logs --search user.role --all
+```
+
+Audit logs are important when diagnosing who changed user roles, project access or infrastructure and why.
+
+---
+
+# Common real-world flows
+
+```mermaid
+flowchart TD
+    Q{What are you doing?}
+    Q -->|New person| U[user create → project add user]
+    Q -->|Role change| R[user update --role]
+    Q -->|Remove person| X[user delete]
+    Q -->|New infrastructure| P[prebuild]
+    Q -->|Deploy code| D[deploy build]
+    Q -->|Run Jenkins job| J[jenkins run]
+```
+
+| Goal | Recommended commands |
+| --- | --- |
+| Add a developer | `user create` → `project add user` (existing project resources are inherited automatically) |
+| Promote/demote a person | `user update <name> --role manager|user` |
+| Remove a person permanently | `user delete <name>` |
+| Register an existing app | `project create` → `configure` → `prebuild` |
+| Connect a checked-out repo | `project link` → `project status` |
+| First web deployment | `prebuild --env <name>` → `deploy build --env <name>` |
+| Later web deployment | `deploy build --env <name>` |
+| Run an arbitrary Jenkins job | `jenkins pipelines` → `jenkins run` |
+| Remove only project/resource access | `project delete user` / `access delete user` |
+
+Use unified user commands for organization lifecycle changes. Direct AWS/NPM/Jenkins user commands are useful for provider-specific administration, but changing only one provider can intentionally create a state that differs from the IndraQ organization identity.
+
+---
+
+# Security model
+
+IndraQ automates privileged systems, so convenience must not come at the cost of uncontrolled credentials.
+
+| Area | Design |
+| --- | --- |
+| Cloud login | Authenticated session stored for the CLI rather than re-entering passwords for every command |
+| Provider credentials | Stored per IndraQ user in Cloud rather than in each project repository |
+| Encryption | Sensitive reusable provider secrets use the Cloud `MASTER_KEY` for encrypted-at-rest storage |
+| AWS managed keys | Secret access keys created through the managed workflow can be retained encrypted for authorized recovery/rotation |
+| Project access | VIEW/WRITE and resource grants control who can change project infrastructure |
+| Role updates | External linked providers are reconciled before the Cloud role is finalized |
+| User deletion | AWS/NPM/Jenkins cleanup happens before permanent Cloud deletion; project configuration is retained |
+| Auditing | Sensitive manager/admin actions require/record reasons where the API enforces them |
+
+Never commit `.env` files containing real secrets, AWS credentials, Jenkins tokens, NPM passwords or GHCR tokens to Git.
+
+Keep the Cloud `MASTER_KEY` stable. Changing or losing it after encrypted credentials are stored makes those existing encrypted values unreadable.
+
+---
+
+# Troubleshooting
+
+| Symptom | First checks |
+| --- | --- |
+| `indraq` is not found | Run `npm run build`, `npm link` (development), open a new terminal, then `indraq doctor` |
+| Provider credentials are missing | `indraq provider list`, then `indraq provider configure <provider>` |
+| Jenkins crumb/authorization error | Confirm the correct `--stage` and that the stored Jenkins account has enough permission for that operation |
+| Jenkins host port is busy | Choose another validated/suggested free host port before deployment creation |
+| `prebuild` cannot reconcile resources | Check `whoami` → `project status` → `provider list` → `environment list`, then rerun |
+| Unified deletion stops on a provider | Repair the genuine provider failure and retry; Cloud deletion is retained until external cleanup can complete |
+
+For command syntax, use `indraq <command> --help` rather than guessing flags.
+
+---
+
+# Platform operator: IndraQ Cloud API
+
+Most CLI users can skip this section. The team operating `api.indraq.com` should use `cloud-api/README.md` as the detailed server guide.
+
+The Cloud API requires Node.js 22+, PostgreSQL, a strong `JWT_SECRET`, a persistent 64-hex-character `MASTER_KEY`, bootstrap-admin credentials for first startup, and SMTP when email password reset is enabled.
+
+```powershell
+cd cloud-api
+npm install
+Copy-Item .env.example .env
+npm run build
+npm start
+```
+
+Numbered SQL migrations in `cloud-api/sql/` run automatically at API startup. Do not casually replace `MASTER_KEY`; existing encrypted provider secrets depend on it.
+
+More implementation detail:
+
+```text
+cloud-api/README.md
+docs/ARCHITECTURE.md
+```
+
+---
+
+# Before publishing a CLI release
+
+Run the complete verification sequence:
+
+```powershell
+npm install
+npm run build
+npm test
+npm pack --dry-run
+```
+
+Inspect `npm pack --dry-run` before publishing. The package should contain the files required at runtime and must not contain private `.env` files, tokens, credentials or unrelated development artifacts.
+
+Test the actual tarball when making a significant release:
+
+```powershell
+npm pack
+npm install -g .\indraq_cli-<version>.tgz
+indraq --version
+indraq doctor
+indraq --help
+```
+
+Then publish only after the packaged build behaves correctly:
+
+```powershell
+npm publish --dry-run
+npm publish
+```
+
+---
+
+# Where to go next
+
+For day-to-day usage, these four commands cover most questions:
+
+```powershell
+indraq --help
+indraq configure
+indraq project status
+indraq prebuild
+```
+
+For deployments:
+
+```powershell
+indraq deploy build --env <environment>
+```
+
+For Jenkins automation:
+
+```powershell
+indraq jenkins pipelines
+indraq jenkins run
+```
+
+For exact flags on anything:
+
+```powershell
+indraq <command> --help
+```
+
+---
+
+# License
+
+MIT © IndraQ Innovations
+
+---
+
+<div align="center">
+  <img src="docs/assets/indraq-mark.png" alt="IndraQ Mark" width="54" />
+  <p><strong>Built and maintained by IndraQ Innovations.</strong></p>
+  <sub>Automate the repetitive work. Keep infrastructure predictable.</sub>
+</div>