file-share/AGENTS.md

# AGENTS.md

Instructions for coding agents working in this repository.

## Live path

The share runs in seahaven-prod under HCP Terraform workspace `file-share-prod`. Source is `terraform/`. Manual apply until the move is sealed. Do not enable auto-apply as part of a docs or cleanup change.

The management-account CDK stack was deleted on 2026-09-29. Do not run `cdk deploy`. `lib/` and `bin/` are the retired stack. The CDK deploy workflow has been removed.

The data volume is attached by the workspace variable `data_volume_id`. Terraform must not create or delete it. The previous management volume was deleted on 2026-09-29.

## Infrastructure as Code principles

- **Exact-pin CDK library versions** if you touch the retired CDK package. Never use `*` or `^` ranges.
- **Never commit** account IDs, role ARNs, VPC IDs, subnet IDs, or new volume IDs. The live volume id is an HCP variable.
- **Deploy with least-privilege IAM.** The instance role has SSM core plus Secrets Manager read on `file-share/*`.
- Do not commit `cdk.out/`.

## Instance replacement

`user_data_replace_on_change` is false. Before any apply that would replace the instance (AMI, user data, instance type):

1. Read the plan and confirm the instance is being replaced.
2. Stop and ask for confirmation. Replacement detaches the data volume.
3. Snapshot the volume first. If a DLM snapshot from the same day exists, use that instead of a second copy.

## Security group rules

- No `0.0.0.0/0` ingress. Ingress is TCP 445, 8080, and 22 from `10.10.0.0/16` and `10.30.0.0/16`.
- Egress `0.0.0.0/0` stays so the instance can install packages and reach the pinned FileBrowser download.
- SSM Session Manager for instance access. No SSH key and no public port 22. SFTP for user `adam` is the office path, not an admin login.

## Secrets

Stored in AWS Secrets Manager (`file-share/smb-password`, `file-share/filebrowser-password`) in seahaven-prod. The instance role reads them at boot. Do not embed secrets in user data or source files. The management-account copies were deleted on 2026-09-29.

## Documentation

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