README.md

@@ -37,6 +37,36 @@ Single stack `seahaven-external-dev-baseline`:
 - **No WAF, SES monitoring, Bedrock logging, DynamoDB CMK, or AWS Backup** —
   all production-only concerns in the source baseline.
 
+## CDK app
+
+This repo is an AWS CDK application (TypeScript). `cdk.json` is the CDK
+entry point: it sets `app` to `npx ts-node bin/app.ts`, so the CLI runs the
+TypeScript source directly with no separate build step, and pins the CDK
+feature flags / context the stack synthesizes against.
+
+Layout follows the standard CDK project structure:
+
+| Path | Purpose |
+|---|---|
+| `cdk.json` | CDK config — `app` command, `watch` globs, and feature-flag context |
+| `bin/app.ts` | App entry point; instantiates the stack with explicit `stackName`, target account `396287094661`, and `us-east-1`, and reads `flowLogVpcIds` from context |
+| `lib/external-dev-baseline-stack.ts` | The `seahaven-external-dev-baseline` stack; composes the constructs below |
+| `lib/detective-controls.ts` | AWS Config, GuardDuty, Security Hub (FSBP + CIS v3.0), IAM Access Analyzer |
+| `lib/flow-logs.ts` | VPC flow-logs bucket and (when VPC ids are supplied) flow logs |
+| `lib/governance-toggles.ts` | Monthly cost Budget and alert subscriptions |
+
+Local workflow (from the repo root):
+
+```bash
+npm ci
+npx cdk synth   # synthesize CloudFormation (also `npm run synth`)
+npx cdk diff    # diff against the deployed stack (`npm run diff`)
+npx cdk deploy  # deploy (`npm run deploy`)
+```
+
+`cdk.json` is committed; `cdk.out/` (synth output) and compiled `*.js` /
+`*.d.ts` artifacts are git-ignored.
+
 ## Configuration
 
 | Input | Where | Value |