grada-run 0.0.2 → 0.32.0

package/apps/docs/src/content/docs/guides/docker-compose.md

@@ -0,0 +1,37 @@
+---
+title: Docker Compose Support
+description: How grada maps docker-compose.yml services to ECS — web-service selection, ports, env vars, and sidecars.
+sidebar:
+  order: 5
+---
+
+If your repo contains a Compose file (`docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, or `compose.yaml`), setup parses it (`src/utils/dockerCompose.js`) and translates its services into the ECS task definition. Your Compose file keeps working locally, and these are the exact mapping rules that decide what runs in AWS.
+
+## File discovery
+
+Only the repo root is checked, trying `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, then `compose.yaml` in order — the first file found wins. A file with no `services` key — or one that fails YAML parsing — is treated as absent (a warning is printed, setup continues), so a stray or malformed file never blocks generation.
+
+## Which service is "web"
+
+The service used as the ECS web service is the **first service with an exposed port**; if none exposes a port, the first service listed wins. Every other service becomes an ECS **sidecar** in the same task definition. Structure your file accordingly: the publicly reachable app must be the port-exposing service.
+
+## Port mapping
+
+The container port is taken from the **last segment of the first port entry** — `"8080:80"` and `"127.0.0.1:8001:8001"` both resolve to the right-hand value (`80` and `8001`). Only the first entry is read, and any non-numeric characters are stripped. This port overrides the configured container port during setup, and the ALB health check targets it.
+
+## Environment and command injection
+
+- **Environment** supports both Compose styles: `environment:` as a mapping is used as-is; as a list (`- KEY=value`) each entry is split on the first `=`.
+- The web service's variables are injected directly into the ECS task definition, and its `command` overrides the container start command — but only when no `Procfile` `web:` process already set one (`Procfile` wins; see [Dockerfiles](/grada/guides/dockerfiles/)).
+- Sidecars get the same treatment: their environment is injected, their `command` is preserved, a missing `image` defaults to `alpine:latest`, and each sidecar logs to the shared CloudWatch log group under an `ecs-<service>` stream prefix.
+
+## What this means in practice
+
+- Sidecars (Redis, Memcached, background helpers) run **in the same task** as the web container and share its lifecycle — this is co-location, not separate services.
+- Compose `build:` contexts are not used in AWS; the image is built from the generated `Dockerfile` by the [CI/CD pipeline](/grada/guides/cicd-pipeline/).
+- Runtime secrets still belong in AWS Secrets Manager, not in Compose `environment:`. See [Secrets Management](/grada/guides/secrets-management/).
+
+## See also
+
+- [Supported Frameworks](/grada/guides/frameworks/) for detection and defaults.
+- [Dockerfiles & the container contract](/grada/guides/dockerfiles/) for runtime requirements.

package/apps/docs/src/content/docs/guides/dockerfiles.md

@@ -0,0 +1,46 @@
+---
+title: Dockerfiles & the Container Contract
+description: What your app must do at runtime (port, bind address, health check) and the per-framework prerequisites.
+sidebar:
+  order: 4
+---
+
+Setup generates a framework-specific Alpine multi-stage `Dockerfile` engineered for zero Critical/High CVEs. Your app only needs to honor a small runtime contract — plus a few per-framework prerequisites printed as warnings (`src/utils/warnings.js`) at the end of setup.
+
+## The container contract
+
+Every generated image assumes three things. Violating any of them is the most common cause of failing ALB health checks after an otherwise successful `apply`:
+
+1. **Listen on `$PORT`.** The container must serve traffic on the port baked in as `{{PORT}}` (default per framework — see [Supported Frameworks](/grada/guides/frameworks/)).
+2. **Bind `0.0.0.0`, not `localhost`.** Localhost-bound apps are unreachable inside ECS networking and Docker.
+3. **Answer the health check with `200 OK`.** The ALB polls your health-check path (default `/`) and accepts any `2xx–3xx` status; anything outside that range marks the task unhealthy and the pipeline's new deployment never stabilizes.
+
+## Per-framework prerequisites
+
+| Framework | What setup warns you about |
+| --------- | -------------------------- |
+| NestJS | Bind `0.0.0.0` in `src/main.ts`: `await app.listen(process.env.PORT ?? 3000, '0.0.0.0')` |
+| Next.js | Set `output: 'standalone'` in your Next config and create a health-check route (copy-paste code is in the generated README's "Critical Application Prerequisites") |
+| Node.js / Express | A `start` script in `package.json` (e.g. `"start": "node index.js"`) and `0.0.0.0` binding |
+| Python (FastAPI) | Web framework in `requirements.txt`, `0.0.0.0` binding, and a health-check route returning `200 OK` |
+| Rails | Your default `Dockerfile` is backed up to `Dockerfile.bak` and replaced with the Alpine build; if you use SQLite locally but provisioned RDS, add the `pg` gem |
+| Static sites | Output folder defaults to `/app/dist` — if your framework emits `build/` or `out/`, update the `COPY` command; ensure a `build` script exists (e.g. `vite build`) |
+
+Warnings are skipped with `--preconfigured` and for `static` projects whose build directory was auto-detected.
+
+## What command runs your app
+
+The container's start command is resolved in this order:
+
+1. `Procfile` `web:` command, if a `Procfile` exists (a `worker:` process additionally generates `worker.tf`, i.e. a second ECS service that doubles Fargate cost).
+2. Otherwise the `command` of the `docker-compose.yml` web service, if one exists.
+3. Otherwise the default `CMD` in the generated `Dockerfile`.
+
+## Keeping images lean
+
+Setup writes a `.dockerignore` excluding `.git/`, `terraform/`, state files, and `.env`, and appends Terraform entries to an existing `.gitignore`. Never commit `.env` — runtime secrets come from AWS Secrets Manager (see [Secrets Management](/grada/guides/secrets-management/)).
+
+## See also
+
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for how the image is built and rolled out.
+- [diagnose](/grada/cli/diagnose/) for reading ECS failure output when the contract is broken.

package/apps/docs/src/content/docs/guides/ephemeral-pr-previews.md

@@ -0,0 +1,39 @@
+---
+title: "Ephemeral PR Previews"
+description: "Spin up isolated temporary AWS environments for every pull request."
+sidebar:
+  order: 8
+---
+
+When enabled, `grada` automatically configures your GitHub Actions pipeline to spin up isolated, temporary AWS environments every time a developer opens a Pull Request.
+
+A bot will comment on the PR with a live URL (e.g., `http://pr-123-your-app...`), allowing your team to test features, UI changes, and API updates before merging to `main`. When the PR is closed or merged, the environment is automatically destroyed.
+
+### 🏗️ How it Works
+
+Under the hood, `grada` utilizes **Terraform Workspaces**. 
+
+When a PR is opened, Terraform creates a new workspace (e.g., `pr-12`). It provisions a completely isolated Application Load Balancer and ECS Fargate Task using the exact same infrastructure definitions as your production environment, ensuring 100% parity. On `--target lambda` projects the same workspace model provisions an isolated function and API Gateway per PR instead, deploys the PR-tagged image to it, and comments the preview API Gateway URL — same open-and-teardown lifecycle, no ALB per PR.
+
+To save time and simplify architecture, PR environments **share** your production AWS Secrets Manager vault and ECR Image Repository.
+
+### ⚖️ The Rule of Thumb: Should I enable this?
+
+**✅ Enable PR Previews if:**
+* You are working on a team of 2+ developers and require visual QA or UX sign-off before merging code.
+* You are building a frontend application or full-stack monolith where seeing the live UI is critical.
+
+**❌ Do NOT enable PR Previews if:**
+* You are a solo developer (you can just test locally).
+* You have a massive volume of PRs (e.g., automated Dependabot updates). Spinning up an AWS Load Balancer takes ~3 minutes, which will slow down rapid automated merges.
+
+### 💰 AWS Cost Implications
+
+Because PR previews provision a real Application Load Balancer (ALB) and ECS Fargate compute tasks, **they are not free.**
+
+* **Compute:** You are charged standard AWS Fargate rates per minute while the PR environment is running.
+* **Load Balancing:** AWS charges ~$16/month per active Load Balancer. If a PR is open for 2 days, you pay the prorated ALB cost for those 48 hours (~$1.00).
+* **Addons:** Because [`grada add`](/grada/cli/add/) resources use `${local.app_name}`, each open PR preview workspace provisions its own isolated S3 bucket and/or DynamoDB table — accruing usage-based storage, request, and PITR charges until the PR closes and the workspace is destroyed. If you use `db:redis`, each open PR also runs its own isolated Valkey node at ~$9.49/mo (~$0.013/hr) until the PR closes, while `queue:sqs`, `ai:bedrock`, and `cron` add no fixed per-PR cost (each open PR runs its own copy of the schedule, billed only for Fargate seconds per invocation). Secrets Manager secrets are shared via `data` source at no extra per-PR secret cost. SES (`email:ses`) is the exception: the domain identity, DKIM, MAIL FROM, and DNS records are account-wide singletons scoped to the production workspace, so previews neither duplicate them nor delete them on teardown — preview containers simply inherit sending permission through their own task role.
+* **Custom domains:** [`domain add`](/grada/cli/domain/) resources (ACM certificate, validation, and alias records) are likewise scoped to the production workspace. PR previews serve over their own isolated `*.cloudfront.net` URL and never claim your production alias, so closing a PR cannot disturb production DNS or TLS.
+
+To keep costs low, ensure your team closes or merges Pull Requests promptly so the `teardown.yml` workflow can destroy the resources and stop the billing clock!

package/apps/docs/src/content/docs/guides/examples.md

@@ -0,0 +1,50 @@
+---
+title: Reference Implementations & Examples
+description: Example repositories demonstrating how grada handles frameworks and architectural patterns, plus ecosystem plugins and starters.
+sidebar:
+  order: 3
+---
+
+These repositories demonstrate how `grada` handles various frameworks and architectural patterns. Each example includes the auto-generated Terraform, GitHub Actions, and container configurations.
+
+## Featured migrations
+
+* **[Heroku to AWS Migration (Django)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer, demonstrating a multi-container Web and Celery Worker architecture deployed from a single codebase.
+* **[Vercel to AWS Migration (Next.js)](https://github.com/anton-codes-iac/deploy-stack-vercel-nextjs-example):** Demonstrates automatic translation of Vercel edge routing (`vercel.json`) to native AWS Application Load Balancer rules.
+* **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** Demonstrates automatic translation of local `docker-compose.yml` sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over `localhost`.
+
+## DevSecOps & security architectures
+
+* **[Zero-Secret AWS Secrets Manager Injection](https://github.com/anton-codes-iac/deploy-stack-secrets-example):** A production-grade Node.js architecture demonstrating zero-plaintext secret injection. It pushes local `.env` variables directly to AWS and maps them into ECS memory at runtime, exposing a live endpoint querying GitHub's API.
+
+## Frontend & fullstack frameworks
+
+* **[Next.js Fullstack App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
+* **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.
+* **[Create React App](https://github.com/anton-codes-iac/deploy-stack-cra-example):** Validates backward compatibility with legacy Webpack pipelines and `build/` auto-detection.
+* **[Astro Static Site](https://github.com/anton-codes-iac/deploy-stack-astro-example):** Demonstrates modern static site generation (SSG).
+* **[SvelteKit Application](https://github.com/anton-codes-iac/deploy-stack-svelte-example):** Demonstrates static adapter integration and custom output folder detection.
+* **[Nuxt 3 (SSR)](https://github.com/anton-codes-iac/deploy-stack-nuxt-example):** Demonstrates a fully server-side rendered Nuxt application using Nitro's optimized Node output.
+
+## Backend APIs & monoliths
+
+* **[Express.js API](https://github.com/anton-codes-iac/deploy-stack-express-example):** A standard Node.js backend setup.
+* **[NestJS API](https://github.com/anton-codes-iac/deploy-stack-nest-example):** A robust NestJS architecture utilizing AST code-patching and highly optimized multi-stage TypeScript builds.
+* **[Python FastAPI](https://github.com/anton-codes-iac/deploy-stack-fastapi-example):** A Python API demonstrating unprivileged port mapping.
+* **[Ruby on Rails](https://github.com/anton-codes-iac/deploy-stack-rails-example):** A production Rails 7+ setup featuring an auto-provisioned PostgreSQL database and secure `RAILS_MASTER_KEY` string-literal injection into the initial Secrets Manager placeholder.
+* **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
+* **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.
+
+---
+
+## Ecosystem plugins & starters
+
+In addition to standalone reference repositories, `grada` provides native integrations that hook directly into framework build pipelines and community template engines:
+
+* **[astro-grada](https://www.npmjs.com/package/astro-grada):** Push-button deployment plugin for Astro sites.
+* **[nuxt-grada](https://www.npmjs.com/package/nuxt-grada):** Nitro-optimized deployment integration for Nuxt 3 applications.
+* **[vite-plugin-grada](https://www.npmjs.com/package/vite-plugin-grada):** Zero-config Vite build plugin for single-page applications.
+* **[svelte-adapter-grada](https://www.npmjs.com/package/svelte-adapter-grada):** Native SvelteKit adapter producing optimized Fargate container builds.
+* **[nest-grada](https://www.npmjs.com/package/nest-grada):** Native Angular DevKit schematic for NestJS, installable via `nest add`.
+* **[cookiecutter-django-grada](https://github.com/anton-codes-iac/cookiecutter-django-grada):** Community Django starter listed on Django Packages.
+* **[cookiecutter-fastapi-grada](https://github.com/anton-codes-iac/cookiecutter-fastapi-grada):** Instant scaffolding for modern, async FastAPI deployments.

package/apps/docs/src/content/docs/guides/frameworks.md

@@ -0,0 +1,88 @@
+---
+title: Supported Frameworks & Detection
+description: Which frameworks grada detects, the signals it looks for, the valid --framework ids, and per-framework requirements.
+sidebar:
+  order: 2
+---
+
+`grada` is designed to be as "zero-config" as possible. During setup, it inspects your repo (`src/utils/detector.js`) and preselects a framework preset. However, because different frameworks have unique internal architectures (especially around network binding and build outputs), a few frameworks require minor application-level tweaks to run securely in a Dockerized AWS Fargate environment.
+
+## The 3-tier support philosophy
+
+We handle framework requirements using a 3-tier strategy so you are never left guessing why a deployment failed:
+
+1. **Zero-touch plugins (Tier 1):** If you use one of our ecosystem plugins (e.g., `nest add nest-grada` or `cookiecutter-django-grada`), your code is automatically patched and configured. Zero manual intervention required.
+2. **Intelligent CLI pre-flight (Tier 2):** If you run the standalone `grada` CLI against a raw repository, the CLI statically analyzes your code. If it detects a missing production requirement (like a localhost binding), it will flag it inline in your terminal with the exact copy-paste fix.
+3. **In-repo docs (Tier 3):** The generated `DEPLOYMENT.md` file always contains a framework-specific checklist before you push to CI/CD.
+
+## Detection precedence
+
+Checks run top-down; the first match wins.
+
+| # | Signal | Preset (`id` / name) |
+| - | ------ | -------------------- |
+| 1 | `package.json` depends on `@nestjs/core` | `nestjs` / NestJS |
+| 2 | `package.json` depends on `next` | `nextjs` / Next.js |
+| 3 | `package.json` depends on `nuxt` | `nuxt` / Nuxt 3 (SSR) |
+| 4 | `package.json` depends on `express` | `node` / Node.js / Express |
+| 5 | `package.json` depends on `@sveltejs/kit` | `svelte` / SvelteKit SSR |
+| 6 | `package.json` depends on `react-scripts`, `gatsby`, `astro`, `vite`, `@vue/cli-service`, or `@angular/cli` | `static` / (that generator) |
+| 7 | `requirements.txt` contains `fastapi` | `python` / Python FastAPI |
+| 8 | `requirements.txt` contains `django`, or `manage.py` exists | `django` / Django |
+| 9 | `Gemfile` contains a `rails` gem | `rails` / Ruby on Rails |
+| 10 | `go.mod` exists | `go` / Go |
+| 11 | No match | No preset — you pick from the interactive list |
+
+Notes from the actual code:
+
+- Both `dependencies` and `devDependencies` are searched, so a framework listed only under dev dependencies still matches.
+- A malformed `package.json` or `vercel.json` is silently ignored (no match), never fatal.
+- An empty `vercel.json` (no `redirects`, `headers`, or `rewrites`) is treated as absent.
+
+## Valid `--framework` ids
+
+The interactive picker and the headless `--framework` flag accept: `node`, `nestjs`, `nextjs`, `nuxt`, `svelte`, `python`, `django`, `rails`, `go`, `static`. In headless mode with no `--framework`, detection applies and anything unmatched falls back to `static`.
+
+## Per-framework defaults
+
+- **Static build directory** (`buildDir`): SvelteKit `build`, Gatsby `public`, everything else (`astro`, `vite`, Vue, Angular) `dist`. This selects the folder the generated `Dockerfile` serves.
+- **Default container port**: `8080` for `static` and `go`, `8000` for `python` and `django`, `3000` for everything else (headless uses `8080` only when `--framework=static`, else `3000`).
+- **Database prompt**: offered only for backend presets (`node`, `nestjs`, `nextjs`, `nuxt`, `svelte`, `python`, `django`, `rails`, `go`).
+
+## Framework requirements cheat sheet
+
+| Framework | What `grada` automates | Application code requirement | Zero-click starter / plugin |
+|---|---|---|---|
+| **Next.js** | Multi-stage Dockerfile, CloudFront edge routing, `vercel.json` parsing | `output: 'standalone'` must be set in `next.config.js` | Built-in CLI detection |
+| **NestJS** | Multi-stage TypeScript build (`dist/`), unprivileged Node runtime | `await app.listen(port, '0.0.0.0')` in `src/main.ts` | `nest-grada` (`nest add`) |
+| **FastAPI** | Alpine Python container, Uvicorn CLI args, unprivileged port mapping | None (0.0.0.0 set via Docker CMD) | `cookiecutter-fastapi-grada` |
+| **Django** | Gunicorn WSGI adapter, Celery worker topologies, RDS bindings | None (0.0.0.0 set via Docker CMD) | `cookiecutter-django-grada` |
+| **Ruby on Rails** | Puma adapter, `RAILS_MASTER_KEY` injection into Secrets Manager placeholder, Kamal Dockerfile replaced with 0-CVE Alpine build | None (0.0.0.0 set via Docker CMD) | `rails-template-grada` |
+| **Nuxt 3** | Nitro-optimized Node output | None (`NITRO_HOST=0.0.0.0` injected automatically) | `nuxt-grada` |
+| **SvelteKit** | Node adapter conversion | None (`HOST=0.0.0.0` injected automatically) | `svelte-adapter-grada` |
+| **Static Sites** *(Vite, Astro, React)* | Output folder detection (`dist/`, `build/`), Nginx routing | None | `vite-plugin-grada` |
+
+## Post-detection checks
+
+After detection, setup validates framework-specific requirements and warns before generating:
+
+- **NestJS**: `src/main.ts` (or `main.js`) must bind `0.0.0.0`, e.g. `await app.listen(process.env.PORT ?? 3000, '0.0.0.0')`.
+- **Next.js**: config must set `output: 'standalone'` (`.js/.mjs/.cjs/.ts` checked).
+- **SvelteKit**: adapter must not be `@sveltejs/adapter-vercel` or `adapter-auto`.
+- **Astro**: adapter must not be `@astrojs/vercel`.
+
+Alongside detection, setup also auto-detects `Procfile` (web/worker commands), `vercel.json` edge rules (translated to ALB listener rules), and `docker-compose.yml` services (port override plus sidecars).
+
+## The golden rule: 0.0.0.0 vs localhost
+
+The most common reason a newly deployed container fails its ALB health check is network binding.
+
+In local development, frameworks bind to `localhost` (or `127.0.0.1`) for security. However, inside a Docker container on AWS ECS, binding to `localhost` means the web server only listens to internal container traffic. The AWS Application Load Balancer (ALB) trying to route traffic from the outside world will hit a closed port, resulting in a `502 Bad Gateway` or `503 Service Temporarily Unavailable`.
+
+**Always ensure your application explicitly binds to `0.0.0.0`.**
+
+## See also
+
+- [Dockerfiles & the container contract](/grada/guides/dockerfiles/) for what your app must do at runtime.
+- [Headless Mode](/grada/guides/headless/) for automating framework selection.
+- [Examples](/grada/guides/examples/) for reference repositories and ecosystem plugins per framework.

package/apps/docs/src/content/docs/guides/headless.md

@@ -0,0 +1,75 @@
+---
+title: "Headless Mode & Automation Guide"
+description: "Run grada without prompts for CI/CD pipelines, scripts, and framework plugins."
+sidebar:
+  order: 11
+---
+
+The `grada` CLI is designed to be fully automatable for CI/CD pipelines, custom scripts, Cookiecutters, and framework plugins (like `vite-plugin-grada`). 
+
+By passing the `--headless` flag, you bypass all interactive terminal prompts. This is a tested contract (`tests/headless.test.js`): with `--headless --preconfigured`, the CLI guarantees no interactive prompt ever fires, so external schematics and CI pipelines can invoke it without hanging.
+
+## Required Flags
+To use headless mode, simply include the `--headless` flag. 
+
+If `grada` cannot auto-detect your framework, you should also provide the `--framework` flag to ensure the correct infrastructure is generated.
+
+* **Valid `--framework` options:** `node`, `nestjs`, `nextjs`, `nuxt`, `svelte`, `python`, `django`, `rails`, `go`, `static`
+
+## Optional Configuration Flags
+
+You can append any of these flags to customize the generated architecture. These map exactly to the options available in the interactive setup:
+
+| Flag | Description | Default |
+|---|---|---|
+| `--region=<region>` | The AWS region to deploy to (e.g., `us-east-1`, `eu-west-1`). | `us-east-2` |
+| `--size=<size>` | The Fargate compute size (`micro` or `small`). | `micro` |
+| `--port=<number>` | The internal port your container exposes. | Framework dependent (`3000`, `8080`, `8000`) |
+| `--healthCheckPath=<path>`| The ALB health check endpoint path. | `/` |
+| `--desiredCount=<number>` | Number of container replicas to run (`1` or `2`). | `1` |
+| `--branch=<name>` | The primary Git deployment branch for CI/CD. | `main` |
+| `--dir=<path>` | The directory to generate files into (use `.` for current).| `.` |
+| `--target=<target>` | Compute architecture: `ecs` (default, `fargate` synonym) or `lambda` (scale-to-zero serverless). | `ecs` |
+| `--needsDatabase` | Provisions a managed AWS database alongside Fargate (engine via `--db-engine`). | `false` |
+| `--db-engine=<engine>` | Database engine: `postgres` (default), `mysql` (MySQL 8.0), or `aurora-postgresql` (Serverless v2 scale-to-zero). | `postgres` |
+| `--enablePrPreviews` | Generates workflows for Ephemeral PR Previews. | `false` |
+| `--no-telemetry` | Disables anonymous usage analytics (or set `DO_NOT_TRACK=1` for all runs). | `false` |
+| `--preconfigured` | Suppresses framework warnings for pre-validated configs from external schematics/integrations (e.g., `nest add`). | `false` |
+| `--with=<capabilities>` | Comma-separated (or repeatable) addon capabilities to scaffold during init (`storage:s3`, `db:dynamodb`, `db:redis`, `queue:sqs`, `ai:bedrock`, `email:ses`, `cron`). | none |
+| `--model=<id>` | Bedrock model override when `ai:bedrock` is included. | Catalog recommended model |
+| `--domain=<domain>` | Domain for the SES identity when `email:ses` is included (required in headless mode). | none |
+| `--zone-id=<id>` | Route 53 hosted zone ID for automatic SES DNS records. | none |
+| `--from-email=<email>` | Default SES sender address. | `noreply@<domain>` |
+| `--setup-ci-migrate` | Wire the pre-deploy database migration gate into the generated workflow when a database and migration command are detected. | `false` |
+| `--setup-ci-drift` | Scaffold `.github/workflows/drift.yml`: a daily 06:00 UTC `terraform plan` check that opens (or updates) a GitHub Issue labeled `iac-drift` on drift and closes it when resolved. | `false` |
+
+*(Note: Boolean flags like `--needsDatabase` and `--enablePrPreviews` can be passed alone or as `--flag=true`).*
+
+## Example Usage
+
+**Standard Static Site Automation (e.g., Vite/React):**
+```bash
+npx grada-run --headless --framework=static --region=eu-west-1 --size=micro
+```
+
+**Next.js High-Availability CI/CD Generation:**
+```bash
+npx grada-run --headless --framework=nextjs --size=small --desiredCount=2
+```
+
+**Django Setup with Managed RDS Database:**
+```bash
+npx grada-run --headless --framework=django --needsDatabase
+```
+
+**Full-Stack Automation with Addons and Migration Gate:**
+```bash
+npx grada-run --headless --framework=nestjs --needsDatabase \
+  --with db:redis,ai:bedrock,email:ses --domain example.com --setup-ci-migrate
+```
+
+## See also
+
+- [`npx grada-run`](/grada/cli/init/) for the full flag table.
+- [Supported Frameworks](/grada/guides/frameworks/) for valid `--framework` ids.
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for what runs after generation.

package/apps/docs/src/content/docs/guides/quickstart.md

@@ -0,0 +1,52 @@
+---
+title: Quickstart (5 minutes)
+description: Go from empty repo to live AWS deployment in five minutes with grada.
+sidebar:
+  order: 0
+---
+
+Deploy your first app to AWS in about five minutes. This is the fastest path; follow the links for details at each step.
+
+## Prerequisites
+
+- Node.js 18+, an AWS account, and AWS credentials in your terminal (`aws sso login` or `aws configure`).
+- A git repository with your app. Stuck on auth? See [Troubleshooting AWS Credentials](/grada/guides/aws-credentials/).
+
+## Step 1 — Scaffold
+
+```bash
+npx grada-run
+```
+
+The wizard auto-detects your framework, `Procfile`, `vercel.json`, and Compose files, then writes Terraform, a `Dockerfile`, and `.github/workflows/deploy.yml`. Not sure your stack is supported? Check [Supported Frameworks](/grada/guides/frameworks/).
+
+## Step 2 — Provision
+
+```bash
+npx grada-run apply
+```
+
+This creates the ALB, ECS cluster, and service. Your URL returns `503` until the first image is pushed — that is expected.
+
+## Step 3 — Ship
+
+```bash
+git add .
+git commit -m "ci: infra"
+git push
+```
+
+Pushing to your deploy branch triggers the pipeline: Terraform sync, Docker build, image scan, ECS rollout. How it works is explained in [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/).
+
+## Step 4 — Verify
+
+- Open the ALB URL from the `apply` output.
+- Still seeing `503` or `502` after the workflow finishes? Run `npx grada-run diagnose` — usually the container failed its health check. See [Dockerfiles & the Container Contract](/grada/guides/dockerfiles/).
+- Need env vars? Continue with [Secrets Management](/grada/guides/secrets-management/).
+
+## Next steps
+
+- [Supported Frameworks](/grada/guides/frameworks/) — framework requirements and detection rules.
+- [Reference Implementations & Examples](/grada/guides/examples/) — working repos per framework.
+- [Headless Mode & Automation](/grada/guides/headless/) — non-interactive `npx grada-run --headless` for CI.
+- Migrating? Start with [Vercel (Next.js)](/grada/migrations/nextjs-vercel-to-aws/), [Vercel (Astro)](/grada/migrations/astro-vercel-to-aws/), [Vercel (SvelteKit)](/grada/migrations/sveltekit-vercel-to-aws/), or [Heroku (Procfile)](/grada/migrations/heroku-procfile-to-aws/).

package/apps/docs/src/content/docs/guides/rerun-init.md

@@ -0,0 +1,43 @@
+---
+title: Re-running Init Safely
+description: What happens when setup finds existing files — backups, regeneration, and how to recover.
+sidebar:
+  order: 10
+---
+
+Re-running `npx grada-run` to change region, size, or framework is safe and predictable: setup never merges with your existing generated files. It backs them up, regenerates from scratch, and tells you exactly what moved.
+
+## The conflict prompt
+
+When setup finds any of `terraform/`, `Dockerfile`, or `.github/workflows/deploy.yml` in the target directory (`src/utils/backup.js`), it lists the conflicts and offers two choices:
+
+- **Backup & Regenerate** — each conflicting path is renamed with a timestamp suffix (e.g. `terraform.bak.1726771200000`), then fresh files are generated.
+- **Cancel** — exits immediately with no changes.
+
+In `--headless` mode there is no prompt: existing files are backed up automatically. Either way, nothing is ever merged or partially overwritten.
+
+## Backups stay local
+
+After backing up, setup appends a `# grada backups` block (`*.bak.*`) to `.gitignore` (creating the file if needed), so backup clutter never reaches GitHub. To recover a previous configuration, compare with `diff -r terraform.bak.<timestamp> terraform/` and copy back what you need — then delete the `.bak.*` directory when you are satisfied. (`npx grada-run eject` removes all `*.bak.*` files as part of decoupling.)
+
+## What regeneration touches
+
+`src/utils/generator.js` writes a fixed file set and handles pre-existing files explicitly:
+
+- `terraform/*.tf`, `Dockerfile`, `.github/workflows/deploy.yml`, plus `preview.yml`/`teardown.yml` only when PR previews are enabled.
+- `terraform/secret_keys.json` is preserved when it already exists (only created as `[]` on first setup) — your pushed key map survives re-runs with no need to re-push.
+- If your repo already has a `README.md`, it is kept and gets a short Deployment pointer appended; the generated guide goes to `DEPLOYMENT.md` instead.
+- Existing `.gitignore` / `.dockerignore` files are preserved with only the grada entries appended (Terraform state paths, `.env`); missing ones are created with framework-appropriate presets.
+- **Rails only:** if `ci.yml` or `dependabot.yml` exist, setup asks whether to disable them by renaming to `.bak` (default CI usually crashes without a database service); in headless mode they are disabled automatically.
+
+## Suggested workflow
+
+1. Commit your work before re-running, so `git status` shows exactly what regeneration changed.
+2. Re-run, review the diff (`git diff`, plus `diff -r` against the `.bak` copies for untracked files like `terraform/` internals).
+3. Run `npx grada-run apply` to converge AWS with the new configuration.
+4. Delete the `.bak.<timestamp>` copies once the new infrastructure is verified.
+
+## See also
+
+- [apply](/grada/cli/apply/) for converging AWS after regeneration.
+- [eject](/grada/cli/eject/) for what happens to backups on decoupling.

package/apps/docs/src/content/docs/guides/secrets-management.md

@@ -0,0 +1,83 @@
+---
+title: "Secrets Management in grada"
+description: "Sync .env files to AWS Secrets Manager without committing plaintext secrets."
+sidebar:
+  order: 7
+---
+
+Managing `.env` files across a team and syncing them to the cloud is a notorious pain point. `grada` solves this by natively integrating with **AWS Secrets Manager**, ensuring zero plaintext secrets ever touch your GitHub repository or CI/CD pipelines. Secrets Manager bills $0.40 per secret per month (one for your app secrets, plus one for the database master password when applicable) — itemized in the `apply` cost preview.
+
+## The Secrets Lifecycle
+
+To maintain zero-secret Git repositories and safe infrastructure provisioning, secrets follow a strict 4-step lifecycle:
+
+```text
+1. Scaffold        ───▶  2. Provision Vault   ───▶  3. Push Secrets     ───▶  4. Deploy to App
+(grada)           (grada apply)       (secrets push .env)       (git push)
+Generates Terraform       Creates empty vault        Uploads encrypted keys    ECS container boots
+& secret_keys.json        in AWS Secrets Mgr         & updates secret_keys     with injected env
+```
+
+---
+
+### Step 1: Provision the Vault (Day 1)
+Your Secrets Manager vault is declared in `terraform/secrets.tf`. Provision the base infrastructure first:
+
+```bash
+npx grada-run apply
+```
+*This creates an empty, secure secret vault named `<project-name>-secrets` in your AWS account.*
+
+### Step 2: Push Secrets to AWS
+Once the vault exists, push your local `.env` values directly to AWS:
+
+```bash
+npx grada-run secrets push .env
+```
+
+**What happens under the hood?**
+1. The CLI reads your local `.env` file.
+2. It encrypts the key-value pairs and pushes them securely into AWS Secrets Manager under your project's namespace (e.g., `my-project-secrets`).
+3. It generates a local `terraform/secret_keys.json` file containing *only the names* of your keys (e.g., `["API_KEY", "STRIPE_SECRET"]`), **not the values**. Re-running setup never wipes this file.
+
+> 💡 **Tip:** The `secrets push` command takes the file path as the first argument. If you need to use other flags, ensure they are appended at the end of the command:
+> `npx grada-run secrets push .env --any-other-flags`
+
+> 🌱 **No `.env` yet?** `secrets push` offers to create an empty one for you interactively. In CI / `--headless` mode it exits 1 instead of prompting, so generate the file before pushing.
+
+### Step 3: Map Secrets into the Container
+Commit the updated `terraform/secret_keys.json` and push to GitHub:
+
+```bash
+git add terraform/secret_keys.json
+git commit -m "chore: map new secrets to ECS"
+git push origin main
+```
+
+Terraform reads `secret_keys.json` during the GitHub Actions deployment and maps each key directly into your ECS Task Definition. When your Fargate container boots up, AWS injects the secret values into `process.env` (Node) or `os.environ` (Python) in memory. On `--target lambda` projects the vault stays shared for runtime reads (`APP_SECRETS_ARN`) and fresh invocations pick up new values automatically — no restart step exists.
+
+> ⚠️ **Commit this file.** `secret_keys.json` holds key *names* only — never values — so it is safe for version control, and deployment depends on it.
+
+---
+
+### Day-2: Pull, Audit, and Rotate (no redeploy)
+
+Secrets don't stand still — teammates join, keys rotate, local `.env` files get lost. Two commands close the loop:
+
+```bash
+npx grada-run secrets pull    # merge remote values into local .env
+npx grada-run secrets audit   # diff local .env vs AWS, change nothing
+```
+
+`pull` appends missing remote keys after your existing entries, keeps local-only variables, and asks before overwriting conflicting values (automatic in `--headless` mode). `audit` prints a colored drift report: `+` missing locally, `~` mismatched values, `-` never pushed to AWS.
+
+**Which flow do I need?**
+
+| Situation | Command |
+|---|---|
+| New variable name added/removed | `secrets push`, then commit `secret_keys.json` + `git push` (task definition must be rebuilt) |
+| Only a value changed (same keys) | `secrets push`, then accept the rolling ECS restart prompt — live in seconds, no redeploy |
+| New machine / lost `.env` | `secrets pull` |
+| "Why doesn't my app see the new value?" | `secrets audit` first, then push or restart accordingly |
+
+See the [secrets CLI reference](/grada/cli/secrets/) for flags, merge rules, and prerequisites.

package/apps/docs/src/content/docs/guides/understanding-your-bill.md

@@ -0,0 +1,63 @@
+---
+title: Understanding Your AWS Bill
+description: What each part of your grada infrastructure costs, what the CLI estimates cover, and how to keep spend low.
+---
+
+Every grada command that touches infrastructure tells you what it costs *before* you pay it: `apply` shows a pre-flight estimate, `add` prints the cost impact of each addon, and your `README.md` keeps a refreshed monthly baseline. This guide explains what those numbers include, what they leave out, and where the cost levers are.
+
+All reference rates below are for `us-east-2` (the stack default) and assume a 730-hour month. Other regions typically land within ~5–15% of these figures.
+
+## The Fixed Monthly Baseline
+
+These resources bill by the hour (or month) whether your app serves one request or one million. A minimal stack (256 CPU / 512 MB Fargate micro, no database) runs **~$31.68/mo**:
+
+| Resource | Math | Monthly |
+| -------- | ---- | ------- |
+| Fargate task (0.25 vCPU + 0.5 GB) | (0.25 × $0.04048 + 0.5 × $0.004445) × 730 hrs | ~$9.01 |
+| Application Load Balancer (base + ~1 LCU) | ($0.0225 + $0.008) × 730 hrs | ~$22.27 |
+| Secrets Manager (1 app secret) | 1 × $0.40 | $0.40 |
+
+Optional fixed add-ons to the baseline:
+
+| Addition | Monthly |
+| -------- | ------- |
+| Background worker service (second identical Fargate task) | doubles Fargate to ~$18.02 — but scales to $0 when its SQS queue is empty |
+| RDS Postgres (`db.t4g.micro` + 20 GB gp3 + managed secret) | ~$13.98 + $0.40 secret |
+| Valkey caching (`add db:redis`, `cache.t4g.micro`) | ~$9.49 |
+
+So a typical full stack (web + database + Valkey) lands around **~$55.55/mo**, and the CLI's estimate always reflects your actual `terraform/` directory — container size, worker, database, secrets, and fixed-cost addons included.
+
+On the Lambda target (`--target lambda`) there is no Fargate or ALB baseline at all: compute and the API Gateway HTTP API bill purely on use, so a no-database project idles at **~$0.40/mo** (one Secrets Manager secret) and an Aurora-backed one at **~$0.80/mo**. The pre-flight estimate shows this as `Fixed Baseline: ~$0.80/mo (RDS: $0.00, Secrets: $0.80 + API GW & Lambda usage)` — the trailing caveat is the reminder that requests, not hours, are the real bill.
+
+## What the Estimate Leaves Out (Usage Billing)
+
+Anything that scales with traffic is billed on use and intentionally excluded from the fixed number:
+
+- **Addons:** `storage:s3` (storage, requests, CloudFront egress), `db:dynamodb` (requests, storage, backups), `queue:sqs` (requests past the 1M free tier), `ai:bedrock` (per-token inference), `email:ses` ($0.10 per 1,000 emails sent), `cron` (Fargate seconds per scheduled run). Each `add` run prints its own billing drivers.
+- **Data transfer:** outbound traffic and CloudFront egress beyond free tiers.
+- **Logs & images:** CloudWatch Logs ingestion (14-day retention is configured) and ECR image storage (~$0.10/GB-mo) — usually cents, plus `gc` cleans up orphans.
+- **Traffic spikes:** ALB capacity units above the ~1 LCU baseline, and RDS backup storage past the free allowance.
+- **Serverless compute (Lambda target):** API Gateway HTTP API requests ($1.00 per million) plus Lambda request charges and GB-second compute time. Sporadic traffic costs pennies; sustained high-concurrency traffic can overtake the ~$31/mo Fargate baseline — see the [Fargate vs Lambda tradeoffs](/grada/guides/architecture/#fargate-vs-lambda-tradeoffs).
+
+Rule of thumb: the fixed baseline is your floor; side projects with modest traffic typically land within a few dollars above it.
+
+### Which target costs less for my workload?
+
+- **Side project / internal tool** (dozens to hundreds of requests a day): Lambda, by a mile — pennies a month against ~$31+ of idle ECS baseline.
+- **Steady product API** (sustained traffic around the clock): Fargate — the flat baseline undercuts per-request billing once concurrency stops dropping to zero.
+- **Spiky or unpredictable traffic** (launches, webhooks, batch-driven): Lambda absorbs bursts with no capacity planning; just mind the database-connection note in [Fargate vs Lambda tradeoffs](/grada/guides/architecture/#fargate-vs-lambda-tradeoffs).
+
+## Cost Savers Built Into the Stack
+
+- **No NAT gateway.** Tasks run in public subnets behind the ALB security group instead of behind a ~$33/mo NAT — the single biggest saving versus a conventional VPC layout.
+- **Micro defaults, scale up deliberately.** Fargate micro, single-AZ `db.t4g.micro`, and single-node Valkey keep the floor low; grow container size or add read replicas only when metrics say so.
+- **Workers scale to zero.** The SQS-driven worker parks at 0 tasks (and $0 compute) when the queue drains — you pay for background capacity only while jobs exist.
+- **Sleep idle environments.** `sleep [env]` scales ECS services to 0 and stops RDS, printing the exact hourly/monthly compute savings (e.g. ~$20.69/mo for a micro web service plus Postgres: ~$9.01 Fargate + ~$11.68 RDS compute paused); `wake [env]` restores everything. Storage (~$2.30/mo), the ALB (~$22.27/mo), Valkey (~$9.49/mo, no pause API), and secrets keep billing while asleep, and AWS auto-restarts stopped databases after 7 days — the CLI shows the exact restart timestamp.
+- **PR previews self-destruct.** Each open pull request runs a full copy of the stack (~$31+/mo each while open, mostly the extra ALB), so previews are destroyed automatically when the PR closes. Close stale PRs and run `gc` to catch leftovers.
+- **Serverless-first addons.** DynamoDB on-demand, SQS, SES, Bedrock, and scheduled cron jobs cost nothing at rest — prefer them over always-on resources when the workload fits.
+
+## Keeping Estimates Accurate
+
+- The `README.md` estimate refreshes automatically on every `add` and `apply` — if you hand-edit `terraform/`, re-run `apply` (or `--dry-run`) to re-sync it.
+- Estimates follow your real config: bigger `--size` at `init`, extra secrets, and new addons all flow into the number on the next run.
+- For hard budget enforcement, pair the CLI estimates with an AWS Budgets billing alarm in the console — the CLI tells you the expected spend, AWS tells you the actuals.