docs: add step-by-step setup guide and end-to-end testing guide

- setup-guide.md: linear numbered setup from zero to running across all three
  modes (dev hot-reload, full Docker, production HTTPS); includes Ubuntu install
  commands, secret generation, migration, verification checks, and troubleshooting table
- testing-guide.md: complete feature-by-feature test checklist covering auth,
  AWS account connection, scan engine, dashboard, compliance, PDF export (both
  client and server-side), alert system, and security verification (credential
  exposure, Swagger disabled, rate limiting, HTTPS redirect); includes
  pre-test checklist, AWS CLI cross-check commands, pass/fail criteria for
  every test, cleanup steps, and a sign-off checklist
- README.md: add both new docs to documentation index with updated role routing

Author: Anilk880

README.md

@@ -59,16 +59,20 @@ A Cloud Security Posture Management (CSPM) SaaS platform that continuously audit
 
 | Document | Audience | Purpose |
 |---|---|---|
-| [`docs/architect-delivery-guide.md`](docs/architect-delivery-guide.md) | **Architect / delivery lead** | Non-technical overview: what to configure, how to onboard a client AWS account, how to deliver the service, end-to-end workflow, local Ubuntu testing guide |
-| [`docs/user-manual.md`](docs/user-manual.md) | **Operator / power user** | Complete reference for every feature: environment variables, running scans, compliance reports, PDF export, alert system, API endpoints, data model, troubleshooting |
+| [`docs/setup-guide.md`](docs/setup-guide.md) | **Everyone** | Step-by-step from zero to running: prerequisites, install, configure, start (dev, Docker, and production modes) |
+| [`docs/testing-guide.md`](docs/testing-guide.md) | **Everyone** | Step-by-step end-to-end test of every feature using a real AWS account; includes security verification and sign-off checklist |
+| [`docs/architect-delivery-guide.md`](docs/architect-delivery-guide.md) | **Architect / delivery lead** | Non-technical overview: what to configure, how to onboard a client AWS account, how to deliver the service, end-to-end workflow |
+| [`docs/user-manual.md`](docs/user-manual.md) | **Operator / power user** | Complete feature reference: environment variables, scanning, compliance, PDF export, alert system, API endpoints, data model, troubleshooting |
 | [`docs/technical-concept-document.md`](docs/technical-concept-document.md) | **Developer** | Build phase history, architecture decisions, what was delivered in each phase, and the roadmap for upcoming phases |
-| [`docs/architecture.md`](docs/architecture.md) | **Developer** | System architecture diagrams and component interactions |
+| [`docs/architecture.md`](docs/architecture.md) | **Developer** | System architecture diagrams, component interactions, security design |
 | [`README.md`](README.md) | **Everyone** | Quick start — stack overview, repo layout, local dev commands, Docker stack, API endpoint list |
 
-> **Starting point by role:**
-> - Delivering to a client? → Start with `architect-delivery-guide.md`
-> - Setting up or operating the platform? → Start with `user-manual.md`
-> - Contributing to or extending the code? → Start with `technical-concept-document.md`
+> **Start here:**
+> - First time setting up? → `setup-guide.md`
+> - Verifying features work? → `testing-guide.md`
+> - Delivering to a client? → `architect-delivery-guide.md`
+> - Looking up a specific feature? → `user-manual.md`
+> - Contributing code? → `technical-concept-document.md`
 
 ## Prerequisites
 

docs/setup-guide.md

@@ -0,0 +1,342 @@
+# CSPM Platform — Step-by-Step Setup Guide
+
+**Audience:** Anyone setting up this platform for the first time — local developer, tester, or architect doing a local proof-of-concept  
+**Time required:** 20–30 minutes for local dev; 45–60 minutes for production  
+**Last updated:** 2026-06-14
+
+---
+
+## Before You Start — Choose Your Mode
+
+| Mode | When to use | What you get |
+|---|---|---|
+| **A — Local Dev** | Development, debugging, first look | HTTP on port 3000, hot reload, no TLS |
+| **B — Full Docker (local)** | Testing the Docker stack without HTTPS | HTTP on port 3000, all services containerised |
+| **C — Production** | Real deployment, client delivery | HTTPS on port 443, network isolation, Redis auth |
+
+> **For your first run and AWS scan testing → use Mode A or B.**  
+> Mode C requires a TLS certificate and domain. See Section 3 for production.
+
+---
+
+## Section 1 — Prerequisites
+
+### 1.1 Install required software (Ubuntu)
+
+```bash
+# Docker (includes Docker Compose)
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+newgrp docker                     # apply group without logging out
+
+# Verify Docker
+docker --version                  # expect: Docker version 24+
+docker compose version            # expect: Docker Compose version v2.20+
+
+# Node.js 20 via nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+source ~/.bashrc
+nvm install 20
+nvm use 20
+node --version                    # expect: v20.x.x
+
+# pnpm
+npm install -g pnpm@9
+pnpm --version                    # expect: 9.x.x
+
+# Python 3.12
+sudo apt update
+sudo apt install -y python3.12 python3.12-venv python3-pip
+python3.12 --version              # expect: Python 3.12.x
+```
+
+### 1.2 AWS CLI (needed to create the IAM audit role)
+
+```bash
+curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
+unzip /tmp/awscliv2.zip -d /tmp
+sudo /tmp/aws/install
+aws --version                     # expect: aws-cli/2.x.x
+
+# Configure your AWS credentials
+aws configure
+# Enter: Access Key ID, Secret Access Key, default region (e.g. us-east-1), output format (json)
+```
+
+---
+
+## Section 2 — Local Setup (Mode A and B)
+
+### 2.1 Clone the repository
+
+```bash
+git clone <repo-url> CSPM-SaaS
+cd CSPM-SaaS
+```
+
+### 2.2 Install dependencies
+
+```bash
+# Web frontend and shared TypeScript package
+pnpm install
+
+# Python API
+pip install -r apps/api/requirements.txt
+```
+
+Expected output for `pnpm install`: packages downloaded, `node_modules` created  
+Expected output for pip install: all packages installed with no errors
+
+### 2.3 Generate secrets
+
+Run each command and copy the output — you will paste these into `.env` in the next step.
+
+```bash
+echo "JWT_SECRET=$(openssl rand -hex 32)"
+echo "JWT_REFRESH_SECRET=$(openssl rand -hex 32)"
+echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"
+```
+
+> **Important:** All three values must be different. Save them somewhere safe.  
+> If you ever change `ENCRYPTION_KEY` after connecting AWS accounts, all credentials become unreadable.
+
+### 2.4 Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and replace the placeholder values:
+
+```bash
+# Paste the generated secrets from step 2.3
+JWT_SECRET=<paste here>
+JWT_REFRESH_SECRET=<paste a different value here>
+ENCRYPTION_KEY=<paste here>
+
+# These are correct as-is for local Docker setup — do not change them
+DATABASE_URL="postgresql://cspm:cspm@localhost:5432/cspm"
+REDIS_URL="redis://localhost:6379"
+NEXT_PUBLIC_API_URL="http://localhost:4000"
+NODE_ENV="development"
+```
+
+**Verify:** `.env` has no remaining placeholder text like `replace-with-...`
+
+### 2.5 Start the database and Redis
+
+```bash
+docker compose -f infra/docker-compose.yml up -d postgres redis
+```
+
+Wait 10 seconds, then verify both containers are healthy:
+
+```bash
+docker compose -f infra/docker-compose.yml ps
+```
+
+Expected: Both `cspm-postgres` and `cspm-redis` show status `healthy`.
+
+### 2.6 Apply database migrations
+
+```bash
+make migrate
+```
+
+Expected output: `INFO  [alembic.runtime.migration] Running upgrade -> ...`  
+If you see `alembic upgrade head` complete with no errors, the schema is ready.
+
+### 2.7 Choose how to start
+
+#### Mode A — Development (hot reload)
+
+Open **two terminals** in the project root:
+
+**Terminal 1:**
+```bash
+make dev
+```
+Expected: FastAPI starts on port 4000, Next.js starts on port 3000. Both show startup messages.
+
+**Terminal 2:**
+```bash
+make worker
+```
+Expected: `celery@... ready.` — worker is waiting for scan jobs.
+
+#### Mode B — Full Docker stack
+
+```bash
+make up
+```
+Expected: All 5 containers (postgres, redis, api, worker, web) start and become healthy.  
+Check with: `docker compose -f infra/docker-compose.yml ps`
+
+### 2.8 Verify the platform is running
+
+```bash
+# API health check
+curl http://localhost:4000/health
+# Expected: {"status":"ok","service":"cspm-api"}
+
+# Web frontend
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
+# Expected: 200
+```
+
+Open `http://localhost:3000` in your browser. You should see the login page.
+
+---
+
+## Section 3 — Production Setup (Mode C)
+
+### 3.1 Prerequisites for production
+
+- A TLS certificate and private key for your domain
+- Your domain DNS pointing to the server
+- Docker installed on the server (see Section 1.1)
+
+### 3.2 Generate a self-signed certificate (local HTTPS testing only)
+
+Skip this if you have a real certificate (e.g. Let's Encrypt).
+
+```bash
+openssl req -x509 -newkey rsa:4096 \
+  -keyout /tmp/cspm-key.pem \
+  -out /tmp/cspm-cert.pem \
+  -days 365 -nodes \
+  -subj '/CN=localhost'
+```
+
+### 3.3 Configure production environment
+
+```bash
+cp .env.prod.example .env.prod
+```
+
+Fill in `.env.prod`:
+
+```bash
+# Generate all secrets
+echo "JWT_SECRET=$(openssl rand -hex 32)"
+echo "JWT_REFRESH_SECRET=$(openssl rand -hex 32)"
+echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"
+echo "POSTGRES_PASSWORD=$(openssl rand -hex 16)"
+echo "REDIS_PASSWORD=$(openssl rand -hex 16)"
+```
+
+Paste the generated values into `.env.prod`. Also set:
+
+```
+POSTGRES_USER=cspm
+POSTGRES_DB=cspm
+API_IMAGE=cspm-api:latest
+WEB_IMAGE=cspm-web:latest
+NODE_ENV=production
+CORS_ORIGIN=https://yourdomain.com        # or https://localhost for self-signed testing
+NEXT_PUBLIC_API_URL=http://api:4000       # internal — do not change
+
+# Paths to your TLS files
+SSL_CERT_PATH=/tmp/cspm-cert.pem          # or /etc/letsencrypt/live/yourdomain.com/fullchain.pem
+SSL_KEY_PATH=/tmp/cspm-key.pem            # or /etc/letsencrypt/live/yourdomain.com/privkey.pem
+```
+
+### 3.4 Update nginx domain (optional)
+
+If you have a real domain, edit `infra/nginx/nginx.prod.conf` and replace the two `server_name _;` lines with your domain:
+
+```nginx
+server_name cspm.yourdomain.com;
+```
+
+For self-signed / IP access, leave `server_name _;` (catch-all).
+
+### 3.5 Build Docker images
+
+```bash
+make prod-build
+```
+
+Expected: Two Docker images built — `cspm-api:latest` and `cspm-web:latest`.  
+Build time: 3–8 minutes depending on internet speed and machine.
+
+### 3.6 Start the production stack
+
+```bash
+make prod-up
+```
+
+Expected: All 6 containers start (postgres, redis, api, worker, web, nginx).
+
+### 3.7 Apply database migrations
+
+```bash
+make prod-migrate
+```
+
+Expected: Alembic migrations applied. Run only once (or when you update the code).
+
+### 3.8 Verify production is running
+
+```bash
+# Health check through nginx
+curl -k https://localhost/health
+# Expected: healthy
+
+# HTTP → HTTPS redirect
+curl -v http://localhost/ 2>&1 | grep "< HTTP\|Location"
+# Expected: HTTP/1.1 301 ... Location: https://...
+```
+
+Open `https://localhost` in your browser. Accept the self-signed certificate warning if using a test cert.
+
+---
+
+## Section 4 — First Login
+
+1. Open the platform in your browser (`http://localhost:3000` for dev, `https://yourdomain.com` for prod)
+2. Click **Register** (or navigate to `/register`)
+3. Fill in:
+   - **Organisation name:** your company name or a test label (e.g. "Test Org")
+   - **Your name:** your display name
+   - **Email:** your email address
+   - **Password:** at least 8 characters
+4. Click **Create account**
+5. You are automatically logged in and redirected to the Dashboard
+
+> The first user registered becomes the **Admin** of that organisation.
+
+---
+
+## Section 5 — Quick Troubleshooting
+
+| Symptom | Check | Fix |
+|---|---|---|
+| API won't start — secret error | Error message in terminal | See error table in `docs/user-manual.md` Section 21 |
+| `http://localhost:3000` doesn't load | Is `make dev` or `make up` running? | Re-run the start command |
+| Dashboard shows no data | No scan run yet | Connect an AWS account and run a scan (see testing guide) |
+| Scan stays PENDING | Celery worker not running | Run `make worker` in a separate terminal |
+| `alembic upgrade head` fails | Postgres not running | Run `docker compose -f infra/docker-compose.yml up -d postgres` first |
+| Docker build fails (web) | pnpm lock mismatch | Run `pnpm install` locally first, then `make prod-build` |
+| Port 3000 or 4000 already in use | Another process | `lsof -i :3000` or `lsof -i :4000` to find and kill it |
+
+---
+
+## Section 6 — Stopping the Platform
+
+```bash
+# Dev stack
+make down
+
+# Production stack
+make prod-down
+
+# Stop only databases (keep data)
+docker compose -f infra/docker-compose.yml stop postgres redis
+```
+
+---
+
+## What's Next
+
+Once the platform is running, follow **`docs/testing-guide.md`** to verify every feature works end-to-end, including a real AWS scan.