grada-run 0.0.2 → 0.32.0

package/apps/docs/.astro/dev.json

@@ -0,0 +1,14 @@
+{
+	"pid": 23981,
+	"port": 4321,
+	"url": "http://127.0.0.1:4321",
+	"urls": {
+		"local": [
+			"http://127.0.0.1:4321/"
+		],
+		"network": [],
+		"networkInterfaceNames": []
+	},
+	"background": false,
+	"startedAt": "2026-09-24T10:12:19.581Z"
+}

package/apps/docs/.astro/settings.json

@@ -0,0 +1,5 @@
+{
+	"_variables": {
+		"lastUpdateCheck": 1789924675360
+	}
+}

package/apps/docs/.astro/types.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="astro/client" />
+/// <reference path="content.d.ts" />

package/apps/docs/astro.config.mjs

@@ -0,0 +1,97 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://starlight.astro.build/reference/configuration/
+export default defineConfig({
+  site: 'https://grada-run.github.io',
+  base: '/grada',
+  redirects: {
+    '/adrs/001-initial-architecture/': '/grada/adrs/0001-s3-native-state-locking/',
+  },
+  integrations: [
+    starlight({
+      title: 'Grada',
+      description: 'Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.',
+      customCss: ['./src/custom.css'],
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/grada-run/grada' },
+      ],
+      editLink: {
+        baseUrl: 'https://github.com/grada-run/grada/edit/main/apps/docs/',
+      },
+      lastUpdated: true,
+      sidebar: [
+        {
+          label: 'Deployment Guides',
+          collapsed: true,
+          items: [
+            { label: 'Quickstart (5 minutes)', slug: 'guides/quickstart' },
+            { label: 'Stack Architecture', slug: 'guides/architecture' },
+            { label: 'CI/CD Pipeline & First Deploy', slug: 'guides/cicd-pipeline' },
+            { label: 'Supported Frameworks', slug: 'guides/frameworks' },
+            { label: 'Reference Implementations & Examples', slug: 'guides/examples' },
+            { label: 'Dockerfiles & Containers', slug: 'guides/dockerfiles' },
+            { label: 'Docker Compose', slug: 'guides/docker-compose' },
+            { label: 'Background Workers', slug: 'guides/background-workers' },
+            { label: 'Managed Database Connections', slug: 'guides/database-connections' },
+            { label: 'Secrets Management', slug: 'guides/secrets-management' },
+            { label: 'Ephemeral PR Previews', slug: 'guides/ephemeral-pr-previews' },
+            { label: 'Understanding Your AWS Bill', slug: 'guides/understanding-your-bill' },
+            { label: 'Troubleshooting AWS Credentials', slug: 'guides/aws-credentials' },
+            { label: 'Re-running Init Safely', slug: 'guides/rerun-init' },
+            { label: 'Headless Mode & Automation', slug: 'guides/headless' },
+          ],
+        },
+        {
+          label: 'CLI Reference',
+          collapsed: true,
+          items: [
+            { label: 'npx grada-run (init)', slug: 'cli/init' },
+            { label: 'apply', slug: 'cli/apply' },
+            { label: 'destroy', slug: 'cli/destroy' },
+            { label: 'secrets', slug: 'cli/secrets' },
+            { label: 'diagnose', slug: 'cli/diagnose' },
+            { label: 'logs', slug: 'cli/logs' },
+            { label: 'status', slug: 'cli/status' },
+            { label: 'rollback', slug: 'cli/rollback' },
+            { label: 'exec', slug: 'cli/exec' },
+            { label: 'db', slug: 'cli/db' },
+            { label: 'gc', slug: 'cli/gc' },
+            { label: 'doctor', slug: 'cli/doctor' },
+            { label: 'eject', slug: 'cli/eject' },
+            { label: 'sync-ai', slug: 'cli/sync-ai' },
+            { label: 'add', slug: 'cli/add' },
+            { label: 'domain', slug: 'cli/domain' },
+            { label: 'sleep & wake', slug: 'cli/sleep' },
+            { label: 'drift', slug: 'cli/drift' },
+          ],
+        },
+        {
+          label: 'Platform Migrations',
+          collapsed: true,
+          items: [
+            { label: 'Vercel (Next.js)', slug: 'migrations/nextjs-vercel-to-aws' },
+            { label: 'Heroku (Procfile)', slug: 'migrations/heroku-procfile-to-aws' },
+            { label: 'Vercel (Astro)', slug: 'migrations/astro-vercel-to-aws' },
+            { label: 'Vercel (SvelteKit)', slug: 'migrations/sveltekit-vercel-to-aws' },
+          ],
+        },
+        {
+          label: 'Project Details',
+          collapsed: true,
+          items: [
+            { label: 'Roadmap', slug: 'roadmap' },
+            { label: 'Testing Strategy', slug: 'testing-strategy' },
+          ],
+        },
+        {
+          label: 'Architecture (ADRs)',
+          collapsed: true,
+          items: [
+            { autogenerate: { directory: 'adrs' } }
+          ],
+        },
+      ],
+    }),
+  ],
+});

package/apps/docs/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "docs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.42.2",
+    "astro": "^7.3.3",
+    "js-yaml": "^4.3.2",
+    "sharp": "^0.34.2"
+  }
+}

package/apps/docs/src/content/docs/adrs/0001-s3-native-state-locking.md

@@ -0,0 +1,37 @@
+---
+title: "S3 Native State Locking"
+description: "Use S3-native locking for Terraform remote state without DynamoDB."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-15 (Retroactive)
+
+## Context and Problem Statement
+
+When deploying infrastructure via Terraform across local developer workstations and automated CI/CD pipelines, remote state management is required to prevent race conditions, state drift, and concurrent apply corruption. 
+
+Traditionally, managing Terraform remote state on AWS required provisioning both an S3 bucket (for storage) and a dedicated DynamoDB table (for state locking). This added operational overhead, increased the baseline AWS resource footprint, and required developers to manage extra IAM permissions solely for locking metadata.
+
+## Decision Drivers
+
+* **Simplicity:** Minimize the number of AWS resources a user has to provision and manage day-to-day.
+* **Cost Efficiency:** Eliminate unnecessary idle infrastructure costs (e.g., DynamoDB provisioned capacity).
+* **Reliability:** Guarantee that concurrent CI/CD pipeline runs and local CLI executions cannot corrupt Terraform state files.
+
+## Considered Options
+
+1. **S3 + DynamoDB Table:** The traditional HashiCorp recommendation for remote state locking.
+2. **S3 Native State Locking:** Utilizing S3's native conditional write support for state locking directly within the S3 bucket backend.
+3. **Third-Party State Backends:** (e.g., Terraform Cloud) — rejected to preserve zero-vendor-lock-in and keep execution local to the user's AWS account.
+
+## Decision Outcome
+
+**Chosen Option:** Use an encrypted Amazon S3 bucket as the remote state backend leveraging Terraform's native S3 state locking capabilities.
+
+### Positive Consequences
+* **Zero Maintenance:** Users do not have to monitor, manage, or pay for an extra DynamoDB table.
+* **Tighter Security:** Simplifies the IAM policy scope required for the `grada` state bucket helper, adhering strictly to least privilege.
+* **Frictionless Onboarding:** Streamlines the bootstrapping experience during the initial `npx grada-run` run.
+
+### Negative Consequences
+* Relies on modern Terraform backend behavior that supports S3 native locks. Edge cases involving highly outdated, legacy Terraform CLI versions are not supported.

package/apps/docs/src/content/docs/adrs/0002-eject-mechanism-pure-iac.md

@@ -0,0 +1,39 @@
+---
+title: "Eject Mechanism for Pure IaC"
+description: "Keep generated Terraform and leave the CLI with the eject mechanism."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-20 (Retroactive)
+
+## Context and Problem Statement
+
+`grada` abstracts away the complexity of writing raw Terraform for ECS Fargate, ALBs, CloudFront, OIDC, and Secrets Manager. However, a primary reason senior platform teams hesitate to adopt deployment generators is the fear of **tool lock-in**. Teams need a guarantee that if their architecture outgrows the CLI, or if they wish to take 100% manual control of the codebase, they can do so without starting from scratch.
+
+## Decision Drivers
+
+* **Zero Vendor Lock-In:** Uphold the foundational promise that developers permanently own their infrastructure code.
+* **Auditability & Freedom:** Provide teams with an unambiguous "escape hatch" to sever ties with `grada` management metadata while maintaining a perfectly functioning infrastructure pipeline.
+
+## Considered Options
+
+1. **No Eject Command:** Require users to manually delete `ManagedBy` tags and untangle state/workflows by hand.
+2. **Submodule / Framework Wrapper:** Keep the Terraform code hidden inside a remote module (rejected, as it violates the core premise of transparent, readable IaC).
+3. **Explicit `eject` Command:** Build a dedicated `npx grada-run eject` utility that strips all CLI metadata and tracking tags, leaving behind clean, standard Terraform and GitHub Actions files.
+
+## Decision Outcome
+
+**Chosen Option:** Implement an explicit `npx grada-run eject` command as a core feature.
+
+### Technical Implementation Details
+When invoked, `eject`:
+* Removes or sanitizes internal `ManagedBy = "grada"` default tags across all generated files.
+* Preserves all generated `.tf`, `Dockerfile`, and `.github/workflows/` files safely in place.
+* Detaches the project from the CLI entirely, leaving valid Terraform code that can be managed directly via the `terraform` or `opentofu` binaries.
+
+### Positive Consequences
+* Builds trust with engineers and security teams who refuse black-box wrappers.
+* Eliminates friction during adoption; users know they can safely leave at any time.
+
+### Negative Consequences
+* Ejected repositories permanently lose access to automated security patches, template updates, or CLI-driven drift synchronization.

package/apps/docs/src/content/docs/adrs/0003-sync-ai-context-strategy.md

@@ -0,0 +1,48 @@
+---
+title: "AI Context Synchronization Strategy"
+description: "Sync IaC context into AI coding assistants with sync-ai."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-02 (Retroactive)
+
+## Context and Problem Statement
+
+Modern engineering teams heavily utilize AI coding assistants (Cursor, GitHub Copilot, Windsurf, Claude Code, etc.) in their local IDEs. However, when dealing with Infrastructure-as-Code (IaC), AI models frequently hallucinate invalid Terraform syntax, recommend destructive manual AWS CLI commands, or ignore critical project-specific constraints like unprivileged container ports and OIDC auth flows.
+
+Furthermore, automatically writing instruction files into user repositories carries a high risk of clobbering a team's existing, carefully crafted agent prompts.
+
+## Decision Drivers
+
+* **Hallucination Mitigation:** Provide structured, deterministic instructions to IDE AI assistants to ensure they generate valid Terraform and safe workflows.
+* **Non-Destructive Integration:** Guarantee that existing `.cursorrules`, `CLAUDE.md`, or shared workspace instruction files are never accidentally overwritten or destroyed.
+* **Multi-Tool Support:** Support the highly fragmented landscape of AI coding tools without forcing users into a specific IDE.
+
+## Considered Options
+
+1. **Single Global Instruction File:** Only support `.cursorrules` (rejected as too narrow for modern multi-tool teams).
+2. **Blind Overwrite of Agent Files:** Replace existing AI rule files with `grada` defaults (rejected due to the unacceptable risk of destroying user configuration).
+3. **Isolated Rule Files + Delimited Block Injection (`sync-ai`):** Create dedicated files where supported (e.g., `grada.mdc`), and safely inject delimited, managed markdown blocks into existing shared instruction files where necessary.
+
+## Decision Outcome
+
+**Chosen Option:** Build a dedicated `npx grada-run sync-ai` command and a non-destructive auto-injection engine.
+
+### Supported Targets
+The engine intelligently maps instructions to the following environments:
+* **Cursor:** `.cursor/rules/grada.mdc`
+* **Roo Code / Roo-Cline:** `.roo/rules/grada.md`
+* **Trae:** `.trae/rules/project_rules.md` (managed block injection)
+* **Continue:** `.prompts/grada.prompt`
+* **Windsurf:** `.windsurfrules` (managed block injection)
+* **GitHub Copilot:** `.github/copilot-instructions.md` (managed block injection)
+* **Claude Code:** `CLAUDE.md` (managed block injection)
+* **Goose:** `.goosehints`
+* **Aider:** `.aider.conf.yml` / `.aider.model.settings.yml`
+
+### Positive Consequences
+* Dramatically reduces AI-induced infrastructure errors and dangerous AWS CLI recommendations.
+* Safe, idempotent execution allows teams to run `npx grada-run sync-ai` whenever their architecture parameters (like AWS region or ports) change, without fear of losing their own prompts.
+
+### Negative Consequences
+* Requires ongoing maintenance of parser logic and block delimiters as AI coding assistant vendors rapidly change their configuration file specifications.

package/apps/docs/src/content/docs/adrs/0004-iac-driven-diagnostic-context.md

@@ -0,0 +1,37 @@
+---
+title: "IaC-Driven Diagnostic Context (Stateless CLI)"
+description: "Let diagnose fetch CloudWatch and ECS context without local state."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-19
+
+## Context and Problem Statement
+
+To provide a seamless developer experience, the `grada diagnose` command needs to automatically fetch CloudWatch logs and ECS task failures without requiring the user to manually input their AWS Region, Cluster Name, or Log Group. 
+
+We needed a mechanism to persist or infer the deployment context locally so the CLI knows where to look for errors.
+
+## Decision Drivers
+
+* **Statelessness:** The CLI should avoid managing internal database files or proprietary local state files that can fall out of sync with actual infrastructure.
+* **Single Source of Truth:** Terraform is already the declarative source of truth for the project's infrastructure.
+* **Ecosystem Compatibility:** Developers often delete node_modules or switch laptops; context retrieval must survive typical Git workflows.
+
+## Considered Options
+
+1. **Local State File:** Create a `.grada/context.json` file upon generation. (Rejected: creates state drift and pollutes version control).
+2. **AWS Tag Querying:** Use the AWS SDK to query all clusters for a specific tag. (Rejected: too slow, requires broad IAM `ListClusters` permissions, and fails if multiple environments exist).
+3. **IaC Parsing (Stateless):** Parse the generated `terraform/main.tf` to extract the AWS Region and infer the cluster name from the local directory structure.
+
+## Decision Outcome
+
+**Chosen Option:** IaC Parsing (Stateless). The `diagnose` command reads the AWS Region directly via regex from `terraform/main.tf` and constructs standard AWS resource names based on the current working directory.
+
+### Positive Consequences
+* The CLI remains entirely stateless. If the Terraform files exist, the diagnostics work.
+* Enforces the architectural philosophy that the generated IaC is the ultimate source of truth.
+* Zero additional files are added to the user's repository.
+
+### Negative Consequences
+* If a user manually alters the `region` string inside `main.tf` using non-standard formatting, the regex parser may fail to detect it, falling back to a default region.

package/apps/docs/src/content/docs/adrs/0005-ecs-fargate-alb-runtime-target.md

@@ -0,0 +1,38 @@
+---
+title: "ECS Fargate and ALB as the Single Runtime Target"
+description: "Run every supported framework on ECS Fargate behind an application load balancer."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+`grada` promises that any supported framework deploys with one command. Every framework-specific Dockerfile, health-check rule, Terraform module (`templates/terraform/`), and diagnostic runbook only works if there is exactly one production runtime to target.
+
+We needed to pick a single AWS compute and ingress combination that covers long-running web servers, workers, and static sites without per-framework infrastructure branches.
+
+## Decision Drivers
+
+* **Uniformity:** One set of Terraform modules, one container contract, one diagnostic story for all frameworks.
+* **No-ops fit:** Users choosing this tool do not run an infra team; the runtime must be serverless and scale to zero operational burden.
+* **Health-checkability:** The load balancer must probe container health so failed deploys surface as ALB signals, not silent black holes.
+
+## Considered Options
+
+1. **AWS Lambda / App Runner per framework.** (Rejected: request/response and timeout limits exclude long-running servers and workers; would force framework-specific branches.)
+2. **EC2 / self-managed clusters.** (Rejected: reintroduces the server management the tool exists to remove.)
+3. **ECS Fargate + Application Load Balancer.** Containers stay portable across frameworks; ALB gives path-based health checks, listener rules (translated from `vercel.json`), and zero-downtime rolling deploys.
+
+## Decision Outcome
+
+**Chosen Option:** ECS Fargate + ALB for all dynamic workloads. Every generated project provisions the same cluster/service/ALB shape; only the image contents and container port vary per framework.
+
+### Positive Consequences
+* Framework support reduces to Dockerfile + port + bind-address requirements (`src/utils/detector.js`, `src/utils/warnings.js`).
+* `diagnose` can assume ALB health-check semantics for every project.
+* Static sites reuse the same pipeline with an Nginx image instead of a framework server.
+
+### Negative Consequences
+* Cold-start-sensitive or GPU workloads are out of scope; the tool cannot serve them without a second runtime target.
+* Users pay Fargate minimums even for idle preview environments.

package/apps/docs/src/content/docs/adrs/0006-github-oidc-no-stored-keys.md

@@ -0,0 +1,37 @@
+---
+title: "GitHub OIDC Authentication, No Stored AWS Keys"
+description: "Authenticate CI/CD with short-lived OIDC tokens instead of long-lived AWS keys."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+The generated workflow (`templates/github/deploy.yml`) must authenticate to AWS on every run to sync Terraform and deploy containers. The conventional approach — storing `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as GitHub secrets — creates rotation burden and a leak surface: any secret exfiltrated from CI grants durable AWS access.
+
+We needed an authentication mechanism with no long-lived credential to store, rotate, or leak.
+
+## Decision Drivers
+
+* **Zero-secret CI:** Nothing credential-shaped should live in the repository or GitHub secret store.
+* **Least privilege:** Each run should receive credentials scoped to that run only.
+* **First-deploy fit:** Setup must work on a fresh AWS account without pre-provisioned IAM users.
+
+## Considered Options
+
+1. **Long-lived IAM user keys in GitHub Secrets.** (Rejected: rotation burden, durable blast radius on leak, contradicts the zero-secret philosophy.)
+2. **GitHub OIDC federation.** The workflow declares `id-token: write`, and Terraform (`templates/terraform/oidc.tf`) registers GitHub as an OIDC identity provider with a per-project role. Each run mints a short-lived token; there is nothing to rotate.
+3. **User-supplied role assumption.** (Rejected as default: pushes IAM setup onto the first-deploy path; kept possible via `create_oidc_provider = false` for accounts that already federate GitHub.)
+
+## Decision Outcome
+
+**Chosen Option:** GitHub OIDC federation by default. Generation creates the provider (unless one exists) and a `<project>-github-actions-role`; the workflow assumes it every run.
+
+### Positive Consequences
+* No AWS keys exist anywhere in CI: nothing to rotate, nothing durable to leak.
+* The weekly drift-convergence cron reuses the same mechanism with no extra setup.
+
+### Negative Consequences
+* First `apply` must create the OIDC provider, adding one IAM dependency to the happy path.
+* Accounts with restrictive IAM policies may need an admin to approve provider creation.

package/apps/docs/src/content/docs/adrs/0007-framework-detection-with-fallback.md

@@ -0,0 +1,37 @@
+---
+title: "Framework Auto-Detection with Graceful Fallback"
+description: "Detect the framework from repo signals and fall back to static instead of failing."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+Setup must preselect the right framework preset without interrogating the user about files they may not understand — but repository signals are unreliable: `package.json` may be malformed, `vercel.json` may be empty, and unknown stacks must still produce a working project.
+
+We needed detection rules that are helpful when signals exist and harmless when they do not.
+
+## Decision Drivers
+
+* **Never block generation:** A strange repo must still scaffold; a wrong guess the user can override beats a fatal error.
+* **Deterministic precedence:** Overlapping signals (e.g. `express` inside a NestJS app) must resolve the same way every run.
+* **Advance warning:** Framework-specific runtime requirements (bind address, build output, adapter) should surface before infrastructure exists, not after the first 502.
+
+## Considered Options
+
+1. **Interactive-only selection.** (Rejected: slow, and headless/CI generation needs a non-interactive path.)
+2. **Strict detection, fail on ambiguity.** (Rejected: malformed or partial configs would block scaffolding entirely.)
+3. **Precedence-ordered detection with silent ignore + static fallback.** Checks run top-down (`src/utils/detector.js`); malformed configs are treated as absent, never fatal; anything unmatched falls back to `static`. Post-detection checks (`src/utils/warnings.js`) flag fixable issues with copy-paste remedies.
+
+## Decision Outcome
+
+**Chosen Option:** Precedence-ordered detection with graceful fallback. Both `dependencies` and `devDependencies` are searched; empty or malformed signal files are ignored; headless mode without `--framework` resolves the same way.
+
+### Positive Consequences
+* `npx grada-run` succeeds on repos the tool has never seen, producing a deployable static project the user can refine.
+* Warnings arrive with exact fixes at setup time, when they are cheapest to apply.
+
+### Negative Consequences
+* A wrong-but-plausible guess (e.g. Express detected inside a larger framework) silently generates the wrong preset until the user notices.
+* Detection rules must be maintained alongside the ecosystem or they rot into misdetection.

package/apps/docs/src/content/docs/adrs/0008-secrets-names-in-git-values-in-aws.md

@@ -0,0 +1,37 @@
+---
+title: "Secrets Contract: Names in Git, Values in AWS"
+description: "Commit secret key names to Terraform while values live only in Secrets Manager."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+Deployed containers need environment secrets, but committing `.env` contents would leak credentials into git history, and baking values into CI configuration would spread them across logs and workflow files. At the same time, Terraform must know *which* variables exist to wire them into the ECS task definition.
+
+We needed a split that keeps values out of version control while keeping the variable set declarative and reviewable.
+
+## Decision Drivers
+
+* **Zero plaintext in git:** No secret value may ever be committed, including in history-friendly JSON files.
+* **Declarative wiring:** The task definition must be built from a committed, diffable source so secret rotation is a normal code review.
+* **Day-2 ergonomics:** Adding a variable vs. changing a value must have obviously different, safe procedures.
+
+## Considered Options
+
+1. **Commit `.env` and inject at build time.** (Rejected: values enter git history permanently and leak into image layers and CI logs.)
+2. **Names-only contract.** `secrets push` uploads values to the `<project>-secrets` vault and writes only key *names* to `terraform/secret_keys.json`, which is committed. Terraform maps each name into the task definition; ECS resolves values from Secrets Manager at runtime.
+3. **Fully external management.** (Rejected: forces users onto out-of-band secret workflows on day one instead of the guided push/pull/audit loop.)
+
+## Decision Outcome
+
+**Chosen Option:** Names-only contract. Key-set changes require committing `secret_keys.json` and redeploying (the task definition is rebuilt); value-only changes take a rolling ECS restart with no redeploy.
+
+### Positive Consequences
+* `secret_keys.json` diffs in pull requests show exactly which variables were added or removed, with zero leak risk.
+* `secrets pull` / `secrets audit` close the onboarding and rotation loops without ever printing values into CI.
+
+### Negative Consequences
+* Forgetting to commit `secret_keys.json` after adding a variable produces a deploy that silently lacks it — a failure mode users must learn once.
+* Secret values remain invisible to code review by design, so a wrong value can only be caught at runtime.

package/apps/docs/src/content/docs/adrs/0009-regenerate-with-backup-on-rerun.md

@@ -0,0 +1,37 @@
+---
+title: "Regenerate from Scratch with Backup on Re-Run"
+description: "Re-running init backs up generated files and regenerates instead of merging."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+Users re-run `npx grada-run` to change region, size, or framework — but by then the target directory contains previously generated `terraform/`, `Dockerfile`, and workflow files, possibly hand-edited. Merging new output into edited files risks silent half-applied configurations that are worse than either version.
+
+We needed re-runs to be safe, predictable, and recoverable.
+
+## Decision Drivers
+
+* **Predictability:** Post-run state must equal what generation produces for the new inputs — no merge ghosts.
+* **Recoverability:** Hand edits and previous outputs must never be destroyed without a way back.
+* **Explicitness:** The user must always know exactly what moved and what to do next.
+
+## Considered Options
+
+1. **Three-way merge with user files.** (Rejected: generated IaC has no stable merge grammar; conflicts would be resolved by guessing.)
+2. **Refuse to overwrite.** (Rejected: makes legitimate reconfiguration (region, size, framework) a manual file-deletion chore.)
+3. **Backup and regenerate.** On conflict (`src/utils/backup.js`), offer Backup & Regenerate: move existing outputs to `.bak` files (additionally git-ignored so clutter never reaches GitHub), regenerate from scratch, and print the exact next steps.
+
+## Decision Outcome
+
+**Chosen Option:** Backup and regenerate. Setup never merges; it backs up, regenerates, and reports.
+
+### Positive Consequences
+* Re-runs are idempotent in effect: same inputs always yield the same tree.
+* No user file is ever destroyed; recovery is a file copy away.
+
+### Negative Consequences
+* Hand edits to generated files are silently forked into `.bak` copies the user must reconcile manually.
+* Repeated re-runs accumulate `.bak` clutter locally (mitigated by git-ignoring the pattern).

package/apps/docs/src/content/docs/adrs/0010-advisory-only-security-scans.md

@@ -0,0 +1,37 @@
+---
+title: "Advisory-Only Security Scans in the Pipeline"
+description: "Trivy scans report vulnerabilities without blocking builds or deploys."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-09-24 (Retroactive)
+
+## Context and Problem Statement
+
+The generated pipeline scans both Terraform (`CRITICAL,HIGH`) and the built container image on every deploy. Failing the build on findings would enforce security posture — but base-image and transitive-dependency findings routinely arrive faster than fixes, which would turn the deployment pipeline into a lottery where routine pushes fail for reasons outside the user's code.
+
+We needed scans to inform without holding deploys hostage.
+
+## Decision Drivers
+
+* **Deploy velocity:** A routine push must not fail because an upstream base image published a CVE overnight.
+* **Visibility:** Findings must still land where the team looks, on every run, not rot in a dashboard nobody opens.
+* **Reversibility:** The day the signal is clean enough to gate on, flipping the default must be a one-line change.
+
+## Considered Options
+
+1. **Blocking scans (`exit-code: 1`).** (Rejected: couples deploy success to upstream vulnerability disclosure timing; guarantees false-positive outages.)
+2. **No scans.** (Rejected: surrenders the IaC and image visibility the pipeline is well placed to provide.)
+3. **Advisory scans (`exit-code: 0`).** Trivy runs on every deploy for both IaC and image; results land in the GitHub step summary; the build proceeds regardless.
+
+## Decision Outcome
+
+**Chosen Option:** Advisory-only scans. Every finding is reported in the step summary; none blocks the rollout.
+
+### Positive Consequences
+* Deploys never fail for third-party CVEs; security signal accumulates without operational pain.
+* Teams adopt the pipeline without fearing day-one red builds from pre-existing findings.
+
+### Negative Consequences
+* Genuinely critical misconfigurations ship unless a human reads the summary — the signal only works if someone looks.
+* Without a ratchet (e.g. fail only on *new* findings), vulnerability debt can grow silently.

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

@@ -0,0 +1,84 @@
+---
+title: add
+description: Provision modular cloud addons like private S3 storage, DynamoDB tables, Valkey caching, SQS queues, Bedrock AI access, SES email, or scheduled cron jobs.
+---
+
+Provision modular Day-2 cloud primitives without writing Terraform, configuring IAM policies, or opening the AWS Management Console.
+
+## What it does
+
+- `storage:s3` creates a private S3 bucket (encrypted, CloudFront OAC, CORS ready for presigned browser uploads) and injects `S3_BUCKET_NAME` and `S3_CDN_URL` into your container.
+- `db:dynamodb` creates a `PAY_PER_REQUEST` DynamoDB table (no fixed hourly instance cost) with Point-in-Time Recovery, a free VPC Gateway Endpoint, and injects `DYNAMODB_TABLE_NAME` into your container.
+- `db:redis` provisions a cost-optimized ElastiCache for Valkey 8.0 node (Redis-protocol compatible) isolated in your VPC, reachable only from your ECS tasks or Lambda function, and injects `REDIS_URL` into your container.
+- `queue:sqs` creates an SQS queue with long polling and a Dead-Letter Queue, and injects `SQS_QUEUE_URL` and `SQS_DLQ_URL` into your container. If your project has a background worker service, it also wires scale-to-zero auto-scaling driven by queue depth. On `--target lambda` projects the queue ships without a consumer (no worker service exists) — poll from function code or wire an event source mapping yourself.
+- `ai:bedrock` grants your container least-privilege permission to invoke Amazon Bedrock foundation models (no static AWS keys) and injects `BEDROCK_MODEL_ID` into your container. Run it interactively to pick a provider and model from the catalog, or pass `--model <id>` directly.
+- `email:ses` provisions Amazon SES for transactional email: a domain identity, DKIM signing, a `mail.` subdomain for bounce handling with SPF, a DMARC baseline, least-privilege `ses:SendEmail` permissions locked to your sender domain, and `SES_FROM_EMAIL` / `SES_REGION` in your container. With `--zone-id` it creates the verification, DKIM, MX, SPF, and DMARC records in Route 53 automatically; otherwise it outputs the records to add at your DNS provider. If you already ran `domain add`, the domain (and zone) is picked up automatically. The identity, DKIM, MAIL FROM, and DNS records are scoped to the production workspace as account-wide singletons, so PR previews never duplicate or delete them — preview containers inherit sending permission through their own task role.
+- `cron` creates an EventBridge Scheduler schedule that runs a one-off Fargate task from your app's task definition on a `cron(...)` or `rate(...)` expression, with least-privilege `ecs:RunTask` + `iam:PassRole` permissions. One schedule per project: `--name` customizes it, and re-running with `--force` replaces it in place. On `--target lambda` projects the schedule invokes the function directly with a JSON payload carrying the command — handle scheduled events in application code.
+- Every addon attaches least-privilege IAM policies to your task role, so your application code can use the AWS SDK with no extra configuration.
+- Addon files live in `terraform/` (`s3.tf`, `dynamodb.tf`, `redis.tf`, `sqs.tf`, `bedrock.tf`, `ses.tf`, `cron.tf`), so `destroy` tears them down and `eject` keeps them automatically. PR-preview workspaces get isolated per-workspace resources. If your project has a `worker.tf` background service, addon environment variables are injected there too.
+- Emits an `add_run` telemetry event recording the capability and outcome.
+
+> **Bedrock model access:** AWS requires you to enable model access in the Bedrock console before your first `InvokeModel` call — including in the regions behind your `us.*` cross-region inference profile. IAM permissions alone are not enough. Anthropic models additionally require a one-time First Time Use (FTU) form in the Bedrock console.
+
+> **SES sandbox:** new AWS accounts start in the SES sandbox and can only send to verified addresses. Request production access in the SES console (a short use-case form, usually approved within a day) before sending to real users.
+
+## Usage
+
+```bash
+npx grada-run add storage:s3
+npx grada-run add db:dynamodb
+npx grada-run add db:dynamodb --partition-key userId
+npx grada-run add db:redis
+npx grada-run add queue:sqs
+npx grada-run add ai:bedrock
+npx grada-run add ai:bedrock --model us.anthropic.claude-haiku-4-5-20251001-v1:0
+npx grada-run add ai:bedrock --list-models
+npx grada-run add ai:bedrock --refresh
+npx grada-run add email:ses --domain example.com
+npx grada-run add email:ses --domain example.com --zone-id Z1234567890ABC
+npx grada-run add cron --schedule "cron(0 2 * * ? *)" --cmd "npm run cron"
+npx grada-run add storage:s3 --force
+```
+
+After adding, run `grada apply` (or commit and push to trigger CI) to provision the resource.
+
+To switch Bedrock models later, just run `grada add ai:bedrock` again (interactively) or with a new `--model <id>` — the model reference updates in place across `bedrock.tf`, `main.tf`, and `worker.tf` without needing `--force`.
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--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). |
+| `--partition-key <key>` | DynamoDB partition key name (default `id`). Letters, numbers, underscore, hyphen, and dot only. Only applies to `db:dynamodb`. |
+| `--model <id>` | Bedrock model or inference profile ID (default `us.anthropic.claude-sonnet-4-6`). Only applies to `ai:bedrock`. |
+| `--list-models` | Print the Bedrock model catalog (works offline, no project required). Only applies to `ai:bedrock`. |
+| `--refresh` | Refresh the Bedrock model catalog from live AWS data before listing or provisioning. Only applies to `ai:bedrock`. |
+| `--domain <domain>` | Domain for the SES identity (defaults to your `domain add` domain, or prompts interactively). Only applies to `email:ses`. |
+| `--from-email <email>` | Default sender address (default `noreply@<domain>`). Must belong to the SES domain. Only applies to `email:ses`. |
+| `--zone-id <id>` | Route 53 hosted zone ID for automatic DKIM/SPF/DMARC records. Only applies to `email:ses`. |
+| `--schedule <expr>` | EventBridge Scheduler expression, e.g. `cron(0 2 * * ? *)` or `rate(1 hour)` (default `cron(0 0 * * ? *)`). Only applies to `cron`. |
+| `--cmd <command>` | Command to run inside the scheduled container (default `npm run cron`; also accepts `--cron-command`). Only applies to `cron`. |
+| `--name <job>` | Job slug customizing the schedule name (default `daily-job`). Only applies to `cron`. |
+| `--timezone <tz>` | IANA timezone for the schedule expression (default `UTC`). Only applies to `cron`. |
+| `--force` | Overwrite the existing addon file (also accepts `--force=false`). Without it, re-adding refuses to clobber your edits. |
+
+Requires a project initialized with `grada` (`terraform/main.tf` must exist).
+
+## Cost & Billing Drivers
+
+- `storage:s3`: $0/mo fixed baseline; billed per GB stored ($0.023/GB-mo), S3 PUT/GET requests, and CloudFront egress.
+- `db:dynamodb`: $0/mo fixed instance baseline (the VPC Gateway Endpoint is free); billed per read/write request, table storage ($0.25/GB-mo), and PITR continuous backups ($0.20/GB-mo once data is written).
+- `db:redis`: ~$9.49/mo fixed baseline ($0.013/hr Valkey 8.0 `cache.t4g.micro`); $0 intra-AZ VPC transfer. Each open PR preview runs its own node while the PR is open.
+- `queue:sqs`: $0/mo fixed baseline; first 1M requests/mo free, then $0.40 per million requests.
+- `ai:bedrock`: $0/mo fixed baseline; billed per 1K input/output tokens on `InvokeModel` calls.
+- `email:ses`: $0/mo fixed baseline; $0.10 per 1,000 emails sent.
+- `cron`: $0/mo fixed baseline (first 14M EventBridge Scheduler invocations/mo free); billed only for Fargate seconds while the cron task runs (per-invocation Lambda billing on `--target lambda`).
+
+`grada add` prints the cost impact, refreshes the estimate in your `README.md` (or `DEPLOYMENT.md`), and `grada apply` lists active addons in its pre-flight preview. Reference rates are us-east-2; actual charges vary by region and usage.
+
+## See also
+
+- [apply](/grada/cli/apply/)
+- [destroy](/grada/cli/destroy/)
+- [domain](/grada/cli/domain/) (serve your app from the same domain SES sends from)