grada-run 0.0.1 → 0.32.0

package/specs/add-storage-dynamodb.md

@@ -0,0 +1,106 @@
+# Spec: Modular Service Engine (`deploy-stack add`) — `storage:s3` & `db:dynamodb`
+
+## Overview
+Introduce the `deploy-stack add <capability>` command to provision modular Day-2 cloud primitives without requiring users to write Terraform, configure IAM policies, or open the AWS Management Console. This implementation establishes the table-driven `ADDON_REGISTRY` architecture, consolidates project/region resolution in `src/utils/resolvers.js`, and delivers two scale-to-zero primitives:
+1. **`deploy-stack add storage:s3`**: Private S3 bucket with CloudFront Origin Access Control (OAC), CORS rules for browser uploads, and least-privilege IAM permissions on `aws_iam_role.task_role`.
+2. **`deploy-stack add db:dynamodb`**: Scale-to-zero (`PAY_PER_REQUEST`) DynamoDB table with Point-in-Time Recovery (PITR), a free VPC Gateway Endpoint wired to `aws_route_table.public`, and least-privilege IAM task permissions.
+
+Because addon files (`terraform/s3.tf`, `terraform/dynamodb.tf`) live directly inside `terraform/` and use `local.app_name`, `deploy-stack destroy` automatically tears them down as part of the Terraform state, `deploy-stack eject` naturally leaves them in place as standard HCL files, and PR-preview workspaces deliberately receive isolated per-workspace buckets/tables.
+
+---
+
+## Part 1: Resolver Deduplication & CLI Dispatch (`src/utils/resolvers.js`, `src/commands/add.js`, `bin/cli.js`)
+
+### 1. Extend `src/utils/resolvers.js` (Single Source of Truth)
+Instead of duplicating flag/file/basename resolution inside `add.js`, extend `src/utils/resolvers.js`:
+* **`resolveProjectName(options = {}, cwd = process.cwd())`:**
+  1. If `options.projectName` is provided (mapped from `--project-name`), return it.
+  2. Otherwise, if `terraform/main.tf` exists in `cwd`, extract the project name from the rendered file by matching either:
+     * `app_name\s*=\s*"([^"$]+)\$\{local\.env_suffix\}"` (from `locals`), or
+     * `resource\s+"aws_ecr_repository"\s+"app"\s*\{[^}]*?name\s*=\s*"([^"]+)-repo"`
+  3. Fall back to `path.basename(cwd)`.
+* Reuse `resolveRegion(options, cwd)` and `resolveProjectName(options, cwd)` in `src/commands/add.js`.
+
+### 2. Command Signature & `ADDON_REGISTRY`
+```bash
+deploy-stack add <capability> [--region <region>] [--project-name <name>] [--partition-key <key>] [--force]
+```
+* Keep the `add` branch in `bin/cli.js` thin (and add a `deploy-stack add <capability>` line to `HELP_TEXT`), delegating capability lookup to a table-driven `ADDON_REGISTRY` inside `src/commands/add.js`.
+* **Supported `<capability>` keys:** `'storage:s3'` and `'db:dynamodb'`.
+* **Flag Scoping & Validation:**
+  * `parseAddArgs(args)` must support both `--flag value` and `--flag=value` forms, mapping `--project-name` to `projectName`, `--partition-key` to `partitionKey` (default `'id'`), `--region` to `region`, and `--force` (supporting both bare `--force` -> `true` and `--force=true` / `--force=false` for parity with other CLI parsers).
+  * `--partition-key` applies only to `db:dynamodb` (ignore if not passed; if passed, validate that it matches `/^[a-zA-Z0-9_.-]+$/` so it cannot break HCL interpolation, throwing a validation error with `error_code: 'INVALID_PARTITION_KEY'` otherwise).
+* **Unknown / Missing Capability:**
+  * If `<capability>` is omitted or not in `ADDON_REGISTRY`, print a clear error listing supported capabilities (`storage:s3`, `db:dynamodb`), emit `trackEvent('add_run', { capability: capability || 'none', success: false, error_code: 'UNSUPPORTED_CAPABILITY' })`, `await flushTelemetry()`, and exit/throw.
+
+### 3. Preconditions & Idempotency
+* **Terraform Project Guard:** Verify that `terraform/main.tf` exists in `cwd`. If missing, print `No terraform/main.tf found. Run "deploy-stack init" first before adding services.`, emit `trackEvent('add_run', { capability, success: false, error_code: 'TERRAFORM_NOT_INITIALIZED' })`, `await flushTelemetry()`, and exit/throw.
+* **Idempotency & `--force` Guard:**
+  * `storage:s3` writes `terraform/s3.tf`.
+  * `db:dynamodb` writes `terraform/dynamodb.tf`.
+  * If the target `.tf` file already exists and `--force` is **not** set, print a warning (`terraform/<file>.tf already exists. Pass --force to overwrite.`), emit `trackEvent('add_run', { projectName, capability, success: false, error_code: 'ADDON_ALREADY_EXISTS' })`, `await flushTelemetry()`, and return without modifying files.
+
+---
+
+## Part 2: IAM Role Binding & Container Environment Injection (`src/commands/add.js`)
+
+### 1. Attach Policies to Existing `aws_iam_role.task_role`
+* `templates/terraform/main.tf` already defines `aws_iam_role.task_role` (line 76) and wires `task_role_arn = aws_iam_role.task_role.arn` (line 116).
+* Do **not** modify `templates/terraform/main.tf` or create a duplicate role. Reference `role = aws_iam_role.task_role.id` directly in the `aws_iam_role_policy` blocks inside `s3.tf` and `dynamodb.tf`.
+
+### 2. Deterministic `injectContainerEnvVars(mainTfContent, envEntries)`
+The user's generated `terraform/main.tf` contains an already-rendered `environment = [...]` block inside `aws_ecs_task_definition.app` (`container_definitions = jsonencode([...])`), potentially alongside compose env vars, database env vars, and secondary containers.
+* **Anchor Strategy:**
+  1. Locate `resource "aws_ecs_task_definition" "app"` in `terraform/main.tf`.
+  2. Find the **first** `environment = [` array inside that resource (which belongs to the primary app container, prior to any secondary containers).
+  3. Walk the balanced square brackets `[...]` of that `environment` array.
+  4. For each `{ name, value }` in `envEntries`:
+     * Check if `{ name = "<NAME>"` (or `"name": "<NAME>"`) already exists inside that `environment` block. If it already exists, skip inserting a duplicate (ensuring idempotent reruns with `--force`).
+     * Otherwise, insert `{ name = "${entry.name}", value = "${entry.value}" }` cleanly before the closing `]` of that `environment` array.
+* **Injected Variables:**
+  * For `storage:s3`:
+    * `S3_BUCKET_NAME` -> `${aws_s3_bucket.storage.id}`     * `S3_CDN_URL` -> `https://${aws_cloudfront_distribution.storage_cdn.domain_name}`
+  * For `db:dynamodb`:
+    * `DYNAMODB_TABLE_NAME` -> `${aws_dynamodb_table.main.name}`  ---  ## Part 3: Capability 1 — `storage:s3` (`templates/terraform/addons/s3.tf` -> `terraform/s3.tf`)  Render `terraform/s3.tf` with the following specifications:  1. **Workspace-Aware Naming & S3 63-Character / Lowercase Rules:**    * Include `data "aws_caller_identity" "current" {}` in `s3.tf`.    * Because `-storage-<12-digit-account-id>` takes 21 characters, truncate and sanitize the prefix (`local.app_name`) to at most 42 characters, lowercase it, and strip any trailing hyphen **before** appending `-storage-${data.aws_caller_identity.current.account_id}` so the full account ID is never truncated and S3 naming rules are always satisfied:
+     `bucket = "${trimsuffix(substr(lower(local.app_name), 0, 42), "-")}-storage-${data.aws_caller_identity.current.account_id}"`
+2. **Private S3 Bucket (`aws_s3_bucket.storage`):**
+   * `aws_s3_bucket_public_access_block.storage`: `block_public_acls = true`, `block_public_policy = true`, `ignore_public_acls = true`, `restrict_public_buckets = true`.
+   * `aws_s3_bucket_server_side_encryption_configuration.storage`: `sse_algorithm = "AES256"`.
+   * `aws_s3_bucket_cors_configuration.storage`: Allow `["GET", "PUT", "POST", "DELETE", "HEAD"]`, `allowed_origins = ["*"]` (include an HCL comment noting this is intentionally open for zero-config presigned uploads and can be restricted to the app domain), `allowed_headers = ["*"]`, `expose_headers = ["ETag"]`, `max_age_seconds = 3000`.
+3. **CloudFront Distribution (`aws_cloudfront_distribution.storage_cdn`):**
+   * Coexists cleanly alongside `aws_cloudfront_distribution.cdn` (the ALB distribution in `main.tf`).
+   * `aws_cloudfront_origin_access_control.storage_oac`: `origin_access_control_origin_type = "s3"`, `signing_behavior = "always"`, `signing_protocol = "sigv4"`.
+   * `aws_cloudfront_distribution.storage_cdn`: Point origin to `aws_s3_bucket.storage.bucket_regional_domain_name` with `origin_access_control_id = aws_cloudfront_origin_access_control.storage_oac.id`, `viewer_protocol_policy = "redirect-to-https"`, `allowed_methods = ["GET", "HEAD", "OPTIONS"]`, `cached_methods = ["GET", "HEAD"]`, `cloudfront_default_certificate = true`, and standard `forwarded_values` (`query_string = false`, `cookies { forward = "none" }`).
+   * `aws_s3_bucket_policy.storage_oac_policy`: Grant principal `cloudfront.amazonaws.com` action `s3:GetObject` on `${aws_s3_bucket.storage.arn}/*` conditioned on `StringEquals = { "AWS:SourceArn" = aws_cloudfront_distribution.storage_cdn.arn }`. 4. **Least-Privilege IAM Policy (`aws_iam_role_policy.storage_s3_access`):**    * Attach to `role = aws_iam_role.task_role.id` granting `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket` on `aws_s3_bucket.storage.arn` and `${aws_s3_bucket.storage.arn}/*`.
+5. **Outputs:**
+   * `output "s3_bucket_name" { value = aws_s3_bucket.storage.id }`
+   * `output "s3_cdn_domain" { value = aws_cloudfront_distribution.storage_cdn.domain_name }`
+
+---
+
+## Part 4: Capability 2 — `db:dynamodb` (`templates/terraform/addons/dynamodb.tf` -> `terraform/dynamodb.tf`)
+
+Render `terraform/dynamodb.tf` with the following specifications:
+
+1. **Workspace-Aware Scale-to-Zero Table (`aws_dynamodb_table.main`):**
+   * `name = "${local.app_name}-table"` (deliberately isolates PR-preview workspaces with their own table via `local.app_name`).    * `billing_mode = "PAY_PER_REQUEST"`    * `hash_key = "{{PARTITION_KEY}}"` (defaults to `"id"`, fixed type `"S"`, no sort key/GSI in v1)    * `attribute { name = "{{PARTITION_KEY}}", type = "S" }`    * `point_in_time_recovery { enabled = true }`    * `server_side_encryption { enabled = true }` 2. **Free VPC Gateway Endpoint (`aws_vpc_endpoint.dynamodb`):**    * `vpc_id = aws_vpc.main.id`    * `service_name = "com.amazonaws.{{REGION}}.dynamodb"`    * `vpc_endpoint_type = "Gateway"`    * `route_table_ids = [aws_route_table.public.id]` (referencing `aws_route_table.public` defined in `terraform/network.tf`). 3. **Least-Privilege IAM Policy (`aws_iam_role_policy.dynamodb_access`):**    * Attach to `role = aws_iam_role.task_role.id` granting `dynamodb:GetItem`, `dynamodb:PutItem`, `dynamodb:UpdateItem`, `dynamodb:DeleteItem`, `dynamodb:Query`, `dynamodb:Scan`, `dynamodb:BatchGetItem`, `dynamodb:BatchWriteItem`, `dynamodb:DescribeTable` on `aws_dynamodb_table.main.arn` and `${aws_dynamodb_table.main.arn}/index/*`.
+4. **Outputs:**
+   * `output "dynamodb_table_name" { value = aws_dynamodb_table.main.name }`
+   * `output "dynamodb_table_arn" { value = aws_dynamodb_table.main.arn }`
+
+---
+
+## Part 5: UX, Docs & Testing
+
+1. **Terminal UX & Telemetry:**
+   * Display `intro(' deploy-stack add 🧩 ')`, log created/updated files and injected env vars (`S3_BUCKET_NAME`, `S3_CDN_URL`, or `DYNAMODB_TABLE_NAME`), and display `outro(...)` instructing the user to run `deploy-stack apply`.
+   * Emit `trackEvent('add_run', { projectName, capability, success: true })` and `await flushTelemetry()`.
+2. **Documentation (`apps/docs/src/content/docs/cli/add.md`):**
+   * Document `deploy-stack add storage:s3` and `deploy-stack add db:dynamodb`, including flags (`--partition-key`, `--force`, `--region`, `--project-name`) and the injected container environment variables.
+3. **Unit Tests (`tests/add.test.js` & `tests/resolvers.test.js`):**
+   * Test `resolveProjectName` extraction from rendered `terraform/main.tf` (`local.app_name` and `aws_ecr_repository.app`) and `--project-name` override.
+   * Test `parseAddArgs` (including `--flag value`, `--flag=value`, and `--force=false` forms) and invalid `--partition-key` rejection (`INVALID_PARTITION_KEY`).
+   * Test missing `terraform/main.tf` (`TERRAFORM_NOT_INITIALIZED`), unknown capability (`UNSUPPORTED_CAPABILITY`), and existing addon file with/without `--force` (`ADDON_ALREADY_EXISTS`).
+   * Test `injectContainerEnvVars` against a real generated `terraform/main.tf` (including multi-container / existing env vars), verifying idempotency when run twice with `--force`.
+   * Verify generated `terraform/s3.tf` references `aws_iam_role.task_role.id`, uses `"${trimsuffix(substr(lower(local.app_name), 0, 42), "-")}-storage-${data.aws_caller_identity.current.account_id}"`, and configures OAC + AES256 + CORS.
+   * Verify generated `terraform/dynamodb.tf` references `aws_iam_role.task_role.id`, `route_table_ids = [aws_route_table.public.id]`, `PAY_PER_REQUEST`, PITR, and custom `--partition-key`.

package/specs/bedrock-model-catalog.md

@@ -0,0 +1,131 @@
+# Spec: Multi-Provider Bedrock Model Catalog, Interactive Selector & Day-2 Switching
+
+## Overview
+Upgrade `deploy-stack add ai:bedrock` from a single hardcoded model constant into a multi-provider model catalog and Day-2 model switcher:
+1. **Bundled Multi-Provider Catalog (`src/data/bedrock-models.json`):** A structured catalog covering major Bedrock providers (Anthropic, OpenAI, DeepSeek, Meta, Amazon, Google, Mistral AI, xAI, Moonshot AI, Cohere) loaded via `fs.readFileSync` for Node 18 compatibility with a deterministic fallback catalog.
+2. **Maintainer Sync Script & Optional Live Refresh (`scripts/sync-bedrock-models.js`, `--refresh`):** A maintainer script (`npm run sync:bedrock-models` with `pruneMissing: true`), an OIDC-gated weekly GitHub Actions workflow that opens/updates a PR, and an optional `--refresh` CLI flag (`pruneMissing: false`) that merges live AWS Bedrock models into `~/.deploy-stack/bedrock-models-cache.json`.
+3. **Two-Step Interactive Model Selector & `--list-models` (`src/commands/add.js`):** When run interactively on a TTY without an explicit model, guide the user through a two-step Clack selector (`Provider` -> `Model`, plus `Custom model ID...`). Support `--list-models` to print the catalog offline even outside a Terraform project.
+4. **Scoped Day-2 Model Switching (`src/commands/add.js`):** Allow `injectContainerEnvVars` to upsert specific opt-in keys (`upsertKeys: ['BEDROCK_MODEL_ID']`) via a 4th `options` parameter while preserving skip-existing behavior and the 3rd `taskDefinitionName` parameter for all other addons, and allow switching Bedrock models without `--force`.
+
+---
+
+## Part 1: Catalog Schema, Loader & Live Refresh (`src/data/bedrock-models.json`, `src/utils/bedrock-catalog.js`)
+
+### 1. Bundled Catalog & Exact Minimal Fallback
+* Define `export const FALLBACK_BEDROCK_MODEL = 'us.anthropic.claude-sonnet-4-6'` in `src/utils/bedrock-catalog.js`.
+* Load `src/data/bedrock-models.json` using `fs.readFileSync` and `JSON.parse` (avoiding JSON import attributes so Node 18 support is preserved).
+* **Exact In-Memory Minimal Fallback Catalog (`FALLBACK_CATALOG`):** If reading or parsing `src/data/bedrock-models.json` fails or fails `isValidCatalog`, return:
+  * `updatedAt: '2026-01-01'`
+  * `defaultModelId: FALLBACK_BEDROCK_MODEL`
+  * `providers: [{ provider: 'Anthropic', models: [{ id: FALLBACK_BEDROCK_MODEL, name: 'Claude Sonnet 4.6', hint: 'Recommended — balanced coding & reasoning', recommended: true }] }]`
+* Re-export `DEFAULT_BEDROCK_MODEL` from `src/commands/add.js` set to `loadBedrockCatalog().defaultModelId || FALLBACK_BEDROCK_MODEL`.
+* **Catalog JSON Schema (`src/data/bedrock-models.json`):**
+  * `updatedAt`: ISO date string (`YYYY-MM-DD`, e.g., `'2026-09-27'`).
+  * `defaultModelId`: `'us.anthropic.claude-sonnet-4-6'`.
+  * `providers`: Ordered array of provider objects (`Anthropic`, `OpenAI`, `DeepSeek`, `Meta`, `Amazon`, `Google`, `Mistral AI`, `xAI`, `Moonshot AI`, `Cohere`), each with:
+    * `provider`: Non-empty provider display name string.
+    * `models`: Non-empty array of model objects, each with `id` (short Bedrock inference profile ID or foundation model ID matching `MODEL_ID_RE`, i.e., `^[a-zA-Z0-9._:-]+$`), `name` (human-readable display name, including current models such as `Claude Sonnet 5`, `Claude Sonnet 4.6`, `Claude Opus 4.7`, `Claude Haiku 4.5`, `GPT-5.5`, `DeepSeek V3.2`, `Llama 4 Maverick`, `Amazon Nova Pro`, `Gemma 4`, `Mistral Large`, `Grok 4.6`, `Kimi K3`), `hint` (concise tier/cost hint string), and optional `recommended: true`.
+
+### 2. Cache Validation, Pagination, Normalization & Merge/Prune Semantics (`src/utils/bedrock-catalog.js`)
+* **Validation Rule (`isValidCatalog(data)`):** A catalog object is valid iff it is a non-null plain object with a non-empty string `updatedAt` matching `/^\d{4}-\d{2}-\d{2}$/`, a non-empty string `defaultModelId`, and a non-empty array `providers` where every item has a non-empty string `provider` and a non-empty array `models` of objects containing non-empty string `id` and `name`.
+* **Unified Provider Normalization (`normalizeProviderName(raw)`):** Route both inference profile prefixes/ARNs and foundation model `providerName` values through a single case-insensitive lookup table so duplicate groups (such as `'Mistral'` vs `'Mistral AI'`) are never created:
+  * `'anthropic'` -> `'Anthropic'`
+  * `'openai'` -> `'OpenAI'`
+  * `'deepseek'` -> `'DeepSeek'`
+  * `'meta'` -> `'Meta'`
+  * `'amazon'` -> `'Amazon'`
+  * `'google'` -> `'Google'`
+  * `'mistral'` or `'mistral ai'` -> `'Mistral AI'`
+  * `'xai'` -> `'xAI'`
+  * `'moonshot'` or `'moonshot ai'` -> `'Moonshot AI'`
+  * `'cohere'` -> `'Cohere'`
+  * Any other non-empty string -> trimmed string (or `'Other'` if empty).
+* **`loadBedrockCatalog(options = {})`:**
+  * Resolve the cache path from `options.cachePath || process.env.DEPLOY_STACK_BEDROCK_CACHE_PATH || path.join(os.homedir(), '.deploy-stack', 'bedrock-models-cache.json')`.
+  * When running in a test environment (`VITEST` or `NODE_ENV === 'test'`) **and** neither `options.cachePath` nor `process.env.DEPLOY_STACK_BEDROCK_CACHE_PATH` is explicitly set, skip reading the home directory cache and return the bundled catalog.
+  * Otherwise, if a readable file exists at the resolved cache path, passes `isValidCatalog(cached)`, and satisfies `cached.updatedAt >= bundled.updatedAt`, return `cached`; otherwise return the bundled catalog.
+* **`refreshBedrockCatalog(options = {})`:**
+  * Add `@aws-sdk/client-bedrock` (`BedrockClient`, `ListInferenceProfilesCommand`, `ListFoundationModelsCommand`) to `package.json` dependencies. Accept optional `options.bedrockClient`, `options.region` (defaulting to `process.env.AWS_REGION || 'us-east-2'`), `options.cachePath`, and `options.pruneMissing = false`.
+  * **Pagination:** Loop `ListInferenceProfilesCommand({ typeEquals: 'SYSTEM_DEFINED', nextToken })` until `response.nextToken` is falsy so all pages of system-defined inference profiles are collected. Call `ListFoundationModelsCommand({ byInferenceType: 'ON_DEMAND' })` (and loop `nextToken` if present).
+  * **Merge & Optional Prune Semantics:**
+    * Start from a deep clone of the bundled catalog.
+    * Collect all active live entries (`status === 'ACTIVE'` for inference profiles; `modelLifecycle?.status === 'ACTIVE'` for foundation models) whose `id` matches `^[a-zA-Z0-9._:-]+$`, normalizing each provider via `normalizeProviderName`.
+    * Build a `Set` of existing model `id` strings in the clone. For any live entry whose `id` is not in the clone, append `{ id, name, hint: 'Live AWS Bedrock model' }` to the matching normalized `provider` group (creating the group if absent).
+    * **Pruning (`options.pruneMissing === true`):** When `pruneMissing: true` is passed (used by the maintainer sync script) and the live AWS query returned at least one valid model, filter each provider's `models` array to retain only models present in the live `id` Set **or** equal to `merged.defaultModelId`, and drop any provider group whose `models` array becomes empty. When `pruneMissing` is `false` (default for CLI `--refresh`), never drop bundled models.
+    * Set `merged.updatedAt = new Date().toISOString().slice(0, 10)`, write `merged` to the resolved cache path (creating parent directories with `recursive: true`), and return `merged`.
+  * **Failure Fallback:** If the AWS SDK calls or cache write throw any error, log a non-fatal Clack `log.warn` message and return the bundled catalog without failing the command.
+
+### 3. Maintainer Sync Script & Credentialless-Safe Weekly Workflow
+* Add `scripts/sync-bedrock-models.js` (and `"sync:bedrock-models": "node scripts/sync-bedrock-models.js"` in `package.json`) that runs `refreshBedrockCatalog({ cachePath: path.resolve('src/data/bedrock-models.json'), pruneMissing: true })` using local/CI AWS credentials to update and prune the bundled file in place.
+* Create `.github/workflows/sync-bedrock-models.yml` triggered on `schedule` (`0 6 * * 1`) and `workflow_dispatch`:
+  * Set top-level `permissions: { id-token: write, contents: write, pull-requests: write }`.
+  * When `vars.AWS_ROLE_ARN == ''`, write an informational notice to `$GITHUB_STEP_SUMMARY` and exit 0.
+  * When `vars.AWS_ROLE_ARN != ''`, configure AWS credentials via `aws-actions/configure-aws-credentials@v4` (assuming `vars.AWS_ROLE_ARN` in `vars.AWS_REGION || 'us-east-2'`), run `npm ci` and `npm run sync:bedrock-models`, and publish any changes to `src/data/bedrock-models.json` via `peter-evans/create-pull-request@v7` (branch `chore/sync-bedrock-models`, commit message `chore(bedrock): sync model catalog`, title `chore(bedrock): sync AWS Bedrock model catalog`).
+
+---
+
+## Part 2: CLI Flags, Guard Ordering & Two-Step Interactive Selector (`src/commands/add.js`, `bin/cli.js`)
+
+### 1. Argument Parsing (`parseAddArgs`)
+* Extend `parseAddArgs(args)` in `src/commands/add.js` to parse:
+  * `--list-models` -> `listModels: true` (default `false`)
+  * `--refresh` -> `refresh: true` (default `false`)
+  * `--headless` / `--headless=true` -> `isHeadless: true`; `--headless=false` -> `isHeadless: false` (default `false`, mirroring `--force` parsing)
+* **Explicit Model Tracking:** Keep `model` defaulting to `DEFAULT_BEDROCK_MODEL` in `parseAddArgs` and return `modelProvided: true` whenever `--model <id>` or `--model=<id>` was explicitly passed in `args` (`false` otherwise).
+* In `bin/cli.js`, update `HELP_TEXT` to document `--list-models` and `--refresh`.
+
+### 2. Guard & Execution Ordering in `runAdd(options = {})`
+At the very top of `runAdd(options = {})` (before defaulting `options.model`), capture:
+* `const explicitModel = options.modelProvided === true || (options.model !== undefined && options.modelProvided !== false);`
+
+Execute in this exact sequence:
+1. **`UNSUPPORTED_CAPABILITY` Guard:** Verify `capability` is in `ADDON_REGISTRY`.
+2. **Flag Validation Guards (`INVALID_PARTITION_KEY` / `INVALID_MODEL_ID`):**
+   * Keep the existing `MODEL_ID_RE` (`^[a-zA-Z0-9._:-]+$`; short inference profile IDs and foundation model IDs only; ARNs with `/` are rejected).
+   * When `capability === 'ai:bedrock'`, validate `model` with `MODEL_ID_RE` before `--refresh` / `--list-models`, so passing an invalid `--model` alongside `--list-models` immediately fails with `INVALID_MODEL_ID`.
+   * When `capability !== 'ai:bedrock'`, silently ignore `--model`, `--list-models`, and `--refresh`.
+3. **Optional Live Refresh (`--refresh` on `ai:bedrock`):** If `capability === 'ai:bedrock'` and `options.refresh` is true, call `await refreshBedrockCatalog({ bedrockClient: options.bedrockClient, cachePath: options.cachePath, region: options.region })` inside a Clack spinner (`Refreshing Bedrock model catalog from AWS...`) and hold the returned catalog for step 4 / step 6 (otherwise load via `loadBedrockCatalog({ cachePath: options.cachePath })`).
+4. **Catalog Listing (`--list-models` on `ai:bedrock`):** If `capability === 'ai:bedrock'` and `options.listModels` is true:
+   * **Viewport Exemption & Compact Format:** `--list-models` is explicitly exempt from the 14-line command viewport cap. Format the output compactly with one `log.info` line per provider (`<Provider> (<N>): <model1.id> (<model1.name>), ...`) followed by `outro`.
+   * Emit `trackEvent('add_run', { projectName, capability, action: 'list_models', success: true })`, flush telemetry, and return `{ ok: true, action: 'list-models', models }` before checking for `terraform/main.tf`.
+5. **`TERRAFORM_NOT_INITIALIZED` Guard:** Verify `terraform/main.tf` exists in `cwd`.
+6. **Interactive Two-Step Model Selection (`ai:bedrock` only):**
+   * Import and reuse `isActiveEnvValue` from `src/core/telemetry.js` to evaluate `CI` and `VITEST`.
+   * Compute `const isInteractive = options.interactive ?? (!options.isHeadless && !isActiveEnvValue(process.env.CI) && !isActiveEnvValue(process.env.VITEST) && process.env.NODE_ENV !== 'test' && Boolean(process.stdout?.isTTY));`.
+   * Trigger the interactive selector when `capability === 'ai:bedrock'`, `isInteractive` is `true`, and `explicitModel` is `false`.
+   * **Step 1 (`select`):** Prompt the user to choose a provider from `catalog.providers` (`label: provider.provider`, `hint: provider.models.map(m => m.name).slice(0, 3).join(', ')`) or `Custom model ID...` (`value: '__custom__'`).
+   * **Step 2 (`select` or `text`):**
+     * If a provider was selected, prompt with a `select` of that provider's models (`label: "${m.name} (${m.id})"`, `hint: m.hint`, `value: m.id`) plus `Custom model ID...` (`value: '__custom__'`).
+     * If `'__custom__'` was chosen at Step 1 or Step 2, prompt with Clack `text` for the model ID and validate the trimmed result with `MODEL_ID_RE` (`^[a-zA-Z0-9._:-]+$`). If invalid, trigger the standard `INVALID_MODEL_ID` error path.
+   * **Cancellation (`isCancel`):** If the user cancels at any prompt, call `cancel('Model selection cancelled.')`, emit `trackEvent('add_run', { projectName, capability, success: false, reason: 'cancelled' })`, flush telemetry, and return `{ ok: false, reason: 'cancelled' }` without calling `process.exit(1)`.
+
+---
+
+## Part 3: Scoped Day-2 Model Switching & Opt-In Env Upsert (`src/commands/add.js`)
+
+1. **Preserve 3rd Parameter (`taskDefinitionName`) & Add 4th Parameter (`options = {}`) on `injectContainerEnvVars`:**
+   * Update the signature to `injectContainerEnvVars(tfContent, envEntries = [], taskDefinitionName = 'app', options = {})` (and if `typeof taskDefinitionName === 'object' && taskDefinitionName !== null`, treat it as `options` with `taskDefinitionName = options.taskDefinitionName || 'app'`).
+   * This preserves full backward compatibility for `'app'` and `'worker'` callers (`injectContainerEnvVars(workerContent, envVars, 'worker', { upsertKeys })`).
+   * Add `const upsertKeys = new Set(options.upsertKeys || []);`.
+   * For any env var **not** in `upsertKeys` (the default for all other addons), preserve the exact existing skip-if-already-present behavior so user edits to `S3_BUCKET_NAME`, `DYNAMODB_TABLE_NAME`, `REDIS_URL`, or `SQS_QUEUE_URL` are never clobbered on `--force` and existing `injectContainerEnvVars` unit tests remain completely valid.
+   * For an env var whose `name` **is** in `upsertKeys` (`upsertKeys: ['BEDROCK_MODEL_ID']` for `ai:bedrock`) and already exists in the target container's (`'app'` or `'worker'`) `environment` block, update its `value` string in place to the new `entry.value` (leaving the file text unchanged if the value is already identical).
+2. **Implicit Overwrite on `ai:bedrock` Model Switch:**
+   * When `terraform/bedrock.tf` already exists and `--force` is not set:
+     * If `capability === 'ai:bedrock'` and the user either passed an explicit model (`explicitModel === true`) or completed the interactive selector (`selectedInteractively === true`), proceed with writing `terraform/bedrock.tf` and upserting `BEDROCK_MODEL_ID` in `terraform/main.tf` (and `terraform/worker.tf` if present, passing `'worker'` as the 3rd arg and `{ upsertKeys: ['BEDROCK_MODEL_ID'] }` as the 4th arg) without requiring `--force`.
+     * Otherwise, preserve the existing `ADDON_ALREADY_EXISTS` guard.
+
+---
+
+## Part 4: Docs & Unit Tests (`apps/docs/`, `tests/add.test.js`)
+
+1. **Documentation (`apps/docs/src/content/docs/cli/add.md`):**
+   * Update the default Bedrock model reference to `us.anthropic.claude-sonnet-4-6`.
+   * Document the interactive provider/model selector, `--list-models`, `--refresh`, Day-2 model switching, and the one-time Anthropic First Time Use (FTU) form in the AWS Bedrock console.
+2. **Unit Tests (`tests/add.test.js`):**
+   * Extend the `@clack/prompts` mock in `tests/add.test.js` to include `intro`, `outro`, `select`, `text`, `spinner`, `log`, `cancel`, and `isCancel`.
+   * Update existing `ai:bedrock` tests that assert the old `us.anthropic.claude-sonnet-4-20250514-v1:0` default so they assert `us.anthropic.claude-sonnet-4-6`.
+   * Verify existing `injectContainerEnvVars` "skips keys that already exist" tests continue to pass unchanged, and add a new test verifying `injectContainerEnvVars(content, envVars, 'worker', { upsertKeys: ['BEDROCK_MODEL_ID'] })` replaces an existing `BEDROCK_MODEL_ID` value in place in both `'app'` (`main.tf`) and `'worker'` (`worker.tf`).
+   * Verify `--list-models` succeeds in an empty directory without `terraform/main.tf`, and that passing an invalid `--model` with `--list-models` fails with `INVALID_MODEL_ID`.
+   * Verify `--refresh` with a mocked paginated `bedrockClient` (`nextToken`), provider normalization (`'Mistral'` -> `'Mistral AI'`), and temp `DEPLOY_STACK_BEDROCK_CACHE_PATH` merges live models without dropping bundled entries when `pruneMissing` is `false`, prunes absent entries when `pruneMissing` is `true`, and falls back cleanly to the bundled catalog when the AWS client throws.
+   * Verify the two-step interactive selector (`interactive: true`) with mocked Clack `select` / `text` prompts (provider -> model selection, custom model ID path, invalid custom ID error, and prompt cancellation).
+   * Verify Day-2 switching: running `add ai:bedrock` with Model A and then running `add ai:bedrock --model <Model B>` without `--force` updates `bedrock.tf`, `main.tf`, and `worker.tf` in place.

package/specs/ci-pipeline.md

@@ -0,0 +1,17 @@
+# Spec: Continuous Infrastructure Validation Pipeline
+
+## Objective
+Create a GitHub Actions workflow that automatically generates, compiles, and security-scans our IaC templates across all supported frameworks to prevent regressions.
+
+## Requirements
+1. **Workflow Registration:** Create `.github/workflows/iac-validation.yml` triggered on push to `main` and all pull requests.
+2. **Matrix Strategy:** Run tests across all 10 supported framework permutations: `nestjs`, `nextjs`, `nuxt`, `node`, `svelte`, `static`, `python`, `django`, `rails`, and `go`.
+3. **Execution Steps:** For each framework in the matrix:
+   - Scaffold the app: Run `node bin/cli.js --headless --preconfigured --framework=<matrix-framework>` in a temporary directory.
+   - Terraform Compile: Run `terraform init -backend=false` followed by `terraform validate`.
+   - Terraform Lint: Run `tflint` to catch deprecated syntax.
+   - DevSecOps Scan: Run Trivy (via `aquasecurity/trivy-action`) to scan the generated `Dockerfile` and `terraform/` directory.
+
+## Constraints
+- The pipeline must execute completely offline without AWS credentials (hence `-backend=false`).
+- Trivy must be configured to fail the build if it detects HIGH or CRITICAL vulnerabilities.

package/specs/cost-transparency.md

@@ -0,0 +1,115 @@
+# Spec: End-to-End Cost Transparency (`addons.js`, `visualizer.js`, `init`, `add`, `apply`, & Docs)
+
+## Overview
+Resolve all cost-transparency gaps across `src/utils/addons.js`, `src/utils/visualizer.js`, `src/commands/init.js`, `src/commands/add.js`, `src/commands/apply.js`, `src/utils/generator.js`, and documentation so users always see accurate fixed-baseline vs. usage-based cost breakdowns at `init`, `add`, and `apply` time.
+
+---
+
+## Part 1: Shared `src/utils/addons.js` Registry & Visualizer Upgrade (`src/utils/visualizer.js`)
+
+### 1. Extract `ADDON_REGISTRY` to `src/utils/addons.js` (No Import Cycle)
+Move `ADDON_REGISTRY` into `src/utils/addons.js` (and re-export it from `src/commands/add.js` so existing imports continue to work). Extend each capability entry with `label` and `cost` metadata:
+* **`'storage:s3'`:**
+  * `file`: `'s3.tf'`
+  * `template`: `'s3.tf'`
+  * `label`: `'S3 + CloudFront OAC'`
+  * `cost`:
+    * `model`: `'usage-based'`
+    * `monthlyFixed`: `0`
+    * `summary`: `'$0/mo fixed baseline; billed per GB stored ($0.023/GB-mo), S3 PUT/GET requests, and CloudFront egress'`
+* **`'db:dynamodb'`:**
+  * `file`: `'dynamodb.tf'`
+  * `template`: `'dynamodb.tf'`
+  * `label`: `'DynamoDB (On-Demand + PITR)'`
+  * `cost`:
+    * `model`: `'usage-based'`
+    * `monthlyFixed`: `0`
+    * `summary`: `'$0/mo fixed instance baseline (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)'`
+
+### 2. Concrete Shape & `main.tf` CPU/Memory Parsing in `parseTerraformConfig(terraformDir)`
+In `src/utils/visualizer.js`:
+* Keep existing detection for `main.tf`, `hasDb` (`rds.tf` / `database.tf`), and `hasWorker` (`worker.tf`).
+* **Read rendered `cpu` and `memory` from `main.tf`:** In `main.tf` (within `resource "aws_ecs_task_definition" "app"`), parse `cpu\s*=\s*"(\d+)"` and `memory\s*=\s*"(\d+)"` as integers before checking `terraform.tfvars` (allowing `terraform.tfvars` to override if present, and falling back to `256` / `512` defaults only when neither specifies them). This ensures non-micro sizes chosen at `init` are preserved during `apply` previews and README cost syncs.
+* **Pure file existence for `hasSecrets`:** Set `hasSecrets = fs.existsSync(path.join(terraformDir, 'secrets.tf'))`.
+* **Registry-driven `addons` array:** Iterate over `Object.entries(ADDON_REGISTRY)` and populate `config.addons` as a concrete array of capability keys whose target `.tf` file exists in `terraformDir` (e.g., `addons: ['storage:s3', 'db:dynamodb']`).
+
+### 3. Per-Secret Billing & Return Object Shape in `estimateMonthlyCost(config)`
+* Keep the existing `us-east-2` pricing table constants for Fargate, ALB (`~$22.27/mo` base + LCU), and RDS (`~$13.98/mo` compute + storage) unchanged.
+* **Secrets Manager Fixed Cost (`$0.40/secret/mo`):**
+  * Add `SECRETS_MANAGER_PER_SECRET = 0.40` to the pricing constants.
+  * Count `secretCount = (config.hasSecrets ? 1 : 0) + (config.hasDb ? 1 : 0)` (1 for the base `secrets.tf` JSON secret, plus 1 when `hasDb` is true for RDS `manage_master_user_password = true`).
+  * Compute `secretsCost = secretCount * 0.40`.
+  * If any installed addon in `config.addons || []` defines `cost.monthlyFixed > 0`, add `addon.cost.monthlyFixed` to the total.
+* **Preserve Object Return Shape:** Return `{ fargateMonthly, albMonthly, dbMonthly, secretsMonthly, totalMonthly }` where each value is a two-decimal numeric string (`'XX.XX'`), adding `secretsMonthly: secretsCost.toFixed(2)` alongside the existing fields.
+
+### 4. Honest Labeling & Addon Rendering in `renderDryRunPreview(config, isDryRun = false)`
+In `src/utils/visualizer.js`:
+* Compute `secretCount = (config.hasSecrets ? 1 : 0) + (config.hasDb ? 1 : 0)`:
+  * When `secretCount > 0`, render `[Secrets Manager (${secretCount === 1 ? '1 secret' : `${secretCount} secrets`})]` in the architecture diagram; when `secretCount === 0` (`hasSecrets === false` and `!hasDb`), omit the `[Secrets Manager]` node.
+* For each capability key in `config.addons || []`, look up its `ADDON_REGISTRY[key]` entry and render `[${entry.label}]` in the architecture diagram.
+* Replace the `"Est. Monthly Cost"` label with:
+  `Est. Fixed Baseline: ~$${costs.totalMonthly}/mo (us-east-2 reference rates; usage, requests & data transfer billed per use)`
+* In the dim parenthetical breakdown line (`Fargate: $${costs.fargateMonthly}, ALB: $${costs.albMonthly}...`), append `, Secrets: $${costs.secretsMonthly}` whenever `Number(costs.secretsMonthly) > 0`.
+* When `config.addons` is non-empty, render a `Usage-Based Addons:` section directly below the baseline breakdown using `ADDON_REGISTRY[key].cost.summary`, formatted with a single space after the colon:
+  ```text
+  Usage-Based Addons:
+    • storage:s3 (S3 + CloudFront OAC): $0/mo fixed baseline; billed per GB stored ($0.023/GB-mo), S3 PUT/GET requests, and CloudFront egress
+  ```
+
+---
+
+## Part 2: `init.js` Contract Alignment, Cost Notice & Doc Sync (`src/commands/init.js`, `src/commands/add.js`, `src/utils/generator.js`)
+
+### 1. Align `init.js` and `templates/README.md` on `{{ESTIMATED_COST}}`
+* Export `COST_ESTIMATE_MARKER = 'Estimated Fixed Monthly Baseline:'` and `LEGACY_COST_ESTIMATE_MARKER = 'Estimated Monthly Cost:'` from `src/utils/generator.js` (or `src/utils/visualizer.js`).
+* Update `templates/README.md` (line 19) so the template owns all surrounding wording and `{{ESTIMATED_COST}}` is purely the numeric string (`costs.totalMonthly`):
+  `* **Estimated Fixed Monthly Baseline:** ~${{ESTIMATED_COST}}/month (us-east-2 reference rates; excludes variable traffic, ECR/CloudWatch storage, and usage-based addons)`
+* Update `src/commands/init.js` (around line 110) so it computes `estimateMonthlyCost({ cpu, memory, hasDb, hasWorker, hasSecrets: true, addons: [] })` (or passes the numeric total directly) and sets `ESTIMATED_COST: costs.totalMonthly` (a plain numeric string like `'36.18'` without `~$` or `/ month (...)`).
+
+### 2. Print Cost Impact in `runAdd`
+* Whenever `deploy-stack add <capability>` succeeds, log the cost line from `ADDON_REGISTRY[capability].cost.summary` before `outro`:
+  * `💰 Cost Impact: ${addon.cost.summary}`
+
+### 3. Implement `syncDocCostEstimate(cwd)`
+* Called by `runAdd` after writing the addon `.tf` file:
+  * Check `DEPLOYMENT.md` first and then `README.md` in `cwd`.
+  * If a file containing either `COST_ESTIMATE_MARKER` or `LEGACY_COST_ESTIMATE_MARKER` is found, recompute `parseTerraformConfig` + `estimateMonthlyCost` from `path.join(cwd, 'terraform')`, replace the marker bullet line with:
+    `* **Estimated Fixed Monthly Baseline:** ~$${costs.totalMonthly}/month (us-east-2 reference rates; excludes variable traffic, ECR/CloudWatch storage, and usage-based addons)`
+    and render/replace an `### Active Addons (Usage-Based)` bullet list immediately beneath the cost bullet list using `ADDON_REGISTRY[key].cost.summary` for each key in `config.addons`.
+  * If neither file exists or the user deleted the cost marker, no-op gracefully without throwing.
+
+---
+
+## Part 3: Print-Only Preview When `autoApprove` Is True in `applyStack` (`src/commands/apply.js`)
+
+* In `applyStack` (`src/commands/apply.js`):
+  * In the `if (!autoApprove)` branch, keep `const confirmed = await renderDryRunPreview(detectedConfig, false);` and its cancellation check intact.
+  * Add an `else` branch (when `autoApprove` is `true`) that calls `await renderDryRunPreview(detectedConfig, true);` so the Clack architecture/cost note box is still printed to the terminal without prompting the user for confirmation.
+* Exposing new `--auto-approve` or `--headless` CLI flags on `apply` remains out of scope.
+
+---
+
+## Part 4: Clarify "Scale-to-Zero / Free" Wording in Templates & Docs
+
+1. **Template Comments (`templates/terraform/addons/s3.tf` & `dynamodb.tf`):**
+   * State clearly that the **VPC Gateway Endpoint** has no hourly/data-processing charge, while DynamoDB table storage (`$0.25/GB-mo`), read/write requests, and PITR continuous backups (`$0.20/GB-mo` once data is written) and S3 storage/requests/CloudFront transfer are usage-billed.
+2. **CLI Add Reference (`apps/docs/src/content/docs/cli/add.md`):**
+   * Replace unqualified "scale-to-zero" claims with "no fixed hourly instance cost (usage-billed)" and include a `## Cost & Billing Drivers` section summarizing the billing model for `storage:s3` and `db:dynamodb`.
+3. **PR Preview Guide (`apps/docs/src/content/docs/guides/ephemeral-pr-previews.md`):**
+   * Update the cost section (~line 30) to note that because `add` resources use `${local.app_name}`, each open PR preview workspace provisions its own isolated S3 bucket and/or DynamoDB table—accruing usage-based storage/request/PITR charges until the PR closes and the workspace is destroyed (whereas Secrets Manager secrets are shared via `data` source at no extra per-PR secret cost).
+
+---
+
+## Part 5: Unit Tests (`tests/visualizer.test.js`, `tests/add.test.js`, `tests/apply.test.js`, `tests/generator.test.js`)
+
+1. **`tests/visualizer.test.js`:**
+   * `parseTerraformConfig` extracts rendered `cpu` and `memory` from `main.tf` (and lets `terraform.tfvars` override if present), checks pure `secrets.tf` existence (`hasSecrets: true/false`), and populates `addons: ['storage:s3', 'db:dynamodb']` from `ADDON_REGISTRY`.
+   * `estimateMonthlyCost` returns `{ fargateMonthly, albMonthly, dbMonthly, secretsMonthly, totalMonthly }` with `secretsMonthly: '0.40'` (`hasSecrets: true, hasDb: false`), `'0.80'` (`hasSecrets: true, hasDb: true`), and `'0.00'` (`hasSecrets: false, hasDb: false`).
+   * `renderDryRunPreview` includes `Est. Fixed Baseline`, `, Secrets: $0.40` (or `$0.80`, and omits `[Secrets Manager]` when `0` secrets), and renders active addons' `[label]` and `Usage-Based Addons:` bullets (`• <key> (<label>): <summary>`).
+   * Assert that `templates/README.md` literally contains `COST_ESTIMATE_MARKER` so the template and JS constant cannot drift.
+2. **`tests/add.test.js`:**
+   * `runAdd` prints `💰 Cost Impact:` with the registry summary.
+   * `syncDocCostEstimate` updates the cost baseline (preserving non-default CPU/memory from `main.tf`) and `### Active Addons (Usage-Based)` section in `README.md` or `DEPLOYMENT.md` (matching both `COST_ESTIMATE_MARKER` and `LEGACY_COST_ESTIMATE_MARKER`), and gracefully no-ops when no marker is present.
+3. **`tests/apply.test.js` & `tests/generator.test.js`:**
+   * `applyStack` with `autoApprove: true` calls `await renderDryRunPreview(detectedConfig, true)` (print-only mode) before executing Terraform.
+   * Update `ESTIMATED_COST` fixtures in `tests/generator.test.js` (e.g., `'30.00'` instead of `'~$30'`) and update snapshots to match the new `templates/README.md` cost wording.

package/specs/custom-domains-and-ses.md

@@ -0,0 +1,153 @@
+# Spec: Custom Domains, Edge TLS (`domain`) & Transactional Email (`add email:ses`)
+
+## Overview
+Eliminate the primary production triggers that force developers into the AWS Management Console:
+1. **Shared Foundation & Pre-Refactors (`src/utils/hcl.js`, `src/utils/domains.js`, `src/commands/add.js`):** Extract a shared HCL block-manipulation toolkit, a shared domain/zone validation and `domain.tf` parser module, and per-addon option resolution (`resolveAddonOptions`) with generalized placeholder/conditional-section template rendering.
+2. **Custom Domains & Automated Edge SSL (`deploy-stack domain <add|verify|status|remove>`):** Provision ACM TLS certificates in `us-east-1` (required by CloudFront) via pure HCL builders, support 1-step Route 53 automated validation/routing (`--zone-id`) and 2-step External DNS verification (Cloudflare, Namecheap), and patch `aws_cloudfront_distribution "cdn"` in `terraform/cloudfront.tf`.
+3. **Transactional Email & DKIM Automation (`deploy-stack add email:ses`):** Provision Amazon SES Domain Identities, DKIM tokens, MAIL FROM domain configuration, optional Route 53 DKIM/SPF/DMARC records, container environment variables (`SES_FROM_EMAIL`, `SES_REGION`), and least-privilege `ses:SendEmail` / `ses:SendRawEmail` IAM permissions on `aws_iam_role.task_role`.
+4. **Operational Polish (`doctor_run` & `DATABASE_URL` Synthesis):** Verify `doctor_run` telemetry compatibility (preserving `DOCTOR_CHECKS` ordering and reusing `detectCiProvider()`) and provide a pure `buildMigrationCommand` helper in `src/commands/db/migrate.js` that synthesizes `DATABASE_URL` at runtime when `DB_HOST` is present.
+
+---
+
+## Part 0: Pre-Refactors & Shared Utilities
+
+1. **Shared HCL-Editing Toolkit (`src/utils/hcl.js`):**
+   * Extract pure, string-literal-aware brace-walking primitives:
+     * `findResourceBlock(content, resourceType, resourceName)`
+     * `findNestedBlock(blockContent, blockName)`
+     * `replaceBlock(content, bounds, replacement)`
+     * `upsertAttribute(blockContent, key, valueExpr)`
+     * `removeAttribute(blockContent, key)`
+   * Rewire existing brace-walking callers (`injectContainerEnvVars` and `ensureWorkerDesiredCountLifecycle` in `src/commands/add.js`, and `upsertSnapshotIdentifier` in `src/commands/db/restore.js`) onto `src/utils/hcl.js` while keeping all existing unit tests green, and build the new CloudFront patcher on top of it.
+2. **Shared Domain Validation & `domain.tf` Parser (`src/utils/domains.js`):**
+   * Centralize domain/zone/email normalization and validation so `domain.js` and `add.js` (`email:ses`) never drift:
+     * `normalizeDomain(input)`: trims whitespace, strips a trailing dot (FQDN), and lowercases.
+     * `DOMAIN_REGEX` & `isValidDomain(domain)`: validates standard domains and optional wildcard prefix (`*.example.com`) up to 253 chars.
+     * `ZONE_ID_REGEX` (`/^(?:\/hostedzone\/)?(Z[A-Z0-9]{1,32})$/`) & `normalizeZoneId(input)`: strips optional `/hostedzone/` prefix and validates `Z[A-Z0-9]{1,32}`.
+     * `isValidFromEmail(email, expectedDomain)`: validates email syntax and checks that the address domain matches `expectedDomain` (or is a subdomain of `expectedDomain`), preventing unverified-identity send failures at runtime.
+     * `parseDomainTf(content)`: parses `# deploy-stack:domain-mode=<mode>`, `domain_name`, and `zone_id` (if present) into a structured `{ domain, mode, zoneId }` object used by both `domain status`/`verify`/`remove` and `add email:ses` auto-detection.
+3. **Per-Addon Option Resolution & Template Generalization (`src/commands/add.js`, `src/utils/addons.js`):**
+   * Extract a `resolveAddonOptions(capability, options, ctx)` dispatch with resolvers for stateful addons (`db:dynamodb`, `ai:bedrock`, `email:ses`), each returning `{ ok: true, templateVars, envVars, upsertKeys }` or a structured validation failure (`{ ok: false, errorCode, reason, message }`).
+   * Generalize `renderAddonTemplate(templateContent, templateVars, conditionalBlocks)` to iterate over a placeholder map (`{{REGION}}`, `{{PARTITION_KEY}}`, `{{BEDROCK_MODEL_ID}}`, `{{SES_DOMAIN}}`, `{{SES_FROM_EMAIL}}`) and named conditional blocks (`{{WORKER_AUTOSCALING_BLOCK}}`, `{{SES_ROUTE53_RECORDS_BLOCK}}`).
+   * Allow `ADDON_ENV_VARS` entries in `src/utils/addons.js` to accept either static strings or `(ctx) => string` functions so dynamic values (`BEDROCK_MODEL_ID`, `SES_FROM_EMAIL`, `SES_REGION`) resolve cleanly without post-hoc `replaceAll` special cases.
+
+---
+
+## Part 1: Custom Domains & Edge SSL (`src/commands/domain.js`)
+
+### 1. CLI Surface, Telemetry & Error Conventions
+* Register `domain` in `bin/cli.js` (`HELP_TEXT` and command router) and create `src/commands/domain.js` exporting `parseDomainArgs(args)`, `runDomain(options = {})`, and the pure HCL builders/patchers.
+* **Subcommands:**
+  * `deploy-stack domain add <domain> [--zone-id <id>] [--activate] [--force] [--headless]`
+  * `deploy-stack domain verify [--headless]` (alias: `activate`)
+  * `deploy-stack domain status`
+  * `deploy-stack domain remove [--yes] [--headless]`
+  * Unknown or missing subcommand fails via `failCommand` with event `'domain_run'`, `errorCode: 'UNKNOWN_DOMAIN_SUBCOMMAND'`, `reason: 'unknown-domain-subcommand'`.
+* **Telemetry (`domain_run`):**
+  * Emit `trackSuccess('domain_run', { subcommand, mode })` on success and route all failures through `failCommand` with `'domain_run'` (importing all used `track*` / `fail*` helpers to satisfy `tests/commands-import.test.js`).
+* **Guard Order & Error Codes:**
+  1. Normalize `args` (`normalizeArgv`) and `options` (`normalizeOptions`).
+  2. Validate subcommand and input flags (`INVALID_DOMAIN` / `reason: 'invalid-domain'`, `INVALID_ZONE_ID` / `reason: 'invalid-zone-id'`) **before** filesystem guards (matching `add.js` flag validation order).
+  3. Resolve `cwd` via `resolveCwd` (failing via `failProjectNotInitialized({ event: 'domain_run' })` on unresolvable `cwd`).
+  4. Check that `terraform/cloudfront.tf` exists in `cwd` (failing with `errorCode: 'TERRAFORM_NOT_INITIALIZED'`, `reason: 'terraform-not-initialized'` if missing).
+
+### 2. Pure HCL Builders for `terraform/domain.tf`
+Instead of a single static template file, implement pure builder functions in `src/commands/domain.js`:
+* **`renderDomainTfRoute53({ domain, zoneId })`:**
+  * Header marker: `# deploy-stack:domain-mode=route53` and `# deploy-stack:zone-id=${zoneId}`.
+  * `provider "aws" { alias = "us_east_1", region = "us-east-1" }`
+  * `resource "aws_acm_certificate" "domain"` (`provider = aws.us_east_1`, `domain_name = "${domain}"`, `validation_method = "DNS"`, `lifecycle { create_before_destroy = true }`).
+  * `resource "aws_route53_record" "domain_validation"` using a valid HCL map comprehension for `for_each`:
+    `for_each = { for dvo in aws_acm_certificate.domain.domain_validation_options : dvo.domain_name => { name = dvo.resource_record_name, record = dvo.resource_record_value, type = dvo.resource_record_type } }`
+    with `zone_id = "${zoneId}"`, `allow_overwrite = true`, `ttl = 60`, `name = each.value.name`, `type = each.value.type`, `records = [each.value.record]`.
+  * `resource "aws_acm_certificate_validation" "domain"` (`provider = aws.us_east_1`, `certificate_arn = aws_acm_certificate.domain.arn`, `validation_record_fqdns = [for record in aws_route53_record.domain_validation : record.fqdn]`).
+  * `resource "aws_route53_record" "cdn_alias_a"` and `"cdn_alias_aaaa"` (`zone_id = "${zoneId}"`, `name = "${domain}"`, `type = "A"` / `"AAAA"`, `alias` block targeting `aws_cloudfront_distribution.cdn.domain_name`, `aws_cloudfront_distribution.cdn.hosted_zone_id`, and `evaluate_target_health = false`).
+  * Outputs: `custom_domain_url = "https://${domain}"`, `acm_certificate_arn = aws_acm_certificate.domain.arn`.
+* **`renderDomainTfExternalPending({ domain })`:**
+  * Header marker: `# deploy-stack:domain-mode=external-pending`.
+  * `provider "aws" { alias = "us_east_1", region = "us-east-1" }` and `resource "aws_acm_certificate" "domain"`.
+  * Outputs: `acm_validation_records` (list of `{ name, type, value }` objects from `domain_validation_options`) and `custom_domain_cname_target = aws_cloudfront_distribution.cdn.domain_name`.
+* **`appendValidationResource(domainTfContent)`:**
+  * Idempotently transitions `external-pending` to `external-active` (no-op if already `external-active` or `route53`), appending `resource "aws_acm_certificate_validation" "domain"` (`provider = aws.us_east_1`, `certificate_arn = aws_acm_certificate.domain.arn`) and `output "custom_domain_url"`.
+
+### 3. CloudFront Patching in `terraform/cloudfront.tf` (`patchCloudFrontDomain` / `unpatchCloudFrontDomain`)
+* Scope strictly to `resource "aws_cloudfront_distribution" "cdn"` in `terraform/cloudfront.tf` using `src/utils/hcl.js` (never touching `aws_cloudfront_distribution "storage_cdn"` in `s3.tf`).
+* **`patchCloudFrontDomain(cloudfrontTfContent, domain)`:**
+  * Upsert `aliases = ["${domain}"]` inside `aws_cloudfront_distribution.cdn` (if an `aliases` list already exists, ensure `domain` is present without clobbering other user-added entries; if replacing a previous `domain.tf` domain on `--force`, replace the old managed domain).
+  * Replace the entire `viewer_certificate { ... }` block (removing `cloudfront_default_certificate = true`, which is mutually exclusive with `acm_certificate_arn`) with:
+    `acm_certificate_arn = aws_acm_certificate_validation.domain.certificate_arn`, `ssl_support_method = "sni-only"`, `minimum_protocol_version = "TLSv1.2_2021"`.
+* **`unpatchCloudFrontDomain(cloudfrontTfContent, domain)`:**
+  * Remove `domain` from `aliases` (and remove the `aliases` attribute entirely if no aliases remain).
+  * Replace the `viewer_certificate { ... }` block back to `viewer_certificate { cloudfront_default_certificate = true }`.
+
+### 4. Subcommand Behaviors & Idempotency Rules
+* **`domain add <domain>`:**
+  * If `terraform/domain.tf` already exists:
+    * If `--force` is not passed, fail with `errorCode: 'DOMAIN_ALREADY_CONFIGURED'`, `reason: 'domain-already-configured'` (hinting to pass `--force` to overwrite or `domain verify` to activate).
+    * If `--force` is passed and a previous domain was patched into `cloudfront.tf`, replace the old domain cleanly.
+  * If `--zone-id` is passed (with or without `--activate`): write Route 53 `domain.tf` and immediately patch `terraform/cloudfront.tf` (`mode = 'route53'`).
+  * If `--zone-id` is omitted and `--activate` is passed: write external-active `domain.tf` and patch `terraform/cloudfront.tf` (`mode = 'external-active'`).
+  * If `--zone-id` is omitted and `--activate` is not passed: write external-pending `domain.tf` and leave `terraform/cloudfront.tf` untouched (`mode = 'external-pending'`).
+* **`domain verify` (alias `activate`):**
+  * If `terraform/domain.tf` does not exist, fail with `errorCode: 'DOMAIN_NOT_CONFIGURED'`, `reason: 'domain-not-configured'`.
+  * If mode is already `route53` or `external-active`, ensure `cloudfront.tf` is patched (idempotent no-op) and return `{ ok: true, mode, alreadyActive: true }`.
+  * Otherwise, transition `domain.tf` via `appendValidationResource`, patch `terraform/cloudfront.tf`, remind the user to ensure their external DNS CNAME records are in place before running `npx deploy-stack apply`, and return `{ ok: true, mode: 'external-active' }`.
+* **`domain status`:**
+  * If `terraform/domain.tf` does not exist, print a friendly non-failing message (`No custom domain configured. Run npx deploy-stack domain add <domain> to get started.`), emit `trackSuccess('domain_run', { subcommand: 'status', configured: false })`, and return `{ ok: true, configured: false }`.
+  * Otherwise, parse `domain.tf` via `parseDomainTf` and call `getTerraformOutputs(path.join(cwd, 'terraform'))` from `src/utils/terraform.js` (allowing an optional `options.getOutputs` injection override for unit tests). If `acm_validation_records` / `custom_domain_cname_target` outputs are present, render the copy-paste DNS record table.
+* **`domain remove`:**
+  * If `terraform/domain.tf` does not exist, fail with `errorCode: 'DOMAIN_NOT_CONFIGURED'`, `reason: 'domain-not-configured'`.
+  * Confirmation behavior: if `--yes` is passed, skip the prompt in both TTY and headless modes. If `--yes` is not passed: in headless mode (`resolveHeadless(options)`), fail with `errorCode: 'CONFIRMATION_REQUIRED'`, `reason: 'confirmation-required'`; in interactive mode, prompt with Clack `confirm` (handling `isCancel` cleanly).
+  * Unpatch `terraform/cloudfront.tf` (if present) and delete `terraform/domain.tf`.
+
+---
+
+## Part 2: Transactional Email & DKIM Automation (`deploy-stack add email:ses`)
+
+1. **Registry & Visualizer (`src/utils/addons.js`, `src/utils/visualizer.js`):**
+   * Add `'email:ses'` to `ADDON_REGISTRY` (`file: 'ses.tf'`, `template: 'ses.tf'`, `label: 'Amazon SES (Transactional Email & DKIM)'`, `cost: { monthlyFixed: 0, summary: '$0/mo fixed baseline; $0.10 per 1,000 emails sent' }`).
+   * Add `ADDON_ENV_VARS['email:ses']` with `SES_FROM_EMAIL: (ctx) => ctx.sesFromEmail` and `SES_REGION: (ctx) => ctx.region`, and register `['SES_FROM_EMAIL', 'SES_REGION']` in `upsertKeys`.
+2. **Option Resolution & Validation Order (`resolveAddonOptions` in `src/commands/add.js`):**
+   * Parse `--domain`, `--from-email`, and `--zone-id` in `parseAddArgs(args)`.
+   * **Pre-Guard Flag Validation (before `terraform/main.tf` guard, matching `--model` and `--partition-key`):**
+     * If an explicit `--domain` was passed on `email:ses`, validate via `isValidDomain` (failing with `errorCode: 'INVALID_DOMAIN'`, `reason: 'invalid-domain'`).
+     * If an explicit `--zone-id` was passed on `email:ses`, validate via `normalizeZoneId` (failing with `errorCode: 'INVALID_ZONE_ID'`, `reason: 'invalid-zone-id'`).
+     * If an explicit `--from-email` was passed alongside an explicit `--domain`, validate via `isValidFromEmail(fromEmail, domain)` (failing with `errorCode: 'INVALID_FROM_EMAIL'`, `reason: 'invalid-from-email'`).
+   * **Post-Guard Domain Resolution (after `terraform/main.tf` & overwrite guards):**
+     1. Use explicit `--domain` if provided.
+     2. Else if `terraform/domain.tf` exists in `cwd`, read it via `parseDomainTf` and reuse its `domain` (and its `zoneId` if `--zone-id` was not explicitly passed).
+     3. Else if `isInteractive` is true (reusing `add.js`'s existing `isInteractive` check), prompt via Clack `text` and handle cancellation through `add.js`'s existing `cancelSelection` telemetry helper.
+     4. Else fail with `errorCode: 'MISSING_SES_DOMAIN'`, `reason: 'missing-ses-domain'`.
+     * Validate the resolved `domain` (`INVALID_DOMAIN`) and resolved `fromEmail = options.fromEmail || 'noreply@' + domain` via `isValidFromEmail(fromEmail, domain)` (`INVALID_FROM_EMAIL`).
+3. **Template (`templates/terraform/addons/ses.tf`):**
+   * Do **not** redeclare `data "aws_caller_identity" "current"` (avoiding collision with `s3.tf`).
+   * Use `{{SES_DOMAIN}}`, `{{SES_FROM_EMAIL}}`, `{{REGION}}`, and `{{SES_ROUTE53_RECORDS_BLOCK}}`.
+   * Attach `resource "aws_iam_role_policy" "ses_send"` to `role = aws_iam_role.task_role.id` (matching `main.tf`), granting `["ses:SendEmail", "ses:SendRawEmail"]` on `Resource = "*"` with a `StringLike` condition on `"ses:FromAddress": ["*@{{SES_DOMAIN}}", "{{SES_FROM_EMAIL}}"]`.
+   * In `aws_route53_record.ses_mail_from_mx` (rendered inside `{{SES_ROUTE53_RECORDS_BLOCK}}` when `zoneId` is present), use `10 feedback-smtp.{{REGION}}.amazonses.com`.
+
+---
+
+## Part 3: `doctor_run` Telemetry & `DATABASE_URL` Runtime Synthesis
+
+1. **`doctor_run` Telemetry (`src/commands/doctor.js`):**
+   * Keep `passed_checks`, `failed_checks` (in their existing `DOCTOR_CHECKS` execution order—do **not** sort alphabetically so existing `tests/doctor.test.js` assertions stay untouched), and `total_failed` unchanged.
+   * Reuse `detectCiProvider()` from `src/core/telemetry.js` (no new CI detection logic in `doctor.js`).
+2. **Pure `buildMigrationCommand` Helper (`src/commands/db/migrate.js`):**
+   * Extract `buildMigrationCommand(resolvedCmd, containerDef)` returning `['sh', '-c', ...]`:
+     * Inspect `containerDef?.environment` and `containerDef?.secrets` (treating missing arrays as empty).
+     * If `DATABASE_URL` is already present in either array, or if `DB_HOST` is **not** present in either array (which also preserves all existing `tests/db.test.js` tests that pass env-less mock task definitions), return `['sh', '-c', resolvedCmd]` unchanged.
+     * When `DB_HOST` is present (alongside `DB_USER` and `DB_PASSWORD` in `environment` or `secrets`) and `DATABASE_URL` is absent, return `['sh', '-c', 'export DATABASE_URL="${DATABASE_URL:-postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT:-5432}/${DB_NAME:-postgres}}"; ' + resolvedCmd]`.
+
+---
+
+## Part 4: Documentation, Sidebar & Unit Tests
+
+1. **Documentation & Sidebar (`apps/docs/`):**
+   * Create `apps/docs/src/content/docs/cli/domain.md` and add `{ label: 'domain', slug: 'cli/domain' }` to the CLI Reference sidebar in `apps/docs/astro.config.mjs`.
+   * Update `apps/docs/src/content/docs/cli/add.md` to document `deploy-stack add email:ses`.
+   * Check off **Custom Domains & Automated SSL** and **Transactional Email & DKIM Automation** in both `README.md` and `apps/docs/src/content/docs/roadmap.md`.
+2. **Unit Tests (`tests/domain.test.js`, `tests/add.test.js`, `tests/db.test.js`):**
+   * Use `stripVTControlCharacters` from `'node:util'` on all captured log assertions.
+   * Add unit tests in `tests/domain.test.js` covering `src/utils/hcl.js`, `src/utils/domains.js`, `domain add` (Route 53 1-step vs. External DNS Stage 1 & `--activate`), `domain verify` (Stage 2 transition + idempotency), `domain status` (configured with `getOutputs` override vs. unconfigured), `domain remove` (`--yes`, interactive confirm, headless guard, and `cloudfront.tf` unpatching), and fuzzer-hardened inputs.
+   * Append `email:ses` tests to `tests/add.test.js` covering explicit `--domain`, auto-detection from `terraform/domain.tf` (including `zoneId` reuse), interactive prompt & cancel telemetry, pre-guard validation (`INVALID_DOMAIN`, `INVALID_ZONE_ID`, `INVALID_FROM_EMAIL` domain mismatch), `MISSING_SES_DOMAIN`, `aws_iam_role.task_role.id` binding, and `SES_FROM_EMAIL` / `SES_REGION` injection.
+   * Append `buildMigrationCommand` unit tests to `tests/db.test.js` covering env-less containers (no-wrap), containers with `DATABASE_URL` already defined (no-wrap), and containers with `DB_HOST` + `DB_USER` + `DB_PASSWORD` (synthesizes `DATABASE_URL`).