grada-run 0.0.2 → 0.32.0

package/apps/docs/src/content/docs/cli/logs.md

@@ -0,0 +1,39 @@
+---
+title: logs
+description: Stream CloudWatch logs for your ECS service.
+---
+
+Stream recent and live CloudWatch logs for the current project, without opening the AWS console.
+
+## What it does
+
+- Resolves the log group (`/ecs/<project-name>`, overridable via `ECS_LOG_GROUP`) and region (`--region` → `AWS_REGION` → `terraform/main.tf` → `us-east-2`) automatically.
+- Prints recent lines with dimmed ISO timestamps and task IDs; errors in red, warnings in yellow.
+- With `-f`, polls every 2 seconds until Ctrl+C, which exits cleanly.
+- On expired credentials, prints the `aws sso login` / `aws configure` hint and exits 1; on a missing log group, suggests the matching `aws logs describe-log-groups` lookup instead of throwing.
+- On `--target lambda` projects, tails `/aws/lambda/<project-name>-fn` instead, and the service filter is ignored (Lambda stream names are request-based, not container names).
+- Emits a `logs_streamed` telemetry event recording success and filter options.
+
+## Usage
+
+```bash
+npx grada-run logs
+npx grada-run logs api --tail 100 --error
+npx grada-run logs -f --since 5m
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `[service]` | Service/container filter. Defaults to the project service. |
+| `--tail <n>` | Recent lines to show (default `50`). |
+| `-f, --follow` | Stream live until interrupted. |
+| `--error` | Show only error lines (`ERROR`, `FATAL`, `Exception`, `fail`, `5XX`). |
+| `--since <duration>` | Look-back window, e.g. `5m`, `1h`, `1d` (default `1h` for one-shot reads). |
+| `--region <region>` | Explicit AWS region override. |
+
+## See also
+
+- [exec](/grada/cli/exec/)
+- [status](/grada/cli/status/)

package/apps/docs/src/content/docs/cli/rollback.md

@@ -0,0 +1,51 @@
+---
+title: rollback
+description: Roll back your ECS service to a previous task definition revision.
+---
+
+Two layers of deployment safety: your infrastructure rolls back bad deployments automatically, and you can manually return to any previous revision with one command.
+
+## What it does
+
+- Your ECS service ships with a deployment circuit breaker — if a new deployment fails its health checks, AWS automatically rolls it back without you lifting a finger.
+- `rollback` takes you back to a previous task definition revision on demand: pass a revision number, or pick from an interactive list showing each revision's container image and registration date.
+- In automation and CI (or with `--headless`), it defaults to the most recent older revision with no prompt.
+- Resolves its inputs automatically: cluster (`<project-name>-cluster`, overridable via `ECS_CLUSTER`), service (`<project-name>-service`, overridable via `ECS_SERVICE`), and region (`--region` → `AWS_REGION` → `terraform/main.tf` → `us-east-2`). `--workspace` targets a PR-preview environment's namespaced service.
+- Watches the rollback deployment until it stabilizes (up to 5 minutes), and points you to `status` and `logs` if it fails or times out.
+- ECS only: on `--target lambda` projects the command exits with the Lambda-native alternative — redeploy a previous image with `aws lambda update-function-code` (list SHA tags via `aws ecr describe-images`).
+- Emits a `rollback_run` telemetry event recording success and outcome.
+
+## Usage
+
+```bash
+npx grada-run rollback
+npx grada-run rollback 12
+npx grada-run rollback --skip-wait
+npx grada-run rollback 12 --cluster myapp-cluster --service myapp-service
+```
+
+Without a revision number, you'll see an interactive revision selector:
+
+```text
+? Select a task definition revision to roll back to:
+  Revision 13 — myapp:sha-9f2c1ab (2026-09-20)
+  Revision 12 — myapp:sha-77d0e4f (2026-09-18)
+  Revision 11 — myapp:sha-51b8c2d (2026-09-15)
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `[revision]` | Task revision to roll back to: a number (`12`), `family:revision` (`myapp-task:12`), or a full task definition ARN. Defaults to the most recent older revision (interactive prompt on a TTY). |
+| `--cluster <name>` | Explicit cluster name override. |
+| `--service <name>` | Explicit service name override. |
+| `--region <region>` | Explicit AWS region override. |
+| `--workspace <name>` | Roll back the PR-preview environment's service instead of production. |
+| `--skip-wait` | Trigger the rollback and exit immediately without waiting for stabilization. |
+
+## See also
+
+- [status](/grada/cli/status/)
+- [logs](/grada/cli/logs/)
+- [diagnose](/grada/cli/diagnose/)

package/apps/docs/src/content/docs/cli/secrets.md

@@ -0,0 +1,73 @@
+---
+title: secrets
+description: Push, pull, and audit environment secrets synced with AWS Secrets Manager.
+---
+
+Sync your local `.env` file with the Secrets Manager vault provisioned for this project, so your deployed app reads the values at runtime without plaintext secrets ever touching the repo or CI/CD pipelines.
+
+## secrets push
+
+Uploads a local env file to the `<project-name>-secrets` vault via `UpdateSecretCommand`, then writes the pushed key names to `terraform/secret_keys.json` so Terraform and CI redeploy know which variables exist.
+
+```bash
+npx grada-run secrets push
+npx grada-run secrets push .env.production
+```
+
+The optional positional argument is the path of the env file to push (resolved relative to the project root). It defaults to `.env` when omitted or blank.
+
+**Smart follow-up based on what changed:**
+
+- **Key names changed** (added/removed variables) — commit `terraform/secret_keys.json` and push to GitHub to trigger a deployment with the new variables. The ECS task definition is rebuilt from the updated key map.
+- **Only values changed** (same key set) — the CLI offers a rolling ECS restart (`forceNewDeployment`) so running tasks pick up the new values immediately, no redeploy required.
+- **Lambda target** — new values apply to fresh invocations automatically; no restart is offered or needed.
+
+Region resolution is shared across all three commands (see Prerequisites), so they work even when no region is configured. Emits a `secrets_pushed` telemetry event. Exits non-zero on failure.
+
+**Missing env file:** if the file does not exist, `push` does not throw. Interactively it asks `Would you like to create an empty <file> file now to get started?` — confirming creates the file (with parent directories) so you can fill it in and re-run; declining leaves everything untouched. With `--headless` or `CI=true` it prints a pointer to generate the file first and exits 1.
+
+## secrets pull
+
+Fetches the remote JSON payload from the `<project-name>-secrets` vault and merges it into your local env file — useful for onboarding a new machine or recovering after losing `.env`.
+
+```bash
+npx grada-run secrets pull
+npx grada-run secrets pull .env
+```
+
+**Merge behavior:**
+
+- Remote keys are appended after your existing local keys; existing local order is preserved.
+- Local-only variables are kept — pull never deletes them.
+- If a key exists locally and remotely with different values, the CLI asks `Conflicting variables found. Overwrite local values with remote?` In `--headless` mode it overwrites automatically.
+
+Values are written in standard `KEY="value"` format. Emits a `secrets_pull` telemetry event. Exits non-zero on failure (e.g. no remote vault yet — run `secrets push` first).
+
+## secrets audit
+
+Compares your local env file against the remote vault and prints a colored drift report — no files are modified.
+
+```bash
+npx grada-run secrets audit
+```
+
+- `+ KEY (Missing locally)` in green — exists in AWS but not in your `.env`.
+- `~ KEY (Mismatched value)` in yellow — exists in both with different values.
+- `- KEY (Not tracked in AWS)` in dim — exists locally but was never pushed.
+
+Ends with `Audit complete. N drifted variable(s) found.` Emits a `secrets_audit` telemetry event.
+
+## Prerequisites
+
+- Run `npx grada-run apply` first: the `<project-name>-secrets` vault is created during provisioning. If it does not exist yet, each command points you back to `apply`.
+- Valid AWS credentials. On expired credentials, refresh with `aws sso login` or `aws configure`. See the [AWS credentials guide](/grada/guides/aws-credentials/).
+- Region (all three commands): pass `--region <region>` explicitly, or rely on the automatic chain — `AWS_REGION` → `AWS_DEFAULT_REGION` → the `region` in `terraform/backend.tf` → default `us-east-2`.
+
+## A note on `terraform/secret_keys.json`
+
+This file contains **key names only** (e.g. `["API_KEY"]`), never values — it is safe to commit, and it **must** be committed: Terraform reads it during deployment to map each key into your ECS task definition.
+
+## See also
+
+- [Secrets management guide](/grada/guides/secrets-management/)
+- [apply](/grada/cli/apply/)

package/apps/docs/src/content/docs/cli/sleep.md

@@ -0,0 +1,53 @@
+---
+title: sleep & wake
+description: Pause idle environments to save costs by scaling ECS services to zero and stopping RDS, then restore them with one command.
+---
+
+Pause a non-production or idle environment with a single command, and wake it back up when you need it — without opening the AWS Management Console.
+
+## What it does
+
+- `sleep [env]` scales your ECS services (`app` and `worker`, when present) to `0` and stops the RDS instance or Aurora cluster, printing the estimated hourly/monthly compute savings.
+- `wake [env]` starts the database first (waiting until it is `available`), then restores the exact ECS desired counts recorded at sleep time.
+- `sleep` also pauses the `add cron` schedule (when configured) and suspends SQS worker auto-scaling, so no scheduled task or queued message wakes the environment back up; `wake` resumes both. Schedules that were never deployed and unregistered scaling targets are skipped gracefully.
+- Sleeping the default (production) environment requires confirmation (`--yes` in automation); named environments sleep without prompting.
+- AWS automatically restarts stopped RDS databases after 7 consecutive days — `sleep` prints the exact restart timestamp, and `wake` warns if the window already elapsed.
+- Sleep state lives in `.grada/sleep-state.json` (one entry per environment, gitignored), so `wake` restores your original replica counts even for scaled-out services.
+- On `--target lambda` projects, compute is already scale-to-zero, so `sleep`/`wake` manage only the database (and pause/resume the cron schedule) — no services are scaled or restored.
+- Emits `sleep_run` / `wake_run` telemetry events recording the outcome.
+
+## Usage
+
+```bash
+npx grada-run sleep staging
+npx grada-run wake staging
+npx grada-run sleep --yes
+npx grada-run wake --no-wait
+npx grada-run sleep staging --skip-db
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `[env]` | Positional environment name (e.g. `staging`, `pr-42`). Aliases `--workspace`. Defaults to the default environment. |
+| `--workspace <name>` | Explicit environment name. Wins over the positional `[env]`. |
+| `--project-name <name>` | Explicit project name override (defaults to the name in `terraform/main.tf`, then the directory name). |
+| `--cluster <name>` | Explicit ECS cluster override. |
+| `--service <name>` | Explicit ECS app service override. |
+| `--db-identifier <id>` | Explicit database identifier override. |
+| `--region <region>` | Explicit AWS region override. |
+| `--skip-db` | Scale ECS services only; leave the database running. |
+| `--no-wait` | On `wake`, return immediately instead of waiting for RDS `available` and ECS tasks to reach their desired counts. |
+| `--yes` | Skip the production confirmation prompt on `sleep` (also accepts `--force`; required in `--headless`/CI runs, which fail instead of prompting). |
+
+Both commands are idempotent: re-sleeping an asleep environment (or waking an awake one) reports the current state instead of failing.
+
+## Cost & billing drivers
+
+While asleep you stop paying for Fargate task hours (`~$9.01/mo` per 256/512 replica) and RDS instance compute (`~$11.68/mo` for `db.t4g.micro`). 20 GB gp3 storage (`~$2.30/mo`), the ALB (`~$22.27/mo`), ElastiCache Valkey (`~$9.49/mo` — it has no pause API), and Secrets Manager secrets keep billing until you run `destroy`. Aurora Serverless v2 already idles at 0 ACU, so stopping it only prevents active wake-ups. Lambda projects skip the ALB line entirely — asleep, only storage, secrets, and (if present) Valkey keep billing.
+
+## See also
+
+- [status](/grada/cli/status/)
+- [destroy](/grada/cli/destroy/)

package/apps/docs/src/content/docs/cli/status.md

@@ -0,0 +1,34 @@
+---
+title: status
+description: Check ECS service health and CloudWatch alarms.
+---
+
+Instant health dashboard for your deployment. Exits cleanly when healthy; hands off to `diagnose` automatically when degraded.
+
+## What it does
+
+- Queries ECS (`desiredCount` vs `runningCount`/`pendingCount`) and project-prefixed CloudWatch alarms.
+- Prints a color-coded dashboard: service status, replicas (green/yellow/red), and alarm states.
+- If degraded (`runningCount < desiredCount` or any alarm firing), prints the degraded notice, invokes `diagnose`, and exits 1.
+- Resolves region like `logs` (`--region` → `AWS_REGION` → `terraform/main.tf` → `us-east-2`); cluster, service, and log group default to `<project-name>-cluster`, `<project-name>-service`, `/ecs/<project-name>` (overridable via `ECS_CLUSTER` / `ECS_SERVICE` / `ECS_LOG_GROUP`).
+- On `--target lambda` projects, reads function state via the AWS CLI (which must be installed) instead of ECS, printing function state, last update status, memory/timeout, and deployed image.
+- Emits a `status_run` telemetry event recording health and outcome.
+
+## Usage
+
+```bash
+npx grada-run status
+npx grada-run status --json
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Output the raw status payload as JSON; disables auto-diagnose. |
+| `--region <region>` | Explicit AWS region override. |
+
+## See also
+
+- [exec](/grada/cli/exec/)
+- [diagnose](/grada/cli/diagnose/)

package/apps/docs/src/content/docs/cli/sync-ai.md

@@ -0,0 +1,27 @@
+---
+title: sync-ai
+description: Regenerate AI assistant rules for an existing project.
+---
+
+Give your AI coding assistants up-to-date grada context after project settings change, so they generate correct Terraform and deployment instructions instead of hallucinating them.
+
+## What it does
+
+- Prompts you to choose which AI assistants to configure, then writes the matching rule files with your project's region (from `region` in `terraform/main.tf`) and container port (from `containerPort` in `terraform/main.tf`).
+- Writes a full rule file for Cursor (`.cursor/rules/grada.mdc`), Roo (`.roo/rules/grada.md`), Trae (`.trae/rules/project_rules.md`), and Continue (`.prompts/grada.prompt`); injects a managed block into the existing config for Windsurf (`.windsurfrules`), Copilot (`.github/copilot-instructions.md`), Claude (`CLAUDE.md`), Goose (`.goosehints`), and Aider (`.aider.conf.yml`).
+- Exits without writing anything when no assistants are selected.
+- Emits a `sync_ai_executed` telemetry event listing the selected assistants.
+
+## Usage
+
+```bash
+npx grada-run sync-ai
+```
+
+## Flags
+
+This command accepts no CLI flags. Assistant selection is interactive.
+
+## See also
+
+- [npx grada-run](/grada/cli/init/)

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

@@ -0,0 +1,87 @@
+---
+title: Stack Architecture
+description: How the generated VPC, load balancer, cluster, CDN, data stores, and CI pipeline fit together.
+---
+
+Every grada project generates the same shape: a public-subnet VPC, an ALB-fronted Fargate cluster (or a scale-to-zero Lambda function with `--target lambda`), CloudFront at the edge, and a keyless CI pipeline that ships images while Terraform owns the infrastructure. This page is the map; each piece links to its reference.
+
+## Request path
+
+Internet → **CloudFront** → **ALB** → **ECS tasks**. The distribution's origin is the load balancer (`cloudfront.tf`), so web traffic enters through the CDN with SSL terminated at the edge; the `Direct URL` printed by `apply` bypasses it for debugging.
+
+Tasks run with `awsvpc` networking in **public subnets** spread across availability zones (`10.0.0.0/16` VPC, one subnet per AZ, internet gateway attached). There is intentionally **no NAT gateway** — tasks get public IPs and talk out directly, which saves ~$33/mo versus a conventional private-subnet layout. Isolation comes from security groups: the ALB accepts public internet traffic, tasks accept traffic only from the ALB, and outbound access stays open for image pulls and external APIs.
+
+## Compute and images
+
+One ECS cluster holds the `app` service, plus an optional private `worker` service with no load balancer (see [Background Workers](/grada/guides/background-workers/)). Both run the same ECR image: the pipeline builds once per push and tags it with the commit SHA (the immutable deploy artifact) and `latest`. Scheduled jobs ([`add cron`](/grada/cli/add/)) reuse that same image — an EventBridge Scheduler rule launches a one-off Fargate task inside the VPC on your `cron(...)` or `rate(...)` expression, so there is no always-on worker to pay for.
+
+Two IAM roles split concerns: the **execution role** pulls images and reads secrets at boot, while the **task role** carries workload permissions — every [`add`](/grada/cli/add/) addon attaches its least-privilege policy here, so application code uses the AWS SDK with no keys.
+
+Deploys never rebuild infrastructure: the pipeline registers a new task-definition revision per push and updates the service to it, while Terraform ignores the service's `task_definition` so the next `apply` never reverts a code deploy. An ECS deployment circuit breaker rolls back failed rollouts automatically, and every revision stays registered so [`rollback`](/grada/cli/rollback/) always has history. See [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/).
+
+## Serverless target (`--target lambda`)
+
+Passing `--target lambda` to [`init`](/grada/cli/init/) generates an alternate scale-to-zero topology with the same VPC, ECR repository, IAM roles, secrets vault, and CloudFront distribution — only the compute layer changes:
+
+Internet → **CloudFront** → **API Gateway HTTP API v2** → **Lambda function**. The generated `Dockerfile` embeds the AWS Lambda Web Adapter extension, so standard HTTP servers (`app.listen(process.env.PORT)`) serve API Gateway events with zero application code changes. The fixed compute and load-balancer baseline is **$0.00/mo** (Lambda and HTTP APIs bill per request); a no-database project totals ~$0.80/mo in Secrets Manager.
+
+Deploys push the SHA-tagged image to ECR and call `update-function-code`, which Terraform ignores (mirroring the ECS `task_definition` rule) so code deploys and `apply` never fight. On day 0, `apply` seeds a minimal placeholder image into ECR automatically — Lambda's API rejects empty repositories — so the first provision succeeds before any code push.
+
+Projects with a database attach the function to the VPC subnets (still no NAT gateway) and receive credentials as `DB_*` environment variables, since VPC-attached functions cannot reach Secrets Manager without a paid VPC endpoint. Non-database functions stay outside the VPC with direct internet access; `add db:redis` attaches the VPC config on demand. Cron schedules invoke the function directly with a JSON payload carrying the configured command — handle scheduled events in application code.
+
+Day-2 commands adapt: `status` and `diagnose` read function configuration via the AWS CLI, `logs` tails `/aws/lambda/<project>-fn`, and `sleep`/`wake` manage only the database (compute needs no scaling). `exec` and `rollback` are ECS-only and exit with the Lambda-native alternative.
+
+### Fargate vs Lambda tradeoffs
+
+Both targets share the VPC, ECR, IAM, secrets, and CloudFront layers — pick by traffic shape, not by feature set:
+
+- **Cost crossover.** Lambda idles at $0 and bills per request (API Gateway HTTP API at $1.00 per million requests, plus Lambda request and GB-second compute charges), so sporadic or bursty workloads cost pennies. Under sustained high-concurrency traffic those per-request charges catch up to and pass Fargate's flat ~$31/mo compute+ALB baseline, and always-on containers become the more cost-effective steady state. See [Understanding Your AWS Bill](/grada/guides/understanding-your-bill/).
+- **Database connections.** Fargate runs a fixed handful of tasks with persistent, pooled connections. Lambda can burst toward 1,000 concurrent executions, and the generated stack connects each execution straight to RDS with no proxy in between — enough simultaneous cold starts will exhaust a `db.t4g.micro` connection limit and fail queries until executions drain. For high-concurrency Lambda workloads against a relational database, keep client pools tiny with aggressive idle timeouts, or place RDS Proxy in front of the database yourself.
+- **Cold starts.** Fargate tasks are always warm behind the ALB. VPC-attached Lambda container images (any project with a database or Redis) pay multi-second cold starts on scale-out — fine for background-tolerant traffic, noticeable on latency-sensitive paths.
+- **Request limits.** API Gateway caps every Lambda invocation behind it at 30 seconds and 10 MB of payload, and a single function execution can never exceed 15 minutes — long responses, in-request file processing, SSE streams, and WebSockets don't fit. The ALB imposes no such ceilings, so ECS carries long-lived and streaming traffic.
+- **Background workers and queues.** ECS keeps a first-class worker story: Procfile workers become a dedicated service, and `queue:sqs` drives a scale-to-zero worker with queue-depth autoscaling. Lambda runs one function — Procfile workers are skipped at scaffold time, SQS queues ship without a consumer (poll from function code or wire an event source mapping yourself), and cron schedules arrive as JSON-payload invokes your code must handle.
+- **Outbound network.** ECS tasks carry public IPs and reach the open internet directly. Lambda functions attached to the VPC (any project with a database or Redis) get private-only network interfaces, and the generated VPC has no NAT gateway — so they cannot call third-party APIs unless you add NAT or VPC endpoints yourself. Non-VPC functions keep direct internet access.
+
+| | ECS Fargate + ALB | Lambda + API Gateway v2 |
+| --- | --- | --- |
+| Idle cost | ~$31/mo flat | $0 |
+| Cost at sustained scale | flat per task (cheaper steady state) | per request + compute (grows with traffic) |
+| Cold starts | none (always warm) | multi-second on VPC scale-out |
+| Max request duration | no hard cap (ALB) | 30s API Gateway cap, 15-min function max |
+| DB connections | fixed pooled tasks | per-execution, no proxy |
+| Background workers | dedicated service + SQS autoscaling | none (queues ship unconsumed) |
+| Outbound internet | yes (public IPs) | only when outside the VPC |
+| WebSockets / streaming | yes, via ALB | no |
+| Day-2 ops | `exec`, `rollback`, migration gate | adapted `status`/`logs`/`diagnose`; no `exec`/`rollback` |
+| Web scaling | fixed desired count | automatic to 1,000 concurrent |
+
+Choose **ECS Fargate** when traffic is steady or latency-sensitive (product APIs, SaaS backends), responses can exceed 30 seconds or stream, background workers or queue consumers are part of the design, or handlers need persistent database connections and outbound internet side by side.
+
+Choose **Lambda** when traffic is sporadic, bursty, or unpredictable (side projects, internal tools, webhooks), $0 idle cost matters more than warm latency, and the workload is request-scoped with no workers or long-lived connections — ideally with Aurora Serverless (which scales with the function) or no database at all.
+
+## Data and secrets
+
+- **Database** (when enabled) runs on RDS in **isolated subnets** with its own subnet group — no route to the internet. Pick the engine at scaffold time (`postgres`, `mysql`, or scale-to-zero `aurora-postgresql` via `--db-engine`). Reach it from your laptop via [`db connect`](/grada/cli/db/), and run migrations inside the VPC with [`db migrate`](/grada/cli/db/).
+- **Secrets** live in Secrets Manager as one app secret, injected as environment variables at container boot from the key map in `terraform/secret_keys.json`. See [Secrets Management](/grada/guides/secrets-management/).
+- **State** lives in an encrypted S3 bucket using native S3 locking (`use_lockfile`), so concurrent applies are safe without a lock table.
+
+## CDN, domain, and email
+
+CloudFront serves the app globally from the ALB origin. [`domain add`](/grada/cli/domain/) attaches your own hostname with an automated `us-east-1` ACM certificate; [`add email:ses`](/grada/cli/add/) provisions SES sending on the same domain with DKIM/SPF/DMARC. Both are optional day-2 steps over the base stack.
+
+## Observability
+
+One CloudWatch log group per project (`/ecs/<project>`, 14-day retention) collects web and worker streams; an alarm fires when the ALB serves more than ten 5XX errors in two minutes. [`status`](/grada/cli/status/) renders the health dashboard, [`diagnose`](/grada/cli/diagnose/) explains crashed tasks, and [`logs`](/grada/cli/logs/) streams without the console.
+
+## Operations
+
+Idle environments cost nothing in compute: [`sleep` / `wake`](/grada/cli/sleep/) scales ECS services to zero and stops RDS — printing the exact hourly/monthly savings and the 7-day AWS auto-restart timestamp — then restores the exact replica counts on wake. Console click-ops never go unnoticed: the opt-in `drift.yml` workflow runs `terraform plan` daily and opens a GitHub Issue on drift, and [`drift`](/grada/cli/drift/) runs the same check locally.
+
+## Preview workspaces
+
+Each open pull request gets a Terraform workspace (`preview.yml`) running the same files renamed by `app_name` plus an environment suffix — a full copy of the stack that `teardown.yml` destroys on close. A few resources are deliberately shared instead of copied (the ECR repository, Secrets Manager lookups), and account-wide singletons — the custom-domain ACM certificate and aliases, the SES domain identity/DKIM/DNS — are scoped to the production (`default`) workspace via `count` guards, so previews neither duplicate them nor delete them on teardown; previews serve over their own `*.cloudfront.net` URL and inherit SES sending permission. See [Ephemeral PR Previews](/grada/guides/ephemeral-pr-previews/).
+
+## See also
+
+- [Quickstart (5 minutes)](/grada/guides/quickstart/) for the fastest path through this stack.
+- [Understanding Your AWS Bill](/grada/guides/understanding-your-bill/) for what each piece costs.

package/apps/docs/src/content/docs/guides/aws-credentials.md

@@ -0,0 +1,72 @@
+---
+title: Troubleshooting AWS Credentials & Authentication
+description: Troubleshooting AWS authentication, expired tokens, and SSO logins.
+sidebar:
+  order: 9
+---
+
+`grada` interacts directly with AWS APIs (Secrets Manager, ECS, CloudWatch, S3) using the official AWS SDK v3 default credential provider chain.
+
+When you encounter an `UnrecognizedClientException` or `ExpiredTokenException`, your local AWS authentication state has lapsed. Every command reports this identically: it stops its spinner, suggests `aws sso login` or `aws configure`, links back to this guide, and exits 1.
+
+If the message instead says the AWS CLI was not found, install it first ([install guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)), then refresh your credentials as below.
+
+---
+
+## 1. Quick Refresh by Setup Type
+
+### A. AWS IAM Identity Center (AWS SSO)
+If your organization or personal account uses IAM Identity Center / SSO:
+
+```bash
+# Log in to refresh your active session token
+aws sso login
+```
+
+If you use named profiles:
+```bash
+aws sso login --profile your-profile-name
+export AWS_PROFILE=your-profile-name
+```
+
+---
+
+### B. Standard Long-Lived Access Keys (`~/.aws/credentials`)
+If you use long-lived `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` pairs:
+
+1. Verify credentials configured:
+   ```bash
+   aws sts get-caller-identity
+   ```
+2. If invalid or missing:
+   ```bash
+   aws configure
+   ```
+
+---
+
+### C. Temporary Session Tokens (`AWS_SESSION_TOKEN`)
+If you assumed an IAM role or exported manual session tokens in your terminal:
+
+Check if stale environment variables are overriding your global credentials:
+```bash
+echo $AWS_SESSION_TOKEN
+```
+If expired, clear them:
+```bash
+unset AWS_ACCESS_KEY_ID
+unset AWS_SECRET_ACCESS_KEY
+unset AWS_SESSION_TOKEN
+```
+Then re-authenticate via `aws configure` or `aws sso login`.
+
+---
+
+## 2. Common Error References
+
+| Error Name | Root Cause | Solution |
+| :--- | :--- | :--- |
+| `UnrecognizedClientException` | The security token is unrecognized, mistyped, or expired. | Run `aws sso login` or re-run `aws configure`. |
+| `ExpiredTokenException` | Temporary STS credentials passed their validity window (typically 1–12 hrs). | Refresh STS credentials or log into SSO again. |
+| `AccessDeniedException` | User or role lacks IAM permissions for ECS, Secrets Manager, or S3. | Ensure your IAM user has adequate deployment permissions. |
+| `ResourceNotFoundException` | Target cluster, secret, or log group does not exist in target region. | Verify `AWS_REGION` and ensure infrastructure was provisioned via `grada apply`. |

package/apps/docs/src/content/docs/guides/background-workers.md

@@ -0,0 +1,45 @@
+---
+title: Background Workers
+description: Run background jobs on a private ECS worker service — how it is created, SQS scale-to-zero, and day-2 operations.
+---
+
+Long-running jobs (Celery, Sidekiq, BullMQ workers, queue pollers) run on a second ECS Fargate service that shares your web container's image, secrets, and database wiring but takes no HTTP traffic. (ECS targets only — `--target lambda` projects run a single function with no worker service; Procfile workers are skipped at scaffold time.)
+
+## What the worker service is
+
+`terraform/worker.tf` defines a private `aws_ecs_service.worker`: same ECR image and cluster as the web service, same Secrets Manager payload and database variables, and its own task definition whose container runs your worker command instead of the web server. There is deliberately **no load balancer block**, so nothing routes internet traffic to it. Logs go to the shared `/ecs/<project>` group with the `worker` stream prefix, keeping them separable from web logs.
+
+New services start with `desired_count = 1`, but the service ignores `desired_count` changes in Terraform so queue-depth auto-scaling can manage the count without apply-time drift.
+
+## How you get one
+
+The worker service is created at init time, from either source:
+
+- A `worker:` entry in your `Procfile` — see [Heroku (Procfile)](/grada/migrations/heroku-procfile-to-aws/).
+- The scaffold worker prompt, pre-filled from what detection finds (Procfile entry, worker dependencies, or Compose commands) — see [`npx grada-run`](/grada/cli/init/).
+
+Either path writes the command into `worker.tf` (`WORKER_COMMAND`) and manages the file like any other generated file.
+
+## SQS scale-to-zero
+
+`add queue:sqs` extends the worker with Application Auto Scaling driven by `ApproximateNumberOfMessagesVisible`:
+
+- **Scale out:** one task per minute while the queue is non-empty, up to 5 tasks.
+- **Scale in:** back to 0 after the queue stays empty for five minutes — a parked worker costs nothing in compute.
+
+The scaling target, both step-scaling policies, and both CloudWatch alarms live in `sqs.tf`, and AWS creates the required service-linked role automatically on first registration. Addon environment variables are injected into the worker container as well as the web container.
+
+## Adding a worker later
+
+There is no `add worker` command: if you scaffolded without a worker, `add queue:sqs` still creates the queue and injects its URLs, but renders the auto-scaling block **commented out**. To activate it later, add `terraform/worker.tf` — re-run init (backup and regenerate, then restore hand-edited and addon files from the `.bak` copy; see [Re-running Init Safely](/grada/guides/rerun-init/)) or copy `worker.tf` from an equivalent fresh scaffold and set the command — uncomment the block in `sqs.tf`, and `apply`.
+
+## Day-2 operations and cost
+
+- Stream worker output with [`logs`](/grada/cli/logs/) — worker entries carry the `worker` stream prefix in the shared group — and open a shell with [`exec`](/grada/cli/exec/) using its service and container overrides.
+- A running worker roughly doubles the Fargate baseline (~$18.02/mo at micro size), falling to $0 compute while its queue is empty; each open PR preview runs its own copy while the PR is open. See [Understanding Your AWS Bill](/grada/guides/understanding-your-bill/).
+
+## See also
+
+- [Heroku (Procfile)](/grada/migrations/heroku-procfile-to-aws/) for Procfile process mapping.
+- [add](/grada/cli/add/) for `queue:sqs` flags and cost drivers — or `add cron` for scheduled one-off tasks that need no always-on worker.
+- [Re-running Init Safely](/grada/guides/rerun-init/) for regeneration behavior.

package/apps/docs/src/content/docs/guides/cicd-pipeline.md

@@ -0,0 +1,64 @@
+---
+title: CI/CD Pipeline & First Deploy
+description: How the generated GitHub Actions workflow builds, scans, and deploys your app with zero stored AWS keys.
+sidebar:
+  order: 1
+---
+
+Every `npx grada-run` run generates `.github/workflows/deploy.yml`. This page explains what that pipeline does, when it runs, and why your site returns `503` until the first push completes.
+
+## When it runs
+
+The workflow triggers on two events (`templates/github/deploy.yml`):
+
+- A `push` to your deploy branch (`{{DEPLOY_BRANCH}}`, chosen during setup).
+- A weekly Sunday cron (`0 0 * * 0`) that re-applies the Terraform configuration, so drift and base-image updates converge automatically.
+
+The region, ECR repository, ECS cluster, and ECS service names are baked in at generation time as `<project>-repo`, `<project>-cluster`, and `<project>-service`.
+
+## No stored AWS keys
+
+Authentication uses GitHub OIDC, not long-lived credentials. The workflow declares:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+```
+
+and assumes the `{{PROJECT_NAME}}-github-actions-role` IAM role created by `terraform/oidc.tf`. There is nothing to rotate and no secret to leak. (If your AWS account already has a GitHub OIDC provider, set `create_oidc_provider = false` in `terraform/oidc.tf` — see [apply](/grada/cli/apply/).)
+
+## The five stages
+
+1. **IaC security scan.** Trivy scans `terraform/` for vulnerabilities, secrets, and misconfigurations (`CRITICAL,HIGH`). It is informational only (`exit-code: '0'`), so it never blocks the build; results land in the GitHub step summary.
+2. **Infrastructure sync.** The `grada-run/grada-action@v1` step runs Terraform against `terraform/`, so infrastructure changes committed alongside code are applied before the new image rolls out.
+3. **Build & push.** The workflow logs in to Amazon ECR, runs `docker build` on your generated `Dockerfile`, and tags the result with both the short commit SHA (e.g. `abc1234`, the immutable deploy artifact) and `latest` (kept for convenience and scanning).
+4. **Container scan.** Trivy scans the built image (`os,library`, `ignore-unfixed: true`), again informational only with results in the step summary.
+5. **Deploy.** Both tags are pushed to ECR then the workflow registers a brand-new ECS task definition revision pinned to the SHA-tagged image and deploys it (`aws ecs update-service --task-definition <new-revision> --force-new-deployment`), which rolls the new image across your tasks behind the ALB. Because every push creates a fresh revision, `npx grada-run rollback [revision]` always has history to return to — and Terraform is configured to leave the service's task definition alone (`lifecycle { ignore_changes = [task_definition] }`), so the next `apply` never reverts a code-only deploy.
+
+## Lambda target pipeline
+
+On `--target lambda` projects the same `deploy.yml` shape applies, but the Deploy stage pushes the SHA-tagged image to ECR and calls `aws lambda update-function-code` (then `aws lambda wait function-updated`) instead of registering a task definition — Terraform ignores the function's `image_uri` (mirroring the ECS `task_definition` rule) so code deploys and `apply` never fight. There is no task-revision history, so `rollback` is ECS-only; redeploy a previous SHA tag to revert.
+
+## Optional pre-deploy migration gate
+
+`db migrate --cmd "<command>" --setup-ci` adds a migration step to the Deploy stage: after the new task definition is registered and before the service updates, it runs your migration command as a one-off ECS task against the newly built image — a failing migration halts the release automatically. Re-running the command updates the wired step in place. `init` can wire the same gate at scaffold time with `--setup-ci-migrate` (or the interactive prompt when a database and migration command are detected). ECS targets only — Lambda projects skip the gate (run migrations from CI against your database endpoint instead). See [`db migrate`](/grada/cli/db/).
+
+## Scheduled drift detection (opt-in)
+
+`--setup-ci-drift` (or `drift --setup` on an existing project) scaffolds a second workflow, `.github/workflows/drift.yml`, that runs `terraform plan` daily at 06:00 UTC plus on manual dispatch. When live AWS state differs from Terraform it opens (or updates, without spamming) a GitHub Issue labeled `iac-drift` with the plan diff; when drift resolves it comments `✅ Drift resolved` and closes the issue. Set a `SLACK_WEBHOOK_URL` repository secret to also post alerts to Slack. Run `npx grada-run drift` anytime for the same check locally. See [`drift`](/grada/cli/drift/).
+
+## Why you see a 503 first
+
+`npx grada-run apply` provisions the ALB, cluster, and service, but no container image exists until this workflow runs once. Pushing to your deploy branch (`git add . && git commit -m "ci: infra" && git push`) builds and deploys the first image, clearing the `503`. If the service stays unhealthy after that, run `npx grada-run diagnose` — usually the container failed its ALB health check (see [Dockerfiles](/grada/guides/dockerfiles/)). (On `--target lambda` projects the same flow provisions the API Gateway and function instead; `apply` seeds a placeholder image so Day-0 succeeds, and the first push replaces it.)
+
+## Related workflows
+
+- `preview.yml` / `teardown.yml` exist only when ephemeral PR previews are enabled. See [Ephemeral PR Previews](/grada/guides/ephemeral-pr-previews/).
+- Secrets are injected at deploy time from AWS Secrets Manager, never from the repo. See [Secrets Management](/grada/guides/secrets-management/).
+
+## See also
+
+- [Quickstart](/grada/guides/quickstart/) for the 5-minute path that ends here.
+- [Supported Frameworks](/grada/guides/frameworks/) for what the pipeline builds.
+- Migrating? See [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/), and [Heroku (Procfile)](/grada/migrations/heroku-procfile-to-aws/).

package/apps/docs/src/content/docs/guides/database-connections.md

@@ -0,0 +1,64 @@
+---
+title: "Managed Database Connections"
+description: "Provision a managed AWS RDS PostgreSQL database for backend frameworks."
+sidebar:
+  order: 6
+---
+
+When you run `npx grada-run` for a backend framework (Node, Django, Rails, Go, etc.), the CLI prompts you to automatically provision a managed AWS RDS PostgreSQL database. The database adds a fixed monthly cost on top of the stack baseline — the `apply` preview itemizes it before you provision.
+
+## Zero-Trust Architecture
+
+If you select "Yes", `grada` builds a true zero-trust network topology:
+1. The PostgreSQL instance is deployed into heavily restricted **Isolated Subnets**.
+2. It is given a strict Security Group that *only* allows inbound traffic from your specific ECS Fargate containers on port `5432`.
+3. The database is completely inaccessible from the public internet.
+
+## Auto-Injected Environment Variables
+
+You do not need to configure database connection strings manually. The generated Terraform automatically creates a secure, random master password in AWS Secrets Manager and injects the following environment variables directly into your running containers:
+
+* `DB_HOST` (The internal AWS DNS endpoint)
+* `DB_PORT` (5432, or 3306 for MySQL)
+* `DB_NAME` (Your deterministic database name, derived from your project name)
+* `DB_USER` (Injected securely at runtime)
+* `DB_PASSWORD` (Injected securely at runtime)
+
+To connect your application, simply configure your ORM (Prisma, Django, TypeORM, Active Record) to read from these grada injected variables.
+
+Most frameworks expect a single connection string (e.g., `DATABASE_URL`). Construct it from the injected variables at runtime:
+
+```bash
+DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
+```
+
+If the password contains special characters (e.g., `@`, `[`, `/`), percent-encode it before placing it in the URI.
+
+RDS enforces TLS (`rds.force_ssl = 1`): libpq-based clients negotiate it automatically, but drivers that default to plaintext need an explicit opt-in — append `?sslmode=require` to the URL (Prisma, JDBC-style clients) or pass the driver's SSL option (e.g. `ssl` in Node `pg`).
+
+## Running Database Migrations
+
+Because the database is in an isolated subnet, you cannot run schema migrations directly from your local laptop.
+The best practice is [`db migrate`](/grada/cli/db/) — it launches a short-lived ECS task inside your VPC that runs your migration command (auto-detected for Prisma, Drizzle, Alembic, Django, Rails, and `db:migrate` npm scripts, or pass `--cmd`), streams the logs to your terminal, and exits with your migration's exit code.
+
+To gate releases on migrations, run `db migrate --cmd "<command>" --setup-ci` once: it adds a pre-deploy step to `.github/workflows/deploy.yml` that runs migrations against the newly built image before the ECS service updates, halting the release if they fail.
+
+## Inspecting Data Locally
+
+For read-only inspection from your laptop (psql, DBeaver, Prisma Studio), open a secure tunnel with [`db connect`](/grada/cli/db/) instead of exposing the database — and run schema changes with [`db migrate`](/grada/cli/db/) so they execute inside the VPC.
+
+## Choosing an Engine
+
+When you answer "Yes" to the database prompt (or pass `--db-engine`), pick the engine that fits your workload:
+
+| Engine | What you get | Cost |
+| ------ | ------------ | ---- |
+| `postgres` (default) | RDS PostgreSQL 16 on `db.t4g.micro` | ~$13.98/mo fixed |
+| `mysql` | RDS MySQL 8.0 on `db.t4g.micro`; containers get `DB_PORT=3306` and a `DB_ENGINE=mysql` marker | ~$13.98/mo fixed |
+| `aurora-postgresql` | Aurora PostgreSQL Serverless v2, scaling 0–2 ACU with auto-pause (takes the regional Aurora default version) | $0/mo idle compute (+$0.12/ACU-hr when active, plus storage) |
+
+MySQL projects get a `mysql://` connection string from `db connect`, and `db migrate` synthesizes the matching `DATABASE_URL` scheme automatically. Aurora clusters are discovered as `<project-name>-db-cluster` by every `db` subcommand; backups and restores use cluster snapshots. The architecture preview and cost estimate reflect the provisioned engine.
+
+## Importing Existing Data
+
+Bringing a database from Heroku, Supabase, or another provider? [`db import`](/grada/cli/db/) streams a local dump (`--file`, including `.sql.gz` and Postgres `.dump` archives) or a live remote database (`--from`) into your isolated instance through a temporary SSM tunnel — the database is never exposed to do it. Credentials travel via `PGPASSWORD` / `MYSQL_PWD` and are masked in all output; take a [`db backup`](/grada/cli/db/) checkpoint first.