update docs

docs/lambdas-md/lambda-14-local-dev.md

@@ -0,0 +1,74 @@
+# Local Dev
+
+> SAM CLI, Lambda RIE, LocalStack, MinIO — when to reach for which.
+
+## The local dev problem
+
+Lambda has no local runtime by default. Your only loop without tooling is: zip, upload, invoke, read CloudWatch logs, repeat — minutes per cycle. The tools below collapse that to seconds, with different trade-offs between fidelity, setup cost, and scope.
+
+## SAM CLI
+
+**What it is:** AWS's official local Lambda emulator. Wraps Docker to run your function inside a container that matches the Lambda runtime environment exactly. Also emulates API Gateway.
+
+**Commands:**
+
+```bash
+sam local invoke -e event.json          # invoke once
+sam local start-api                       # spin up local HTTP API gateway
+sam local invoke --debug-port 5858       # attach debugger
+```
+
+**Fidelity:** high — same Amazon Linux image, same runtime, same filesystem layout. Catches architecture issues (x86 wheel on arm64) that a plain venv misses.
+
+**Downsides:** requires Docker, slow to start (pulls image on first run), no MinIO/SQS/DynamoDB emulation built in. You wire those up separately.
+
+## Lambda Runtime Interface Emulator (RIE)
+
+A lightweight binary embedded in all AWS-provided Lambda base images. When you run the image locally, RIE exposes a local HTTP endpoint that accepts invocations in the Lambda API format. You don't need SAM CLI — just Docker:
+
+```bash
+docker build -t my-fn .
+docker run -p 9000:8080 my-fn
+curl -XPOST http://localhost:9000/2015-03-31/functions/function/invocations \
+  -d '{"key": "value"}'
+```
+
+Use RIE when you're building container-image Lambdas and want to test them without SAM overhead.
+
+## LocalStack
+
+A full AWS mock that emulates Lambda, S3, SQS, DynamoDB, API Gateway, and dozens more services in a single container. Community edition is free; Pro ($35/month) adds more services and persistent state.
+
+**When to use:** integration tests that span multiple AWS services (e.g. an EventBridge rule that triggers a Lambda that writes to DynamoDB). Without LocalStack you'd need a real AWS account for these tests.
+
+**When to avoid:** if you only need one service (just S3 → use MinIO; just Lambda → use SAM/RIE). LocalStack's Lambda emulation has occasional edge-case differences from the real runtime.
+
+```bash
+docker run --rm -p 4566:4566 localstack/localstack
+AWS_DEFAULT_REGION=us-east-1 \
+  AWS_ACCESS_KEY_ID=test \
+  AWS_SECRET_ACCESS_KEY=test \
+  aws --endpoint-url=http://localhost:4566 s3 ls
+```
+
+## MinIO (this project)
+
+MinIO is an S3-compatible object store that runs locally in Docker. It implements the S3 API precisely enough that `boto3`/`aioboto3` needs only an `endpoint_url` override to work against it. It is **not** a Lambda emulator — it replaces S3 only.
+
+```bash
+make up           # starts MinIO on :9000 (API) and :9001 (console)
+SOURCE_DIR=~/pdfs make seed   # uploads PDFs to MinIO
+make invoke       # runs lambda_function.py against MinIO via invoke.py
+```
+
+This is the lightest possible local setup: no Docker-in-Docker, no SAM overhead, minimal latency. The function handler runs in your local Python process against a real S3-compatible store. Differences from real Lambda (no execution environment lifecycle, no /tmp isolation between runs) are acceptable for the development loop but not for environment-fidelity tests.
+
+## Decision matrix
+
+| Need | Reach for |
+|------|-----------|
+| Fast iteration on handler logic | MinIO + `python invoke.py` (this project's setup) |
+| Emulate Lambda runtime + API Gateway locally | SAM CLI |
+| Test a container-image Lambda | Lambda RIE via Docker |
+| Integration test across multiple AWS services | LocalStack |
+| Full-fidelity staging before prod | Real AWS account, separate environment |