# Ipa Init

> Initialize IPA project configuration

- Skill: `aws-samples/ipa-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aws-samples/ipa-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/ipa-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/ipa-init

---


# /ipa-init — Initialize IPA Project Configuration

This skill interactively configures a project's `.env` file with the IPA-managed variables required by all other IPA skills (`/ipa-compose`, `/ipa-prepare`, `/ipa-deploy`). It auto-detects the AWS account ID, provides sensible defaults, and validates all input. When the builder selects `APP_IAC=terraform`, the skill also bootstraps the Terraform state backend (S3 + DynamoDB via CloudFormation) so the project is deploy-ready in a single step.

**Lifecycle**: **`/ipa-init`** → `/ipa-compose` → `/ipa-prepare` → `/ipa-deploy`

---

## Variable Schema

The `.env` file contains up to seven IPA-managed variables. `AWS_PROFILE` is optional — if the builder skips it, the line is omitted from `.env`. The agent MUST set all other six variables during initialization.

| Variable | Prompted | Default | Description |
|----------|----------|---------|-------------|
| `AWS_PROFILE` | Yes | _(none)_ | AWS CLI profile name (optional — omit to use default credential chain) |
| `AWS_REGION` | Yes | `us-east-1` | AWS region for deployments |
| `AWS_ACCOUNT_ID` | Auto-detect, confirm | _(none)_ | 12-digit AWS account ID |
| `APP_NAMESPACE` | Yes | `app` | Project name prefix for stack naming (max 12 chars) |
| `APP_ENV` | Yes | `dev` | Environment label (e.g., `dev`, `stage`, `prod`) |
| `APP_CODE_AGENT` | No (auto-set) | `claude-code` | AI agent platform — set automatically, do not prompt |
| `APP_IAC` | Yes | `cloudformation` | Infrastructure-as-code tool (cloudformation or terraform) |
| `TF_STATE_BUCKET` | No (derived) | _(none)_ | S3 bucket for Terraform state — written by Step 4.5 after CFN deploy. Only when `APP_IAC=terraform`. |
| `TF_STATE_LOCK_TABLE` | No (derived) | _(none)_ | DynamoDB table for state locking — written by Step 4.5 after CFN deploy. Only when `APP_IAC=terraform`. |

### Variable Categories

- **Prompted (5)**: `AWS_PROFILE` (optional — can be skipped), `AWS_REGION`, `APP_NAMESPACE`, `APP_ENV`, `APP_IAC` — ask the builder for a value, offer default if one exists.
- **Auto-detected (1)**: `AWS_ACCOUNT_ID` — detect via AWS CLI and auto-accept, fall back to manual prompt on failure.
- **Auto-set (1)**: `APP_CODE_AGENT` — set silently without prompting. Fixed for this iteration.

### .env File Format

The `.env` file uses standard `KEY=VALUE` format:

- One variable per line
- No quotes around values
- No spaces around `=`
- Comments start with `#`
- IPA-managed variables are written as a group with a header comment
- Extra (non-IPA) variables may exist elsewhere in the file and MUST be preserved

Example (with profile):

```
# IPA Project Configuration
# Generated by /ipa-init — local only, do not commit
AWS_PROFILE=my-profile
AWS_REGION=us-east-1
AWS_ACCOUNT_ID=123456789012
APP_NAMESPACE=myproject
APP_ENV=dev
APP_CODE_AGENT=claude-code
APP_IAC=cloudformation
```

Example (no profile — uses default credential chain):

```
# IPA Project Configuration
# Generated by /ipa-init — local only, do not commit
AWS_REGION=us-east-1
AWS_ACCOUNT_ID=123456789012
APP_NAMESPACE=myproject
APP_ENV=dev
APP_CODE_AGENT=claude-code
APP_IAC=cloudformation
```

---

## Validation Rules

You MUST validate every value before writing `.env`. If a value fails validation, reject it with the specific error message below and re-prompt the builder.

| Variable | Pattern | Error Message |
|----------|---------|---------------|
| `AWS_PROFILE` | Non-empty string, or `none` to skip | "AWS_PROFILE must be a profile name or 'none' to skip" |
| `AWS_REGION` | `/^[a-z]{2}-[a-z]+-\d+$/` | "Invalid region format — expected format like us-east-1" |
| `AWS_ACCOUNT_ID` | `/^\d{12}$/` | "Invalid account ID — must be exactly 12 digits" |
| `APP_NAMESPACE` | `/^[a-z][a-z0-9-]{0,11}$/` | "Invalid namespace — must be 1-12 chars, lowercase letters/digits/hyphens, must start with a letter" |
| `APP_ENV` | `/^[a-z][a-z0-9-]{0,11}$/` | "Invalid environment — must be 1-12 chars, lowercase letters/digits/hyphens, must start with a letter" |
| `APP_IAC` | `cloudformation` or `terraform` | "Invalid IaC tool — must be 'cloudformation' or 'terraform'" |

### Validation Behavior

- Validate all prompted values together after both batched prompts return.
- If any value fails: display error messages for ALL failing values at once, then re-prompt ONLY the failing value(s). Do NOT re-ask values that passed.
- Use a simple text prompt (not AskUserQuestion) for re-prompts of failing values.
- Do NOT write `.env` if any value is invalid.
- `APP_CODE_AGENT` is auto-set to a fixed value and does not require validation.

---

## First-Time Initialization

### Step 1: Detect Init Mode

Check if `.env` exists at the project root:

- **If `.env` is missing or empty** (zero bytes or only whitespace/comments): enter the **First-Time Initialization** flow below.
- **If `.env` exists and contains at least one KEY=VALUE pair**: enter the **Re-Initialization** flow (see next section).

### Step 2: Batched Configuration Prompt

Ask the five values in **two** `AskUserQuestion` calls — questions 1–4 in the first, question 5 in the second. Do NOT ask them one at a time, and do NOT put all five in one call.

> **Two hard limits of the tool, and breaking either means the builder is never prompted at all.** `AskUserQuestion` accepts **at most 4 questions per call**, and **every question needs at least 2 options** — the built-in "Other" path is added by the tool and does not count toward that minimum. A call that breaks either limit is rejected with `InputValidationError` before anything renders, so the agent is left to fill `.env` in from whatever context it has. This was measured on 2026-08-18: a single five-question call whose namespace question offered only `"app"` was rejected on both counts at once, and the run continued with values nobody confirmed. Keep four-plus-one, and keep two options on every question.

Before the first prompt, display:

> **Let's configure your project.** Answer the four questions below, then one more. Sensible defaults are pre-selected — accept them all for the fastest setup.

Questions 1–4 (first `AskUserQuestion` call):

1. **AWS_PROFILE** (header: "Profile", multiSelect: false)
   - Question: "Which AWS CLI profile should IPA use?"
   - Options:
     - **"Skip" (Recommended)** — "Use default AWS credential chain (env vars, SSO, instance profile)"
     - **"default"** — "Use the AWS CLI profile named 'default'"
   - Other (built-in): builder types a custom profile name
   - **Do NOT suggest, recommend, or infer a profile name.** Do not offer examples or guess a profile name based on the project, directory, or any other context.
   - If the builder selects "Skip": **omit `AWS_PROFILE` from `.env` entirely** (do not write the line).
   - If the builder selects "default" or types a custom name via "Other": use that value.

2. **AWS_REGION** (header: "Region", multiSelect: false)
   - Question: "Which AWS region for deployments?"
   - Options:
     - **"us-east-1" (Recommended)** — "N. Virginia — default region for most AWS services"
     - **"us-west-2"** — "Oregon"
     - **"eu-west-1"** — "Ireland"
   - Other (built-in): builder types a custom region

3. **APP_NAMESPACE** (header: "Namespace", multiSelect: false)
   - Question: "Choose a project namespace. All CloudFormation stacks start with `{namespace}-{env}-`. Must be unique per account+environment. (1-12 chars, lowercase letters/digits/hyphens, starts with letter)"
   - Options:
     - **"app" (Recommended)** — "Default namespace — good for single-project accounts"
     - **"sandbox"** — "Throwaway namespace — good for an account you share with other projects"
   - Other (built-in): builder types a custom namespace
   - Both options are fixed strings. Do NOT infer a namespace from the directory name or drop the second option to offer only `"app"`: a one-option question is rejected by the tool (see the limits above), and this is the question most builders override.

4. **APP_ENV** (header: "Env", multiSelect: false)
   - Question: "Which environment?"
   - Options:
     - **"dev" (Recommended)** — "Development environment"
     - **"stage"** — "Staging environment"
     - **"prod"** — "Production environment"
   - Other (built-in): builder types a custom environment

Question 5 (second `AskUserQuestion` call, sent as soon as the first returns — do not end your turn between the two):

5. **APP_IAC** (header: "IaC Tool", multiSelect: false)
   - Question: "Which infrastructure-as-code tool?"
   - Options:
     - **"cloudformation" (Recommended)** — "AWS-native, zero additional tooling"
     - **"terraform"** — "HashiCorp Terraform with S3 state backend"
   - Other (built-in): builder types a custom value (reject unless `cloudformation` or `terraform`)

### Step 3: Post-Batch Validation and Account Detection

After both batched prompts have returned all 5 answers:

1. **Validate all values** per the Validation Rules section. Check every value, then:
   - If ALL values pass: continue to account detection.
   - If any value from "Other" fails validation: display error messages for ALL failing values at once, then re-prompt ONLY the failing value(s) using a simple text prompt (not AskUserQuestion). Do NOT re-ask values that passed. Example:
     ```
     Validation failed:
       APP_NAMESPACE: "my--project" — Invalid: cannot contain consecutive hyphens

     Re-enter APP_NAMESPACE (1-12 chars, lowercase letters/digits/hyphens, starts with letter):
     ```

2. **Auto-detect AWS_ACCOUNT_ID** using the profile from Question 1:
   - If profile was skipped: run `aws sts get-caller-identity --query Account --output text`
   - If profile provided: run `aws sts get-caller-identity --profile <profile> --query Account --output text`
   - **If the command succeeds**: auto-accept the 12-digit result. Do NOT ask the builder to confirm. Display: "Detected AWS Account ID: `<detected_value>`"
   - **If the command fails** (AWS CLI not installed, invalid credentials, expired session, or any error): silently skip auto-detection. Prompt the builder manually: "AWS account ID could not be auto-detected. Enter your 12-digit AWS Account ID:" — Validate: `/^\d{12}$/`. This is the ONLY scenario that adds an extra interaction.

3. **Auto-set** (do not prompt):
   - `APP_CODE_AGENT=claude-code`

### Step 4: Summary and Write

Display a summary table of all values:

```
┌─────────────────┬──────────────────┬───────────────┐
│ Variable        │ Value            │ Source        │
├─────────────────┼──────────────────┼───────────────┤
│ AWS_PROFILE     │ my-dev-admin     │ prompted      │
│ AWS_REGION      │ us-east-1        │ default       │
│ AWS_ACCOUNT_ID  │ 123456789012     │ auto-detected │
│ APP_NAMESPACE   │ myproject        │ prompted      │
│ APP_ENV         │ dev              │ default       │
│ APP_CODE_AGENT  │ claude-code      │ auto-set      │
│ APP_IAC         │ cloudformation   │ default       │
└─────────────────┴──────────────────┴───────────────┘
```

The **Source** column MUST indicate how each value was determined:
- `prompted` — builder typed the value
- `default` — builder accepted the default
- `skipped` — builder chose to omit this variable (AWS_PROFILE only)
- `auto-detected` — detected from AWS CLI (auto-accepted, no confirmation)
- `auto-set` — set automatically, not prompted

If `AWS_PROFILE` was skipped, show it as:
```
│ AWS_PROFILE     │ (not set)        │ skipped       │
```
and do NOT write the `AWS_PROFILE=` line to `.env`.

**Immediately write `.env`** in KEY=VALUE format with the header comment block. Do NOT ask "Does this look correct?" — the builder confirmed their choices in the batched prompts.

After writing, display: "Configuration written to `.env`. Re-run `/ipa-init` to change any values."

If `APP_IAC=terraform`, proceed to **Step 4.5: Bootstrap Terraform State Backend**. Otherwise, proceed to **Step 5: Next Step Guidance**.

### Step 4.5: Bootstrap Terraform State Backend

**This step runs only when `APP_IAC=terraform`.** Skip entirely for `cloudformation`.

Terraform requires a state backend (S3 bucket + DynamoDB lock table) to exist before any module can run. Bootstrapping it during `/ipa-init` makes the project deploy-ready in one step — `/ipa-compose` then generates Makefiles that work on first run, with no separate prepare step required for state.

#### 4.5.1 Pre-flight Check

Before deploying anything:

1. **Credentials available?** If `AWS_ACCOUNT_ID` was set via manual fallback (auto-detection failed in Step 3), credentials are not usable for CFN deploy. Display:

   > **Cannot bootstrap Terraform state backend.** AWS credentials are not configured (`aws sts get-caller-identity` failed earlier). After configuring credentials, run `make -f scripts/prepare.mk prepare-tfstate` once `/ipa-compose` has generated `prepare.mk` (the prepare target is the fallback path for state-backend bootstrapping).

   Skip the deploy and proceed to **Step 5: Next Step Guidance**. The skill does NOT fail.

2. **CloudFormation template present?** Verify `infra/cfn/tfstate/tfstate.yml` exists. If not, display an error and skip the bootstrap (same fallback messaging as above).

#### 4.5.2 Deploy the State Backend

Display:

> **Bootstrapping Terraform state backend** — deploying `{APP_NAMESPACE}-{APP_ENV}-tfstate` (S3 bucket + DynamoDB lock table). This typically takes 30-60 seconds.

Run:

```bash
aws cloudformation deploy \
  --stack-name {APP_NAMESPACE}-{APP_ENV}-tfstate \
  --template-file infra/cfn/tfstate/tfstate.yml \
  --parameter-overrides Namespace={APP_NAMESPACE} Environment={APP_ENV} \
  --no-fail-on-empty-changeset \
  $(if AWS_PROFILE,--profile AWS_PROFILE,) \
  --region {AWS_REGION}
```

The `--no-fail-on-empty-changeset` flag makes re-runs safe — if the stack already exists with the same parameters, the command is a no-op.

#### 4.5.3 Capture Outputs

Query the stack for `StateBucketName` and `LockTableName`:

```bash
aws cloudformation describe-stacks \
  --stack-name {APP_NAMESPACE}-{APP_ENV}-tfstate \
  --query 'Stacks[0].Outputs[?OutputKey==`StateBucketName`].OutputValue' \
  --output text \
  $(if AWS_PROFILE,--profile AWS_PROFILE,) \
  --region {AWS_REGION}
```

Repeat for `LockTableName`.

#### 4.5.4 Write Outputs to .env

Append (or replace, if already present) two lines under a `# Terraform State Backend` header:

```
# Terraform State Backend (written by /ipa-init after tfstate deploy)
TF_STATE_BUCKET=<StateBucketName>
TF_STATE_LOCK_TABLE=<LockTableName>
```

Use the same `grep -v` strip-then-append idiom that `env.mk` uses, so re-runs converge to the same content.

#### 4.5.5 Failure Handling

If the deploy or describe-stacks call fails:

- **Network or credential error**: display the error and the same fallback message from 4.5.1. The skill does NOT fail — the rest of init has already succeeded.
- **CFN deploy error (e.g., name collision)**: display the CFN error message and instruct the builder to investigate. Do NOT roll back automatically.

After 4.5 completes (success or fallback), proceed to **Step 5: Next Step Guidance**.

---

## Re-Initialization

This flow runs when `.env` already exists and contains at least one KEY=VALUE pair.

### Step 1: Read and Parse Existing .env

1. Read the `.env` file line by line.
2. Separate lines into two groups:
   - **IPA-managed variables**: `AWS_PROFILE`, `AWS_REGION`, `AWS_ACCOUNT_ID`, `APP_NAMESPACE`, `APP_ENV`, `APP_CODE_AGENT`, `APP_IAC`, `TF_STATE_BUCKET`, `TF_STATE_LOCK_TABLE`
   - **Extra lines**: all other lines (other variables, comments, blank lines) — these belong to other tooling and MUST be preserved exactly as-is.

   `TF_STATE_BUCKET` and `TF_STATE_LOCK_TABLE` are written by Step 4.5 when `APP_IAC=terraform`. They are NOT prompted in any flow — preserve them in re-init exactly as found.
3. If the file is malformed (e.g., lines with no `=` delimiter that aren't comments or blank), warn the builder: "Some lines in .env appear malformed. Would you like to repair them or keep them as-is?" Offer to fix or preserve.

### Step 2: Display Current Values

Show the builder their current IPA configuration:

```
Current IPA Configuration:
┌─────────────────┬──────────────────┐
│ Variable        │ Current Value    │
├─────────────────┼──────────────────┤
│ AWS_PROFILE     │ my-dev-admin     │
│ AWS_REGION      │ us-east-1        │
│ AWS_ACCOUNT_ID  │ 123456789012     │
│ APP_NAMESPACE   │ myproject        │
│ APP_ENV         │ dev              │
│ APP_CODE_AGENT  │ claude-code      │
│ APP_IAC         │ cloudformation   │
└─────────────────┴──────────────────┘
```

If extra (non-IPA) variables exist, note: "Your .env also contains N additional variable(s) not managed by IPA. These will be preserved."

### Step 3: Selective Update

Ask: "Which values would you like to change? (enter variable names separated by commas, or 'none' to keep all):"

- Only prompt for the variables the builder selects.
- For each selected variable, show the current value and prompt for a new one.
- Validate each new value per the Validation Rules section.
- `APP_CODE_AGENT` is auto-set and cannot be changed by the builder.

**Special case — AWS_PROFILE changed**: If the builder changes `AWS_PROFILE`, re-run AWS_ACCOUNT_ID auto-detection using the new profile. Present the new detected value for confirmation. If detection fails, ask if they want to update `AWS_ACCOUNT_ID` manually.

### Step 4: Re-Compose Warning

If the builder changed `APP_NAMESPACE` or `APP_ENV`, display this warning BEFORE confirmation:

> **Warning**: You changed `APP_NAMESPACE` and/or `APP_ENV`. These values are baked into Makefiles by `/ipa-compose`. You MUST re-run `/ipa-compose` after this update to regenerate Makefiles with the new values.

#### IaC Engine Switch Guardrail

If the builder changed `APP_IAC` (e.g., `cloudformation` → `terraform` or vice versa), this is a **major change** that breaks state continuity. Stacks deployed by the previous engine are invisible to the new one.

Before confirmation, display:

> **DANGER: Switching IaC engine from `{old}` to `{new}`.**
>
> Resources deployed by `{old}` are NOT visible to `{new}` and will not be managed, updated, or torn down by the new engine. Switching engines on a project with deployed infrastructure typically results in:
>
> - Orphaned resources you must clean up manually
> - Duplicate resource creation if you redeploy with the new engine (name collisions)
> - Lost ability to use `/ipa-destroy` against the old stacks
>
> **Recommended path**: Run `/ipa-destroy` (and any manual prepare-stack teardowns) BEFORE switching `APP_IAC`. Then run `/ipa-init` to switch, followed by `/ipa-compose` and `/ipa-prepare`.
>
> If you have NOT yet deployed any stacks, switching is safe.

Use `AskUserQuestion` to require explicit confirmation:

- **"I have not deployed any stacks yet — proceed with switch"**
- **"Cancel — keep `APP_IAC={old}`"** *(Recommended)*
- **"I understand the risks — proceed anyway"**

If the builder cancels, leave `APP_IAC` unchanged and continue with any other selected updates. If the builder proceeds and the **new** value is `terraform`, the post-write flow MUST run **Step 4.5: Bootstrap Terraform State Backend** (same as first-time init) so `TF_STATE_BUCKET` and `TF_STATE_LOCK_TABLE` are populated.

### Step 5: Confirm and Write

Display a summary of changes only (unchanged values marked as "unchanged"):

```
┌─────────────────┬──────────────────┬──────────────────┬───────────┐
│ Variable        │ Old Value        │ New Value        │ Status    │
├─────────────────┼──────────────────┼──────────────────┼───────────┤
│ AWS_PROFILE     │ my-dev-admin     │ my-prod-admin    │ changed   │
│ AWS_REGION      │ us-east-1        │ us-east-1        │ unchanged │
│ AWS_ACCOUNT_ID  │ 123456789012     │ 987654321098     │ changed   │
│ APP_NAMESPACE   │ myproject        │ myproject        │ unchanged │
│ APP_ENV         │ dev              │ dev              │ unchanged │
│ APP_CODE_AGENT  │ claude-code      │ claude-code      │ auto-set  │
│ APP_IAC         │ cloudformation   │ cloudformation   │ unchanged │
└─────────────────┴──────────────────┴──────────────────┴───────────┘
```

Ask: "Does this look correct? (yes to write, no to start over):"

- **If confirmed**: rewrite `.env` preserving all extra (non-IPA) variables in their original positions. IPA variables are written as a group with the standard header comment. Then:
  - **If `APP_IAC` was changed to `terraform`**: run Step 4.5 (Bootstrap Terraform State Backend).
  - **If `APP_IAC` was changed to `cloudformation`**: leave existing `TF_STATE_BUCKET` / `TF_STATE_LOCK_TABLE` lines in `.env` (they are harmless when unused; the builder may switch back later).
  - Otherwise proceed directly to **Step 5: Next Step Guidance**.
- **If the builder confirms no changes**: leave `.env` untouched. Proceed to **Step 5: Next Step Guidance**.
- **If rejected**: restart from Step 3.

### Extra Variable Preservation

When rewriting `.env`:

1. Collect all non-IPA lines (comments, blank lines, extra variables) and their original line positions.
2. Write the IPA variable block (with header comment) at the top of the file.
3. Append all non-IPA lines after the IPA block, preserving their original relative order.
4. Never delete, modify, or reorder extra variables.

---

## Step 5: Next Step Guidance

**If `/ipa-compose` invoked this skill through its Phase 0.5 auto-init gate**, display one line —

```
Initialization complete: .env written.
```

— and then **continue `/ipa-compose` from its Phase 0 in the same turn.** Do not display the next-step block below and do not end your turn: compose delegated by loading this skill's instructions into its own turn, so nothing resumes it except you carrying on. Writing `.env` is a step in that composition, not the end of a task.

**If the builder invoked this skill directly**, display:

```
Initialization complete.

Next: Run `/ipa-compose` to compose infrastructure and generate Makefiles.
      Security configuration is handled automatically on first compose.
```

Then stop. Do NOT invoke any other skill — the builder runs `/ipa-compose` next.

---

## Edge Cases

### Malformed .env File

If `.env` exists but contains lines that are not valid KEY=VALUE pairs, comments, or blank lines:

1. Warn the builder: "Your .env file contains malformed lines (lines without a `=` delimiter that aren't comments). These lines may cause issues."
2. List the malformed lines.
3. Ask: "Would you like to (a) repair these lines, (b) remove them, or (c) keep them as-is?"
4. Proceed with the chosen action, then continue with the re-init flow.

### AWS_PROFILE Not Found Locally

After the builder provides `AWS_PROFILE` (skip this check if the builder chose to omit the profile), check if it exists in `~/.aws/config` or `~/.aws/credentials`:

1. Run: `aws configure list-profiles` (or check the config files directly).
2. If the profile is NOT found: display a non-blocking warning: "Note: Profile '<profile_name>' was not found in your local AWS configuration (~/.aws/config). This is OK if the profile exists on another machine or will be configured later."
3. Do NOT reject the value — accept it and continue.

### Invalid CloudFormation Stack Name

`APP_NAMESPACE` is used in stack names via `{namespace}-{env}-{service}`. The validation regex (`/^[a-z][a-z0-9-]{0,11}$/`) already prevents most invalid names, but additionally:

- Reject namespaces that start or end with a hyphen.
- Reject namespaces that contain consecutive hyphens (`--`).
- If rejected, explain: "This namespace would produce an invalid CloudFormation stack name. Stack names must contain only alphanumeric characters and hyphens, and cannot start/end with a hyphen or contain consecutive hyphens."

### AWS STS Failure During Auto-Detection

If `aws sts get-caller-identity` fails for any reason:

- Do NOT display the error output to the builder.
- Do NOT treat this as a failure state.
- Simply fall back to manual prompting for `AWS_ACCOUNT_ID`.
- The skill MUST work on machines without AWS CLI installed.

### Empty or Whitespace-Only .env

If `.env` exists but contains only whitespace, blank lines, or comments (no KEY=VALUE pairs):

- Treat this as a first-time initialization (same as missing `.env`).
- Do NOT attempt to parse or preserve the empty content.