grada-run 0.0.1 → 0.32.0

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

@@ -0,0 +1,32 @@
+---
+title: apply
+description: Provision or update your AWS infrastructure with Terraform.
+---
+
+Run the Terraform plan/apply flow against the generated configuration.
+
+## What it does
+
+- Verifies you are in a grada project (`terraform/main.tf` must exist), exiting otherwise, so `apply` never runs against the wrong directory.
+- Renders an infrastructure preview from your Terraform config and framework detection: a `Fixed Baseline` monthly figure with per-service breakdown, one topology entry per provisioned [`add`](/grada/cli/add/) addon (collapsing to a single `Addons (N)` line when three or more are active), and a one-line `Usage-based (N addons)` summary of metered billing drivers (shown only when usage-billed addons are present). With `--dry-run` it stops there and provisions nothing.
+- Otherwise runs `terraform init -upgrade` followed by `terraform apply -auto-approve` in `terraform/`, streaming progress, then prints the live URLs from the Terraform outputs (`cloudfront_url` and `alb_direct_url`, or `api_gateway_url` on `--target lambda`) plus the `git push` command that deploys your app and clears the initial 503.
+- On `--target lambda` projects, ensures the ECR repository exists first and seeds a minimal placeholder image under `:latest` when nothing has been pushed yet (Lambda rejects empty repositories), so Day-0 provisioning succeeds before the first code push.
+- Asks for confirmation after the preview; declining aborts without provisioning anything.
+- If the S3 state bucket is missing (e.g. deleted manually), offers to recreate it and resume automatically instead of failing.
+- If the environment is asleep (a `.grada/sleep-state.json` entry exists), warns you to run [`wake`](/grada/cli/sleep/) first — applying would start tasks against a stopped database.
+- On the known GitHub OIDC provider conflict (`EntityAlreadyExists` for `token.actions.githubusercontent.com`), tells you to set `create_oidc_provider = false` in `terraform/oidc.tf` and re-run; other failures print the Terraform error and the manual `cd terraform && terraform apply` fallback.
+
+## Usage
+
+```bash
+npx grada-run apply
+npx grada-run apply --dry-run
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--dry-run` | Render a preview of the planned changes without applying them. |
+
+`apply` shells out to the `terraform` binary in your generated `terraform/` directory and streams progress while it runs.

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

@@ -0,0 +1,200 @@
+---
+title: db
+description: Tunnel to, migrate, back up, and restore your managed RDS database.
+---
+
+Run migrations, create safety checkpoints, and restore your managed database — all from the terminal, without ever exposing the database to the public internet.
+
+## Commands
+
+```bash
+npx grada-run db connect                  # Open a secure local tunnel
+npx grada-run db migrate --cmd "<command>" # Run migrations inside your VPC
+npx grada-run db backup                   # Create a snapshot checkpoint
+npx grada-run db restore <snapshot-id>    # Restore from a snapshot
+npx grada-run db enable-vector            # Enable pgvector for AI embeddings
+npx grada-run db import --file <dump.sql> # Import a SQL dump
+```
+
+All commands work across engines: RDS PostgreSQL, RDS MySQL 8.0, and Aurora PostgreSQL Serverless v2 (see `--db-engine` in [init](/grada/cli/init/)). `db connect` prints `mysql://` URIs and tunnels to port `3306` for MySQL, and discovers Aurora clusters via `<project-name>-db-cluster` automatically.
+
+## db connect
+
+Connect your local tools (psql, DBeaver, DataGrip) or a local `.env` file directly to your isolated RDS instance. The command tunnels through a running ECS container as a jump host.
+
+- Finds your RDS database (`<project-name>-db`, `<project-name>-db-cluster` for Aurora, or the `<workspace>` variants for PR-preview environments) and reads its endpoint and managed credentials from Secrets Manager.
+- Prints the local host, port, database name, username, and a copy-pasteable `postgresql://` connection string. The password stays masked as `********` unless you pass `--show-credentials`.
+- Finds a running container for the current project automatically and opens the tunnel via the Session Manager port-forwarding session. Press Ctrl+C to close it.
+- Resolves its inputs automatically: cluster, service, and region (same order as `exec`: explicit flag → environment variable → `terraform/main.tf` → default).
+- When no database is provisioned, or no containers are running, explains what to do (`init`/`apply`/`status`) and exits 1 instead of failing cryptically.
+- On expired AWS credentials, points you to `aws sso login` / `aws configure` and exits 1 instead of throwing.
+- Emits a `db_connect_run` telemetry event recording success and outcome. Credentials are never included in telemetry.
+
+```bash
+npx grada-run db connect
+npx grada-run db connect --port 5544
+npx grada-run db connect --show-credentials
+npx grada-run db connect --workspace pr-123
+```
+
+Paste the printed connection string into DBeaver, or export it locally:
+
+```bash
+export DATABASE_URL="postgresql://dbadmin:<password>@localhost:5432/<dbname>"
+```
+
+The printed connection string already percent-encodes special characters in the username and password (AWS-generated passwords often contain `@`, `[`, or `/`). The standalone `Password:` line is shown verbatim — encode it yourself if you build a URI by hand instead of copying ours.
+
+| Flag | Description |
+| ---- | ----------- |
+| `--port <port>` | Local port for the tunnel (defaults to the remote database port: `5432` for PostgreSQL/Aurora, `3306` for MySQL). Must be a number between 1 and 65535. |
+| `--show-credentials` | Reveal the decrypted password in the terminal output. Masked by default. |
+| `--workspace <name>` | Target a PR-preview environment (e.g. `--workspace pr-123`). Falls back to the workspace in `.terraform/environment`. |
+| `--cluster <name>` | Explicit cluster name override. |
+| `--service <name>` | Explicit service name override. |
+| `--region <region>` | Explicit AWS region override. |
+
+## db migrate
+
+Run schema migrations or seed scripts (Prisma, Drizzle, Alembic, Django, Rails, or anything custom) inside your VPC as a short-lived ECS task — no tunnel, no local database access needed. Logs stream live to your terminal, and the command exits with your migration's own exit code.
+
+When you omit `--cmd`, the project is inspected for a known migration setup (`db:migrate` / `migrate` npm scripts, Prisma, Drizzle, Alembic, Django, Rails) and the detected command is used (in CI) or offered for confirmation (interactively).
+
+When your task definition carries discrete `DB_*` credentials, the command synthesizes the engine-matching `DATABASE_URL` at runtime — with `PGSSLMODE=require` for PostgreSQL, since RDS/Aurora enforces `rds.force_ssl = 1`.
+
+```bash
+npx grada-run db migrate --cmd "npx prisma migrate deploy"
+npx grada-run db migrate                     # auto-detect the command
+npx grada-run db migrate --cmd "npm run db:seed" --timeout 1200
+```
+
+| Flag | Description |
+| ---- | ----------- |
+| `--cmd <command>` | Migration command to run. Auto-detected when omitted. |
+| `--task-def <task-def>` | Task definition (ARN or `family:revision`) to run. Defaults to the live service revision. |
+| `--timeout <seconds>` | Give up after this long (default `600`). The task is stopped automatically. |
+| `--setup-ci` | Install the pre-deploy migration gate into `.github/workflows/deploy.yml` instead of running. |
+| `--project-name <name>` | Explicit project name override. |
+| `--workspace <name>` | Target a PR-preview environment. |
+| `--cluster <name>` | Explicit cluster name override. |
+| `--service <name>` | Explicit service name override. |
+| `--container <name>` | Explicit container name override. |
+| `--region <region>` | Explicit AWS region override. |
+
+### Pre-deploy migration gate
+
+`db migrate --setup-ci` adds a step to your deploy workflow that runs migrations against the newly built image **before** the ECS service updates — a failing migration halts the release automatically:
+
+```bash
+npx grada-run db migrate --cmd "npx prisma migrate deploy" --setup-ci
+```
+
+The step is re-installed cleanly on every run, so re-running the command updates the wired migration command in place.
+
+## db backup
+
+Create a point-in-time safety checkpoint of your database (a cluster snapshot for Aurora) before risky operations like migrations or restores. The command waits until the snapshot is ready, then prints the restore command for it.
+
+```bash
+npx grada-run db backup
+npx grada-run db backup --id pre-migration-checkpoint
+npx grada-run db backup --no-wait          # return immediately
+```
+
+| Flag | Description |
+| ---- | ----------- |
+| `--id <snapshot-id>` | Custom snapshot id. Defaults to `<db>-manual-YYYYMMDD-HHmmss`. |
+| `--timeout <seconds>` | Give up waiting after this long (default `900`). Creation continues in the background. |
+| `--no-wait` | Return immediately without waiting for the snapshot to become available. |
+| `--project-name <name>` | Explicit project name override. |
+| `--workspace <name>` | Target a PR-preview environment. |
+| `--db-identifier <id>` | Explicit RDS identifier override (instance or Aurora cluster). |
+| `--region <region>` | Explicit AWS region override. |
+
+## db restore
+
+Restore your database from a manual or automated snapshot. Omit the snapshot id to pick from a list of available checkpoints, newest first.
+
+Restoring works through Terraform: the command pins the snapshot in `terraform/database.tf` (`snapshot_identifier`, in the instance or `aws_rds_cluster` block), so the VPC wiring, security groups, and Secrets Manager integration stay intact and future applies stay clean. Run `npx grada-run apply` afterwards to perform the restore.
+
+```bash
+npx grada-run db restore                  # pick a snapshot interactively
+npx grada-run db restore my-snapshot-id
+npx grada-run db restore my-snapshot-id --yes   # skip confirmation (for CI)
+```
+
+> **Restoring replaces your current data.** Everything written after the snapshot is permanently discarded. Create a safety checkpoint with `npx grada-run db backup` first if you might need the current data.
+
+| Flag | Description |
+| ---- | ----------- |
+| `<snapshot-id>` | Snapshot to restore (positional). Omit to choose interactively. |
+| `--yes` | Skip the confirmation prompt. Required in non-interactive environments. |
+| `--project-name <name>` | Explicit project name override. |
+| `--workspace <name>` | Target a PR-preview environment. |
+| `--db-identifier <id>` | Explicit RDS identifier override (instance or Aurora cluster). |
+| `--region <region>` | Explicit AWS region override. |
+
+After `apply` completes, leave `snapshot_identifier` in `terraform/database.tf` — it keeps subsequent applies drift-free.
+
+## db enable-vector
+
+Enable the `pgvector` extension on RDS PostgreSQL or Aurora PostgreSQL for AI/RAG embeddings — no OpenSearch cluster required. Runs a one-off ECS task inside your VPC that executes `CREATE EXTENSION IF NOT EXISTS vector` using whatever client your image already has (`psql`, `pg`/`@prisma/client`, or `psycopg`), negotiating TLS on every branch for `rds.force_ssl` databases, then verifies the installed version. Refuses to run on MySQL projects.
+
+```bash
+npx grada-run db enable-vector
+npx grada-run db enable-vector --task-def myapp-task:4 --timeout 300
+```
+
+If your project has a Prisma schema without `postgresqlExtensions`, the command prints the snippet to add. When the container has no usable PostgreSQL client, it exits 3 with install guidance instead of failing cryptically.
+
+| Flag | Description |
+| ---- | ----------- |
+| `--task-def <task-def>` | Task definition to run (defaults to the service's active revision). |
+| `--timeout <seconds>` | Give up waiting after this long (default `600`). |
+| `--project-name <name>` | Explicit project name override. |
+| `--workspace <name>` | Target a PR-preview environment. |
+| `--cluster <name>` | Explicit cluster name override. |
+| `--service <name>` | Explicit service name override. |
+| `--container <name>` | Explicit container name override. |
+| `--region <region>` | Explicit AWS region override. |
+
+## db import
+
+Stream a local SQL dump or a remote database (Heroku, Supabase, Render, Railway) directly into your isolated RDS instance through an automated background SSM tunnel — the database stays private throughout.
+
+```bash
+npx grada-run db import --file ./prod.sql --yes
+npx grada-run db import --file ./prod.sql.gz --yes   # gzipped dumps stream through gunzip
+npx grada-run db import --file ./prod.dump --yes     # Postgres custom archives via pg_restore
+npx grada-run db import --from "postgresql://user:pass@host:5432/db" --yes
+```
+
+- Pass exactly one of `--file` / `--from` (or pick interactively when neither is given).
+- `.dump` archives restore with `pg_restore --no-owner --no-acl`; `--from` pipes `pg_dump` (`mysqldump` for MySQL targets) straight into the target client, so multi-gigabyte databases never touch your disk.
+- **Secrets never touch argv or disk.** Target credentials come from Secrets Manager and travel via `PGPASSWORD` / `MYSQL_PWD`; `--from` passwords are parsed out of the URL and passed the same way. Validation errors print the URL with the password masked as `****`.
+- **TLS by default.** Postgres clients on both sides run with `PGSSLMODE=require` (unless you pinned `PGSSLMODE`), since RDS/Aurora enforces `rds.force_ssl = 1`.
+- The tunnel binds an ephemeral loopback port (never `5432`/`3306`, which may already serve a local database) and is always torn down afterwards, even on failure or Ctrl+C.
+- Requires the matching client tools locally: `psql` / `pg_restore` / `pg_dump` (`brew install libpq`, then add `$(brew --prefix libpq)/bin` to `PATH`) or `mysql` / `mysqldump` (`brew install mysql-client`).
+
+| Flag | Description |
+| ---- | ----------- |
+| `--file <path>` | Local `.sql`, `.sql.gz`, or `.dump` file to import. |
+| `--from <url>` | Source `postgresql://` or `mysql://` URL (must include a database name). |
+| `--yes` | Skip the confirmation prompt. Required in non-interactive environments. |
+| `--project-name <name>` | Explicit project name override. |
+| `--workspace <name>` | Target a PR-preview environment. |
+| `--db-identifier <id>` | Explicit RDS identifier override. |
+| `--region <region>` | Explicit AWS region override. |
+
+> **Importing writes to your live database.** Take a safety checkpoint with `npx grada-run db backup` before importing into a database you care about.
+
+## Prerequisites
+
+- Run `npx grada-run apply` first with a managed database provisioned (answer "Yes" to the database prompt during `init`).
+- `db connect` additionally needs the AWS CLI and the Session Manager plugin (`brew install session-manager-plugin` on Mac; the command prints the right instructions for your OS when it's missing). On expired credentials, refresh with `aws sso login` or `aws configure`. See the [AWS credentials guide](/grada/guides/aws-credentials/).
+
+## See also
+
+- [Managed Database Connections](/grada/guides/database-connections/)
+- [exec](/grada/cli/exec/)
+- [status](/grada/cli/status/)

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

@@ -0,0 +1,31 @@
+---
+title: destroy
+description: Tear down all AWS resources provisioned for this project.
+---
+
+Permanently delete the AWS infrastructure created by `apply` when a project is retired or needs a clean rebuild, protecting you from ongoing AWS charges.
+
+## What it does
+
+- Verifies you are in a grada project (`terraform/backend.tf` must exist) and that the `terraform` binary is installed, exiting otherwise.
+- Asks for explicit confirmation before doing anything destructive; declining cancels with no changes.
+- Before destroying, wakes a stopped or transitional-state database back to `available` (RDS refuses to delete databases that aren't available), so tearing down an asleep environment succeeds instead of failing mid-destroy; aborts with a retry message if the database never becomes ready.
+- Runs `terraform destroy -auto-approve` in `terraform/`, streaming progress, so all compute resources (ECS or Lambda, ALB or API Gateway, database, and related resources) are removed.
+- Parses the state bucket name and region out of `terraform/backend.tf` (region defaults to `us-east-2` when not found), then optionally asks whether to also empty and delete the S3 state bucket via `teardownStateBucket`. Answering "No" keeps the bucket so `apply` can restore the infrastructure later.
+- Emits an `infrastructure_destroyed` telemetry event recording success and whether the state bucket was retained.
+
+## Usage
+
+```bash
+npx grada-run destroy
+```
+
+## Flags
+
+This command accepts no CLI flags. Both confirmation prompts are interactive.
+
+## See also
+
+- [apply](/grada/cli/apply/)
+- [doctor](/grada/cli/doctor/)
+- [sleep & wake](/grada/cli/sleep/) (pause billing temporarily instead of tearing down)

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

@@ -0,0 +1,37 @@
+---
+title: diagnose
+description: Diagnose failing ECS deployments from logs and task state.
+---
+
+Inspect recent ECS task failures and CloudWatch logs for the current project.
+
+## What it does
+
+- Saves you from digging through the AWS console by finding the most recently stopped ECS task for this project and showing why it stopped plus the failing container's recent log events (up to 50 lines).
+- Resolves its inputs automatically: the AWS region from `AWS_REGION`, falling back to `region` in `terraform/main.tf` (default `us-east-2`); the cluster (`<project-name>-cluster`, overridable via `ECS_CLUSTER`); and the log group (`/ecs/<project-name>`, overridable via `ECS_LOG_GROUP`). The project name itself comes from `app_name` in `terraform/main.tf`, falling back to the current directory name.
+- Lists up to 100 recent stopped tasks, describes them in a single batch, and diagnoses the most recently stopped one (by container exit time, falling back to stop/start/creation time): stopped reason, failing container name, exit code, container reason, and how long ago it stopped.
+- Reports recovery instead of a stale crash: when the crash belongs to a superseded task-definition revision, or a running task started after the stop, prints the previous crash as one-line context (no log dump) and exits healthy.
+- Fetches logs from the crashed task's own CloudWatch stream first, falling back to the last hour of group-wide events; reports a missing log group distinctly instead of showing an empty result.
+- Makes no changes to your infrastructure; it is read-only. Prints a healthy message and exits when no stopped tasks exist.
+- On `--target lambda` projects, checks function state and configuration via the AWS CLI and tails the function's recent log events instead of inspecting ECS tasks.
+- On expired AWS credentials, points you to `aws sso login` / `aws configure` and the [AWS credentials guide](/grada/guides/aws-credentials/), then exits with code 1 instead of throwing.
+- Emits a `diagnose_run` telemetry event recording success and whether the service was healthy.
+
+## Usage
+
+```bash
+npx grada-run diagnose
+npx grada-run wtf
+```
+
+`wtf` is an alias for `diagnose`.
+
+## Flags
+
+This command accepts no CLI flags. Region, cluster, and log group are resolved as described above, not from flags.
+
+## See also
+
+- [exec](/grada/cli/exec/)
+- [status](/grada/cli/status/)
+- [ADR-0004: IaC-Driven Diagnostic Context](/grada/adrs/0004-iac-driven-diagnostic-context/)

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

@@ -0,0 +1,28 @@
+---
+title: doctor
+description: Check that required tools are installed before provisioning.
+---
+
+Verify your machine is ready to provision and deploy, telling you exactly which dependency to install when something is missing.
+
+## What it does
+
+- Checks for the four required binaries — `terraform`, `aws` (AWS CLI), `docker`, and `git` — and prints a pass/fail line for each with an install hint for anything missing (Homebrew on macOS, distro-appropriate guidance on Linux, `winget` on native Windows).
+- Makes no changes to your project or cloud resources; it is a read-only check.
+- Prints a success message when everything is present, or a reminder to install the missing dependencies first.
+- Emits a `doctor_run` telemetry event recording whether all checks passed plus per-check outcomes (`passed_checks`, `failed_checks`, `total_failed` using stable check IDs — never paths or error text).
+
+## Usage
+
+```bash
+npx grada-run doctor
+```
+
+## Flags
+
+This command accepts no CLI flags.
+
+## See also
+
+- [npx grada-run](/grada/cli/init/)
+- [apply](/grada/cli/apply/)

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

@@ -0,0 +1,57 @@
+---
+title: domain
+description: Attach a custom domain to your CloudFront distribution with automated ACM TLS certificates and DNS verification.
+---
+
+Serve your application from your own domain with automated edge TLS — no manual certificate requests, validation emails, or CloudFront console edits.
+
+## What it does
+
+- `domain add <domain>` provisions an ACM TLS certificate in `us-east-1` (required by CloudFront) and wires it into your distribution's `aliases` and `viewer_certificate`.
+- With `--zone-id <id>`, validation and routing are fully automated: grada creates the ACM validation records plus apex `A`/`AAAA` alias records in your Route 53 hosted zone, then binds the certificate to CloudFront in a single `apply`.
+- Without `--zone-id`, you get a guided 2-step flow for external DNS providers (Cloudflare, Namecheap): `domain add` stages the certificate, `domain status` shows the exact CNAME records to paste, and `domain verify` activates the domain once DNS is in place.
+- `domain status` shows the configured domain, its mode, whether CloudFront is wired, and a copy-paste DNS record table.
+- `domain remove` deletes the domain configuration and restores the free `*.cloudfront.net` default certificate.
+- PR preview workspaces are unaffected: domain resources are scoped to the production workspace, so previews keep serving over their own `*.cloudfront.net` URL and teardowns never touch your certificate, aliases, or DNS.
+- Domain configuration lives in `terraform/domain.tf`, so `destroy` tears it down and `eject` keeps it automatically.
+- Emits a `domain_run` telemetry event recording the subcommand and outcome.
+
+## Usage
+
+```bash
+# Route 53, fully automated (one step)
+npx grada-run domain add example.com --zone-id Z1234567890ABC
+npx grada-run apply
+
+# External DNS, guided (two steps)
+npx grada-run domain add example.com
+npx grada-run apply
+# add the printed CNAMEs at your DNS provider, then:
+npx grada-run domain verify
+npx grada-run apply
+
+# Inspect or remove
+npx grada-run domain status
+npx grada-run domain remove
+```
+
+To replace a configured domain, run `domain add <new-domain>` again with `--force` — the old domain is swapped out of CloudFront cleanly.
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--zone-id <id>` | Route 53 hosted zone ID for automated validation and routing. Accepts a bare ID (`Z123…`) or the console's `/hostedzone/Z123…` form. Only applies to `domain add`. |
+| `--activate` | Activate immediately in external-DNS mode (skips the pending stage). Make sure your validation CNAMEs exist first — `apply` waits on DNS propagation. Only applies to `domain add`. |
+| `--force` | Replace an already-configured domain. Without it, re-adding refuses to clobber your configuration. Only applies to `domain add`. |
+| `--yes` | Skip the confirmation prompt. Required in headless/CI mode. Only applies to `domain remove`. |
+
+Requires a project initialized with `grada` (`terraform/cloudfront.tf` must exist).
+
+> **One domain per project:** each project manages a single custom domain. Need apex plus `www`? Configure the apex here and add a redirect rule for `www` at your DNS provider.
+
+## See also
+
+- [add](/grada/cli/add/) (provision `email:ses` on the same domain)
+- [apply](/grada/cli/apply/)
+- [destroy](/grada/cli/destroy/)

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

@@ -0,0 +1,40 @@
+---
+title: drift
+description: Detect out-of-band AWS changes with terraform plan, locally or on a daily GitHub Actions schedule.
+---
+
+Catch console click-ops before they surprise you: compare live AWS state against Terraform, locally on demand or daily in CI with automatic GitHub Issues.
+
+## What it does
+
+- `drift` runs `terraform init` + `terraform plan -detailed-exitcode` in `terraform/` and reports `✅ No infrastructure drift detected` (exit `0`), `⚠ Infrastructure drift detected!` with a resource summary (exit `2`), or a plan failure (exit `1`).
+- `drift --setup` (alias: `drift init`) scaffolds `.github/workflows/drift.yml` into an existing project, reusing your deploy workflow's OIDC role — no extra secrets needed.
+- `--setup-ci-drift` scaffolds the same workflow during `grada` scaffolding.
+- The scheduled workflow runs daily at 06:00 UTC (plus a manual `workflow_dispatch` trigger): on drift 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 drift alerts to Slack.
+- Emits a `drift_run` telemetry event recording the action and outcome.
+
+## Usage
+
+```bash
+npx grada-run drift
+npx grada-run drift --setup
+npx grada-run drift --setup --force
+npx grada-run --setup-ci-drift
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--setup` | Scaffold `.github/workflows/drift.yml` instead of running a local check. |
+| `--force` | Overwrite an existing `drift.yml` on `--setup`. |
+| `--region <region>` | Explicit AWS region override. |
+| `--project-name <name>` | Explicit project name override (defaults to the name in `terraform/main.tf`, then the directory name). |
+
+Requires a project initialized with `grada` (`terraform/main.tf` must exist) and the Terraform CLI installed for local checks.
+
+## See also
+
+- [apply](/grada/cli/apply/) (reconcile drifted state)
+- [init](/grada/cli/init/)

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

@@ -0,0 +1,29 @@
+---
+title: eject
+description: Decouple your project from grada into vanilla Terraform.
+---
+
+Take permanent, sole ownership of your infrastructure files when you no longer want the CLI managing them, while keeping everything running in AWS.
+
+## What it does
+
+- Asks for explicit confirmation (defaulting to "No"); declining cancels with no changes.
+- Strips grada metadata from your local files: removes the `# grada generated infrastructure` header and the `default_tags { tags = { ManagedBy = "grada" } }` block from `terraform/main.tf`, and removes the `# grada backups` block from `.gitignore`.
+- Recursively deletes every `*.bak.*` backup file in the project (skipping `node_modules` and `.git`).
+- Leaves your infrastructure fully operational as raw, standalone Terraform. As a final step, run `terraform apply` inside `terraform/` so AWS syncs state and removes the live `ManagedBy` tags.
+- Emits a `project_ejected` telemetry event. This cannot be undone.
+
+## Usage
+
+```bash
+npx grada-run eject
+```
+
+## Flags
+
+This command accepts no CLI flags. The confirmation prompt is interactive.
+
+## See also
+
+- [apply](/grada/cli/apply/)
+- [destroy](/grada/cli/destroy/)

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

@@ -0,0 +1,49 @@
+---
+title: exec
+description: Open an interactive shell inside your running ECS container.
+---
+
+Drop into a secure shell inside your live Fargate container to inspect files, check environment variables, or debug a running app — without opening the AWS console.
+
+## What it does
+
+- Finds a running container for the current project automatically and opens an interactive shell (`/bin/sh` by default) via ECS Exec.
+- Resolves its inputs automatically: cluster (`<project-name>-cluster`, overridable via `ECS_CLUSTER`), service (`<project-name>-service`, overridable via `ECS_SERVICE`), container (`<project-name>-container`, overridable via `ECS_CONTAINER`), and region (`--region` → `AWS_REGION` → `terraform/main.tf` → `us-east-2`).
+- Checks that the AWS CLI is installed first; if missing, prints install links and exits 1 instead of failing cryptically.
+- Checks that the Session Manager plugin is installed next; if missing, prints install instructions for your OS (`brew install session-manager-plugin` on Mac, download links on Windows/Linux) and exits 1.
+- When no containers are running (e.g. scaled to zero or still booting), explains that a running container is required, points you to `status` and `apply`, and exits 1.
+- On expired AWS credentials, points you to `aws sso login` / `aws configure` and exits 1 instead of throwing.
+- ECS only: on `--target lambda` projects the command exits with an error (functions have no shell to attach to) and points you to `logs` instead.
+- Emits an `exec_run` telemetry event recording success and outcome.
+
+## Usage
+
+```bash
+npx grada-run exec
+npx grada-run exec --command /bin/bash
+npx grada-run exec --service myapp-service --container myapp-container
+```
+
+Type `exit` to leave the shell.
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `[service]` | Service to connect to. Defaults to the project service. |
+| `--service <name>` | Explicit service name override. |
+| `--cluster <name>` | Explicit cluster name override. |
+| `--container <name>` | Explicit container name override. |
+| `--command <cmd>` | Shell to open (default `/bin/sh`). |
+| `--region <region>` | Explicit AWS region override. |
+
+## Prerequisites
+
+- Run `npx grada-run apply` first: ECS Exec access (`enable_execute_command` plus the container's session permissions) is provisioned with your infrastructure. If the connection is refused on an older deployment, re-run `apply` to enable it.
+- Install the AWS CLI and the Session Manager plugin (`brew install session-manager-plugin` on Mac; the command prints the right instructions for your OS when it's missing). On expired credentials, refresh with `aws sso login` or `aws configure`. See the [AWS credentials guide](/grada/guides/aws-credentials/).
+
+## See also
+
+- [status](/grada/cli/status/)
+- [logs](/grada/cli/logs/)
+- [diagnose](/grada/cli/diagnose/)

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

@@ -0,0 +1,37 @@
+---
+title: gc
+description: Discover and delete orphaned ECR images, CloudWatch log groups, and Elastic IPs.
+---
+
+Dry-run discovery and interactive deletion of orphaned AWS resources left behind by failed deployments, deleted PR previews, or manual console changes — protecting your AWS bill without leaving the terminal.
+
+## What it does
+
+- Scans ECR repositories matching `<project-name>-*` for untagged images and batch-deletes them.
+- Scans CloudWatch log groups under `/ecs/<project-name>-*` (preview leftovers; the live `/ecs/<project-name>` group is never matched) and deletes them. On `--target lambda` projects it scans `/aws/lambda/<project-name>-*` instead, always excluding the live `/aws/lambda/<project-name>-fn` group.
+- Scans Elastic IPs and releases any without an association (stops the hourly unused-EIP charge).
+- Paginates all discovery APIs, so large accounts are fully scanned.
+- Prints a categorized dry-run summary with per-target counts before asking anything.
+
+## Usage
+
+```bash
+npx grada-run gc
+npx grada-run gc --region eu-west-1
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--region <region>` | Explicit AWS region override. |
+| `--project-name <name>` | Explicit project name override (defaults to `app_name` in `terraform/main.tf`, then the current directory name). |
+
+## Safety
+
+Deletion requires explicit interactive confirmation (`Are you sure you want to permanently delete these orphaned resources? (y/N)`, defaulting to no). There is intentionally no `--yes` flag, so the command can never wipe resources from a CI pipeline by accident. Declining or cancelling deletes nothing; finding nothing skips the prompt entirely.
+
+## See also
+
+- [status](/grada/cli/status/)
+- [Ephemeral PR Previews](/grada/guides/ephemeral-pr-previews/)

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

@@ -0,0 +1,72 @@
+---
+title: Initializing Project (npx grada-run)
+description: Scaffold production-ready AWS infrastructure and CI/CD pipelines.
+---
+
+Generate Terraform, Docker, and GitHub Actions files for your project.
+
+## What it does
+
+- Turns your codebase into a deployable AWS project: auto-detects your framework, `Procfile`, `vercel.json`, and Compose files, warns about framework-specific migration issues (NestJS bind address, Next.js standalone output, SvelteKit/Astro adapters), then provisions the remote-state S3 bucket and synthesizes Terraform, Docker, and CI/CD files.
+- Scans your manifests for infrastructure signals before prompting: database drivers and migration markers pre-select the managed PostgreSQL prompt, worker dependencies pre-fill the background-worker command, and detected capabilities (Redis, SQS, S3, DynamoDB, Bedrock, SES) come pre-checked in the addon picker — every suggestion shows the exact evidence that triggered it (`detected: ioredis, REDIS_URL`). Detection is read-only and skips secret values entirely.
+- Scaffolds selected addons in the same run (same pipeline as [`add`](/grada/cli/add/), including container env injection and README cost refresh), offers to wire the pre-deploy database migration gate into the generated workflow, offers scheduled IaC drift detection (a daily `terraform plan` workflow that opens GitHub Issues), and prints a full stack topology preview when addons are included.
+- Backs up any existing generated files before overwriting them, and writes AI assistant rule files for the assistants you choose (advanced mode) or the ones already present in your repo (quickstart mode). Your own `README.md` is never overwritten: deployment docs go to `README.md` only when it is absent or was previously generated, otherwise to `DEPLOYMENT.md` (or `GRADA.md` when both are yours), with an existing `secret_keys.json` left untouched.
+- Finishes with the exact next steps: the `apply` command to provision, and the `git` commands to commit and push.
+- Writes a fixed-baseline monthly cost estimate into the generated deployment doc, refreshed automatically whenever you later run [`add`](/grada/cli/add/).
+- Emits `project_provisioned` (recording the database engine, detected/selected addons, migration-gate status, and drift-detection status) and `cli-error` telemetry events (disable with `--no-telemetry`).
+
+## Usage
+
+```bash
+npx grada-run
+npx grada-run --headless --framework=nextjs --region=us-east-2
+npx grada-run --headless --framework=nestjs --needsDatabase \
+  --with db:redis,ai:bedrock,email:ses --domain example.com --setup-ci-migrate
+npx grada-run --headless --framework=node --target=lambda
+```
+
+Running with no subcommand starts the interactive setup wizard (`init` is the default command).
+
+## Compute targets
+
+`--target` selects the AWS compute architecture (interactive runs prompt when the flag is absent):
+
+- `ecs` (default, `fargate` accepted as a synonym) — always-on ECS Fargate tasks behind an ALB: zero cold starts, ~$31.28/mo compute+ALB baseline.
+- `lambda` — scale-to-zero AWS Lambda container function (via the Lambda Web Adapter, zero app code changes) behind API Gateway HTTP API v2 and CloudFront: $0.00/mo fixed compute baseline, usage-based invocations.
+
+Lambda targets skip ECS-only scaffolding (no worker service, no ALB listener rules, no pre-deploy migration gate — run migrations from CI against your database endpoint instead). Day-0 `apply` seeds a placeholder image into ECR automatically, so the first provision succeeds before any code push. Secrets pushed with `secrets push` stay in the shared vault for runtime reads (`APP_SECRETS_ARN`); database credentials flow as `DB_*` environment variables so VPC-attached functions need no Secrets Manager endpoint.
+
+Not sure which to pick? Choose `ecs` for steady or latency-sensitive traffic, long responses, WebSockets, background workers, or persistent database connections — and `lambda` for sporadic or bursty traffic where $0 idle cost beats warm latency. The full side-by-side (cost crossover, request limits, connection safety, network egress) lives in [Fargate vs Lambda tradeoffs](/grada/guides/architecture/#fargate-vs-lambda-tradeoffs).
+
+## Headless flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--headless` | Bypass all interactive prompts (for CI/CD and automation). |
+| `--framework=<name>` | `node`, `nestjs`, `nextjs`, `nuxt`, `svelte`, `python`, `django`, `rails`, `go`, `static`. |
+| `--region=<region>` | AWS region (e.g. `us-east-1`). |
+| `--port=<port>` | Container port your app listens on. |
+| `--size=<size>` | Fargate task size preset. |
+| `--healthCheckPath=<path>` | ALB health-check path. |
+| `--desiredCount=<n>` | Number of tasks to run. |
+| `--branch=<name>` | Branch the CI workflow deploys. |
+| `--needsDatabase` | Provision a managed database. |
+| `--db-engine <engine>` | Database engine: `postgres` (default), `mysql` (MySQL 8.0), or `aurora-postgresql` (Serverless v2 scale-to-zero). Skip the interactive engine prompt. |
+| `--target <target>` | Compute target: `ecs` (default, `fargate` synonym) or `lambda` (scale-to-zero serverless). Skips the interactive target prompt. |
+| `--enablePrPreviews` | Enable ephemeral PR preview environments. |
+| `--dir=<path>` | Target directory for generated files. |
+| `--preconfigured` | Skip framework-specific warnings (for preconfigured setups). |
+| `--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`). Pre-checks the interactive picker, or scaffolds directly in headless mode. |
+| `--model <id>` | Bedrock model override when `ai:bedrock` is included (defaults to the catalog's recommended model). |
+| `--domain <domain>` | Domain for the SES identity when `email:ses` is included (required in headless mode). |
+| `--zone-id <id>` | Route 53 hosted zone ID for automatic SES DNS records. |
+| `--from-email <email>` | Default SES sender address (default `noreply@<domain>`). |
+| `--setup-ci-migrate` | Wire the pre-deploy database migration gate into the generated workflow when a database and migration command are detected. |
+| `--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. |
+| `--no-telemetry` | Disable telemetry for this run (or set `DO_NOT_TRACK=1` for all runs). |
+
+New here? Start with the [Quickstart](/grada/guides/quickstart/).
+
+See the [Supported Frameworks](/grada/guides/frameworks/) guide for detection rules and per-framework requirements, and the [Headless Mode guide](/grada/guides/headless/) for automation examples.
+
+After scaffolding, continue with [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/).