Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD

- Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure
- Update Lambda runtime default from Node 22 to Node 24
- Rewrite CI/CD page to reflect GitHub Actions reusable workflows
  (was still referencing CodePipeline/CodeBuild)

aws-infrastructure.md

@@ -13,13 +13,25 @@ These apply to every Lambda in every project. Verify, don't assume.
 
 | Setting | Value |
 |---|---|
-| Runtime | Python 3.12 or Node 22.x |
+| Runtime | Python 3.12 or Node 24.x |
 | Architecture | arm64 |
 | Log retention | 60 days (explicit in IaC template) |
 | Naming | kebab-case, matching the stack name prefix |
 
 Never rely on the CloudWatch default for log retention. Always set `RetentionInDays` explicitly in the template.
 
+## CDK Version Policy
+
+Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.253.1**.
+
+Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors. npm `overrides` cannot fix bundled deps. Always test `npm ci` locally before pushing a version bump.
+
+When upgrading, verify on a branch first:
+1. Update `package.json` to the new version
+2. Run `rm -rf node_modules package-lock.json && npm install`
+3. Run `npm ci` — if it fails, the version is not safe
+4. Run `npx cdk synth` — if it fails, the version is not safe
+
 ## CloudFormation Outputs
 
 Every stack should export:

cicd.md

@@ -4,51 +4,91 @@
 
 Every deployable repo must have a CI/CD pipeline. No manual deploys to production. If it deploys to AWS, it needs a pipeline.
 
-## Pipeline Types
+## Platform
 
-### SAM / CDK Stacks
+GitHub Actions is the standard CI/CD platform. All pipelines use reusable workflows from the `Sea-Haven-Industries/.github` org repo (`.github/workflows/`).
 
-Use CodePipeline + CodeBuild, triggered on push to `main`.
+## Workflow Structure
 
-| Stage | Action |
+Every repo gets two thin workflow files in `.github/workflows/`:
-|---|---|
-| Source | GitHub connection (push to `main`) |
-| Build | CodeBuild: `sam build && sam package` or `cdk deploy` |
-| Deploy | CloudFormation changeset execute |
 
-- Build environment: ARM (`aarch64`) to match Lambda architecture
+| File | Trigger | Purpose |
-- Runtime: Match the project's Lambda runtime (Python 3.12, Node 22.x)
+|---|---|---|
-- Pipeline artifacts bucket: `{stack-name}-pipeline-artifacts`
+| `ci.yaml` | `pull_request` on `main` | Lint, typecheck, test, synth/validate |
+| `deploy.yaml` | `push` on `main` | Deploy to AWS |
 
-### Frontend / Static Sites
+### CDK Stacks (TypeScript)
 
-Use CodePipeline or GitHub Actions for build + deploy + cache invalidation.
+```yaml
+# .github/workflows/ci.yaml
+name: CI
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  ci:
+    uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main
+    with:
+      node-version: "24"
 
-| Stage | Action |
+# .github/workflows/deploy.yaml
-|---|---|
+name: Deploy
-| Source | GitHub connection (push to `main`) |
+on:
-| Build | Install dependencies, build static assets |
+  push:
-| Deploy | S3 sync + CloudFront invalidation |
+    branches: [main]
+jobs:
+  deploy:
+    uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main
+    with:
+      node-version: "24"
+    secrets:
+      deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+```
+
+### SAM Stacks (Python)
+
+```yaml
+# .github/workflows/ci.yaml
+name: CI
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  ci:
+    uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main
+
+# .github/workflows/deploy.yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@main
+    with:
+      stack-name: "your-stack-name"
+    secrets:
+      cfn-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+```
+
+## Authentication
+
+Deploy workflows authenticate to AWS via OIDC (no long-lived credentials). Each repo needs:
+
+1. An IAM role named `githubdeploy-<repo-name>` with:
+   - OIDC trust policy for `token.actions.githubusercontent.com`
+   - Subject condition: `repo:Sea-Haven-Industries/<repo>:ref:refs/heads/main`
+   - Inline policy allowing `sts:AssumeRole` on CDK/SAM bootstrap roles
+2. A repo secret `AWS_DEPLOY_ROLE_ARN` containing the role ARN
+
+## Node.js Version
+
+Always pass `node-version: "24"` to reusable workflows. Local dev uses Node 24 / npm 11 which generates lockfileVersion 3. The workflow defaults match this, but be explicit to avoid drift.
 
 ## Naming
 
-- Pipeline: `{stack-name}-pipeline`
+- All workflow files: kebab-case
-- CodeBuild project: `{stack-name}-build`
+- Reusable workflow references: `@main` branch
-- Artifacts bucket: `{stack-name}-pipeline-artifacts`
-
-All kebab-case, matching the stack and repo name.
-
-## What the Pipeline Should Do
-
-At minimum:
-
-1. **Build** — install dependencies, compile/transpile, package
-2. **Deploy** — push to the target environment via CloudFormation or S3
-
-Optionally:
-
-3. **Test** — run unit/integration tests before deploy
-4. **Lint** — check code style and formatting
 
 ## When to Add a Pipeline