# AGENTS.md

Instructions for coding agents working in this repository.

## Infrastructure as Code principles

- **CDK + EC2**: this repo deploys an EC2 instance via CDK TypeScript. No Lambda, no SAM.
- **Lambda defaults (does not apply)** — this is a pure EC2 stack.
- **Exact-pin all CDK library versions** (`aws-cdk-lib`, `aws-cdk`, `constructs`). Never use `*` or `^` ranges.
- **Never commit** account IDs, role ARNs, VPC IDs, subnet IDs, or volume IDs in new code. The existing `cdk.context.json` already contains resolved values — do not add new deployment-specific identifiers without documented defaults.
- **Deploy with least-privilege IAM.** The instance role already has only `AmazonSSMManagedInstanceCore` + Secrets Manager read on `file-share/*`.
- **Verify**: `npm run build && npx cdk synth && npx cdk diff` before pushing. Do not commit `cdk.out/`.

## CDK directory layout

```
.
├── bin/
│   └── app.ts              # CDK app entrypoint
├── lib/
│   └── file-share-stack.ts  # All resource definitions
├── cdk.json                  # CDK context + config
├── cdk.context.json          # Resolved context (committed)
├── package.json              # Exact-pinned CDK dependencies
├── tsconfig.json
└── .github/
    └── workflows/            # CI/CD
```

## `overrideLogicalId` — never remove

Removing `overrideLogicalId` on a deployed resource forces replacement. Never remove an existing call without documenting the replacement impact.

## Persistent EBS volumes

This repo's data volume (`vol-04d951cccacc435b5`) is **imported by ID**, not managed by CloudFormation. It survives instance replacement and stack deletion.

### Snapshot before an EC2-replacing deploy

Before any deploy that would replace the EC2 instance (AMI change, user-data change, instance type change):

1. Run `cdk diff` to confirm the instance will be replaced.
2. **Stop and ask for confirmation** — an instance replacement detaches the imported volume. A snapshot is the safety net.
3. If a DLM snapshot already exists from the same day, reference it rather than creating a duplicate.

## Security group rules

- Never open 0.0.0.0/0. All rules use specific CIDR ranges (`10.10.0.0/16` VPN, `10.20.0.0/16` VPC).
- SSM Session Manager for instance access — no SSH key, no public port 22.

## Secrets

Stored in AWS Secrets Manager (`file-share/smb-password`, `file-share/filebrowser-password`). The instance role reads them at boot. Do not embed secrets in UserData or source files.

## Documentation

The Confluence "AWS Architecture Map" (page 1540098) should be updated alongside any architecture change.