vybekiit 0.7.0 → 0.7.2

package/dist/global-skills/aws-serverless/references/architecture.md

@@ -1,123 +1,262 @@
 # Serverless Architecture Patterns
 
-Pattern selection and the opinionated service defaults / constraints for each. The patterns themselves are standard — the value here is the default-vs-alternative choices and the non-obvious constraints.
+Reference architectures, pattern selection flowcharts, and service selection tables for common serverless workloads.
 
-## Pattern selection
+## Contents
 
-| What you're building | Pattern |
-|---|---|
-| Synchronous request/response API | REST/HTTP API → Lambda → DynamoDB |
-| Processing events from a queue/stream/database | Event processing (SQS/Streams → Lambda) |
-| Multi-step workflow with branching/error handling | Orchestration (Step Functions) |
-| Real-time bidirectional / LLM streaming | WebSocket API or Function URL streaming |
-| One event → multiple independent consumers | Async fan-out (EventBridge / SNS) |
-| Recurring task on a schedule | EventBridge Scheduler → Lambda / Step Functions |
+- [Pattern selection flowchart](#pattern-selection-flowchart)
+- [REST/HTTP API pattern](#resthttp-api-pattern)
+- [Event processing pattern](#event-processing-pattern)
+- [Orchestration pattern](#orchestration-pattern)
+- [Real-time streaming pattern](#real-time-streaming-pattern)
+- [Async fan-out pattern](#async-fan-out-pattern)
+- [Scheduled jobs pattern](#scheduled-jobs-pattern)
+- [Choosing between patterns](#choosing-between-patterns)
+
+---
 
-Most real apps combine several. Start with one (a CRUD API on DynamoDB covers most initial needs); add event processing for async work, orchestration for multi-step workflows, fan-out for cross-service comms.
+## Pattern selection flowchart
+
+```
+What are you building?
+│
+├── Synchronous request/response API?
+│   └── REST/HTTP API pattern
+│
+├── Processing events from a queue/stream/database?
+│   └── Event processing pattern
+│
+├── Multi-step workflow with branching/error handling?
+│   └── Orchestration pattern
+│
+├── Real-time bidirectional communication or LLM streaming?
+│   └── Real-time streaming pattern
+│
+├── One event triggers multiple independent consumers?
+│   └── Async fan-out pattern
+│
+└── Recurring task on a schedule?
+    └── Scheduled jobs pattern
+```
 
 ---
 
 ## REST/HTTP API pattern
 
-CRUD APIs, mobile/web backends, microservices.
+```
+Client → API Gateway (HTTP API) → Lambda → DynamoDB
+                                         → S3 (binary storage)
+```
+
+**When:** CRUD APIs, mobile/web backends, microservices.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
-| API type | HTTP API (simpler) | REST API for WAF, caching, request validation, API keys |
-| Auth | JWT authorizer (HTTP API native) | Cognito (REST native), Lambda authorizer (custom logic) |
-| Database | DynamoDB (on-demand) | RDS Proxy + RDS for relational data |
-| File storage | S3 presigned URLs | Direct upload via API Gateway (10 MB limit) |
-| Function pattern | One function per route | Lambdalith for Express/FastAPI migrations |
+| API type | HTTP API (simpler) | REST API if you need WAF, caching, request validation, API keys |
+| Auth | JWT authorizer (HTTP API native) | Cognito (REST: native Cognito authorizer; HTTP: JWT authorizer), Lambda authorizer (custom logic) |
+| Database | DynamoDB (on-demand) | RDS Proxy + RDS if relational data needed |
+| File storage | S3 with presigned URLs | Direct upload via API Gateway (10 MB limit) |
+| Function pattern | One function per route | Lambdalith if team prefers Express/FastAPI style |
+
+**Key constraints:**
 
-Constraints: HTTP API 30s hard timeout, no WAF/caching; REST API 29s default (adjustable for Regional/private). Both 10 MB payload.
+- HTTP API: 30s hard timeout, no WAF, no caching, 10 MB payload
+- REST API: 29s default timeout (adjustable for Regional/private APIs), 10 MB payload
 
 ---
 
 ## Event processing pattern
 
-Async workloads, decoupled producers/consumers, batch/file processing.
+```
+Event source → SQS → Lambda → DynamoDB / S3
+                ↓
+              DLQ (failed messages)
+```
+
+**When:** Async workloads, decoupled producers/consumers, batch processing, file processing.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
-| Buffer | SQS standard | SQS FIFO if ordering matters (10-msg batch) |
-| Trigger | SQS ESM | S3 event notification → Lambda (file uploads) |
-| Change data capture | DynamoDB Streams → Lambda | EventBridge Pipes → Lambda (no ESM) |
+| Buffer | SQS standard queue | SQS FIFO if ordering matters (10 msg batch limit) |
+| Trigger | SQS event source mapping | S3 event notification → Lambda (file uploads) |
+| Change data capture | DynamoDB Streams → Lambda | EventBridge Pipes → Lambda (no ESM needed) |
 | Stream ingestion | SQS (simpler) | Kinesis (ordered replay, multiple consumers, high-throughput) |
-| Error handling | SQS redrive policy (DLQ) | On-failure destination for streams |
-| Concurrency control | `MaximumConcurrency` on ESM | Reserved concurrency on function |
+| Error handling | SQS redrive policy (DLQ) | On-failure destination (SQS/SNS/S3) for streams |
+| Concurrency control | MaximumConcurrency on ESM | Reserved concurrency on function |
+| Batch processing | ReportBatchItemFailures | Powertools Batch Processor utility |
 
-Constraints: SQS visibility ≥ 6× function timeout; `MaximumConcurrency` and Provisioned Mode mutually exclusive on one ESM; SQS filter drops unmatched messages permanently. **S3 triggers:** never write output to the triggering bucket/prefix (recursion); no native DLQ (use Lambda async DLQ); consider EventBridge for S3 (richer filtering). **DynamoDB Streams:** max 2 consumers/shard, 24h retention, ordering per partition key only.
+**Key constraints:**
+
+- SQS visibility timeout ≥ 6× function timeout
+- MaximumConcurrency and Provisioned Mode are mutually exclusive on same ESM
+- Enable partial batch failure reporting to avoid reprocessing successful messages
+- SQS event filtering automatically deletes unmatched messages (permanently — not sent to DLQ)
+
+**S3 trigger constraints:**
+
+- Recursive invocation risk: never write output to the same bucket/prefix that triggers the function
+- No native DLQ on S3 notifications — use Lambda async invocation DLQ instead
+- Use prefix/suffix filtering to limit which objects trigger the function
+- Consider EventBridge for S3 instead of S3 notifications (richer filtering, multiple targets)
+
+**DynamoDB Streams constraints:**
+
+- Max 2 Lambda consumers per stream shard (use EventBridge Pipes for more)
+- 24-hour stream retention — records expire and cannot be replayed after that
+- Ordering guaranteed per partition key, not globally
 
 ---
 
 ## Orchestration pattern
 
-Multi-step workflows, saga transactions, approval chains, data pipelines, AI agent loops.
+```
+Trigger → Step Functions → Lambda (validate)
+                         → Choice (route by status)
+                         → Parallel (fan-out)
+                         → Lambda (aggregate) → DynamoDB
+```
+
+**When:** Multi-step workflows, saga transactions, approval chains, data pipelines, AI agent loops.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
-| Workflow type | Standard (exactly-once, ≤ 1 year) | Express (< 5 min, high-volume) |
-| Simple transforms | JSONata (inline, no Lambda) | Lambda task (complex logic) |
+| Workflow type | Standard (exactly-once, up to 1 year) | Express (<5 min, high-volume; async=at-least-once, sync=at-most-once) |
+| Simple data transforms | JSONata (inline, no Lambda needed) | Lambda task (complex logic) |
 | Service calls | Direct SDK integration (200+ services) | Lambda intermediary (only if business logic needed) |
-| Human approval | `.waitForTaskToken` | Lambda durable functions `waitForCallback` |
+| Human approval | .waitForTaskToken | Lambda durable functions waitForCallback |
 | AI agent loops | Step Functions + Bedrock | Lambda durable functions (code-first, checkpointed) |
+| Error handling | Retry + Catch in ASL | Lambda durable functions try/catch in code |
+
+**Key constraints:**
 
-Constraints: 256 KiB between states (use S3 for large data); Express lacks `.sync`/`.waitForTaskToken`/Distributed Map/Activities; 25,000 history entries (Standard). See [orchestration.md](orchestration.md).
+- 256 KB payload limit between states — use S3 for large data
+- Express: no .sync, no .waitForTaskToken, no Distributed Map, no Activities
+- 25,000 execution history entries (Standard) — split long workflows into child executions
+- Prefer direct SDK integrations over Lambda intermediary functions to reduce latency
 
 ---
 
 ## Real-time streaming pattern
 
-Chat, live dashboards, notifications, LLM token streaming, multiplayer.
+```
+Client ←→ API Gateway WebSocket ←→ Lambda → DynamoDB (connections)
+                                          → Bedrock (LLM responses)
+```
+
+Or for LLM token streaming:
+
+```
+Client → Lambda Function URL (streaming) → Bedrock ConverseStream
+```
+
+**When:** Chat apps, live dashboards, notifications, LLM token streaming, multiplayer games.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
 | Bidirectional | API Gateway WebSocket | AppSync subscriptions (GraphQL) |
 | LLM streaming | Lambda Function URL + ConverseStream | REST API proxy with STREAM mode |
-| Connection state | DynamoDB (connectionId → metadata, TTL to clean up after 2h max) | ElastiCache (higher throughput) |
-| Auth | `$connect` route authorizer | Cognito + custom auth in Lambda |
+| Connection state | DynamoDB (connectionId → metadata, enable TTL to clean up stale connections after 2-hour max duration) | ElastiCache (higher throughput) |
+| Auth | $connect route authorizer | Cognito + custom auth in Lambda |
 
-Constraints: WebSocket 10-min idle / 2-hour max / 128 KB message; Function URL streaming 200 MB, 2 MBps after first 6 MB, Node.js native. **For streaming behind CloudFront, Function URLs should use `AWS_IAM` auth** — use Origin Access Control to sign requests rather than setting auth to `NONE`; if `NONE` is unavoidable, enforce auth at the edge (CloudFront + Lambda@Edge). (For a deliberately public, browser-reachable URL with no edge in front, `NONE` is the intended auth type — see [Function URLs in lambda.md](lambda.md#function-urls) for the required permissions.)
+**Key constraints:**
+
+- WebSocket: 10 min idle timeout, 2 hour max connection, 128 KB message (hard limit)
+- Function URL streaming: 200 MB limit, 2 MBps after first 6 MB, Node.js native support
+- Function URLs **MUST** use `AWS_IAM` auth type. For CloudFront integration, use Origin Access Control (OAC) to sign requests — do not set auth to `NONE`. If `NONE` is unavoidable for other reasons, authentication **MUST** be enforced at the edge (e.g., CloudFront + Lambda@Edge). No native JWT/Cognito support.
 
 ---
 
 ## Async fan-out pattern
 
-One event → multiple independent actions; event-driven microservices.
+```
+Producer → EventBridge → Rule A → Lambda (process)
+                       → Rule B → Step Functions (workflow)
+                       → Rule C → SQS → Lambda (batch)
+```
+
+**When:** One event triggers multiple independent actions, event-driven microservices, cross-service communication.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
 | Event router | EventBridge (content-based routing) | SNS (simpler fan-out, attribute/body filtering) |
-| Point-to-point | EventBridge Pipes (no Lambda glue) | SQS → Lambda ESM |
-| Schema management | EventBridge Schema Registry + Discovery | Manual docs |
+| Point-to-point | EventBridge Pipes (source→target, no Lambda intermediary) | SQS → Lambda ESM |
+| Schema management | EventBridge Schema Registry + Discovery | Manual schema documentation |
 | Cross-account | EventBridge cross-account rules | SNS cross-account subscriptions |
-| Scheduling | EventBridge Scheduler (cron/rate) | EventBridge rules with schedule expression |
+| Scheduling | EventBridge Scheduler (cron/rate) | EventBridge rules (simpler but less flexible) |
+
+**Key constraints:**
 
-Constraints: dedicated event bus per domain (not the default bus); be precise with patterns (broad patterns risk loops); DLQs on all targets.
+- Use dedicated event bus per application domain (not the default bus)
+- EventBridge Pipes eliminates Lambda intermediary functions for source→target integrations
+- Be precise with event patterns — overly broad patterns risk loops
+- Configure DLQs on all targets
 
 ---
 
 ## Scheduled jobs pattern
 
-Cron jobs, periodic sync, report generation, cleanup.
+```
+EventBridge Scheduler → Lambda (task)
+                      → Step Functions (complex workflow)
+```
+
+**When:** Cron jobs, periodic data sync, report generation, cleanup tasks.
+
+**Service selection:**
 
 | Decision | Default | Alternative |
 |---|---|---|
-| Scheduler | EventBridge Scheduler (flexible, one-time + recurring) | EventBridge rules schedule expression (simpler) |
-| Short task (< 15 min) | Lambda directly | — |
-| Long task (> 15 min) | Step Functions (≤ 1 year) | Lambda durable functions |
-| High frequency (< 1 min) | Not supported natively | SQS delay queue + Lambda |
+| Scheduler | EventBridge Scheduler (flexible, one-time + recurring) | EventBridge rules with schedule expression (simpler) |
+| Short task (<15 min) | Lambda directly | — |
+| Long task (>15 min) | Step Functions (up to 1 year) | Lambda durable functions |
+| High frequency (<1 min) | Not supported natively | SQS delay queue + Lambda |
 
-Constraints: minimum interval 1 minute; always make scheduled Lambdas idempotent (at-least-once); prefer EventBridge Scheduler over rules for new projects (flexible time windows).
+**Key constraints:**
+
+- Minimum schedule interval: 1 minute
+- Lambda max timeout: 15 minutes — use Step Functions for longer
+- Always make scheduled Lambda idempotent (scheduler guarantees at-least-once)
+- Use EventBridge Scheduler over EventBridge rules for new projects (more features, flexible time windows)
 
 ---
 
-## Common combinations
+## Choosing between patterns
+
+Most real applications combine multiple patterns:
 
-| Application | Patterns |
+```
+                    ┌─ HTTP API ─── Lambda ─── DynamoDB
+Client ─── CloudFront ─┤
+                    └─ WebSocket ── Lambda ─── DynamoDB
+                                      │
+                                      ▼
+                              EventBridge
+                              ┌────┼────┐
+                              ▼    ▼    ▼
+                            SQS  SFN  Lambda
+                              │    │
+                              ▼    ▼
+                           Lambda  Bedrock
+```
+
+**Common combinations:**
+
+| Application | Patterns used |
 |---|---|
 | SaaS API backend | REST API + Event processing + Scheduled jobs |
 | E-commerce | REST API + Orchestration (order saga) + Fan-out (notifications) |
 | Data pipeline | Scheduled jobs + Event processing + Orchestration |
 | AI chatbot | Real-time streaming + Orchestration (agent loop) |
 | IoT processing | Event processing + Fan-out + Scheduled jobs (aggregation) |
+
+**Begin with a single pattern and add more as requirements grow.** A CRUD API with DynamoDB covers most initial implementations. Add event processing when you need async work. Add orchestration when you need multi-step workflows. Add fan-out when you need cross-service communication.

package/dist/global-skills/aws-serverless/references/concurrency.md

@@ -1,86 +1,200 @@
 # Lambda Concurrency Controls
 
-Four concurrency controls operate at different levels with non-obvious interactions. The exact numbers and mutual-exclusivity rules below are the part that's easy to get wrong.
+Four concurrency controls operate at different levels, solve different problems, and have complex interactions.
+
+## Contents
+
+- [The 4 concurrency types](#the-4-concurrency-types)
+- [Interaction matrix](#interaction-matrix)
+- [Decision scenarios](#decision-scenarios)
+- [Account limits and scaling](#account-limits-and-scaling)
+- [Common mistakes](#common-mistakes)
+- [SnapStart interaction](#snapstart-interaction)
+- [SAM/CDK examples](#samcdk-property-reference)
+
+---
 
 ## The 4 concurrency types
 
-1. **Reserved Concurrency** (scope: function) — sets the **max** concurrent instances AND reserves that capacity from the account pool. Setting to **0** fully throttles the function (emergency shutoff). Use to protect critical functions, cap to protect downstream, or kill-switch.
+### 1. Reserved Concurrency
+Sets the **maximum** concurrent instances for a function and **reserves** that capacity from the account pool so no other function can consume it.
+
+- **Scope:** Function.
+- Reserve 400 → function always gets up to 400, never more. Others share the rest.
+- Setting to **0** completely throttles the function (emergency shutoff).
+- Use for: protecting critical functions, capping to protect downstream, emergency shutoff.
+
+### 2. Provisioned Concurrency
+Pre-initializes execution environments so they are **ready before requests arrive**.
 
-2. **Provisioned Concurrency** (scope: published version or alias — **NOT `$LATEST`**) — pre-initializes environments so they're ready before requests arrive. Spills to on-demand (with cold starts) beyond the provisioned count. Combine with Application Auto Scaling (~70% target). Paid even when idle.
+- **Scope:** Published version or alias (**NOT** `$LATEST`).
+- **Allocation rate:** Up to 6,000 environments per minute when provisioning.
+- Configure 100 on alias `PROD` → first 100 concurrent requests get sub-10ms startup.
+  Request 101+ spills to on-demand with cold starts.
+- **Account-level RPS quota**: RPS = 10 × account concurrency. For example, 1,000 account concurrency → 10,000 RPS cap across all functions. This is an account-level quota, not a per-instance throughput cap. Per-instance throughput = 1 / function duration.
+- Combine with **Application Auto Scaling** (target ~70% utilization).
+- Use for: user-facing APIs, functions with heavy init (ML models, DB pools).
 
-3. **Maximum Concurrency** (scope: per SQS ESM, range **2–1,000**) — caps how many concurrent instances one SQS ESM can invoke. Does **not** reserve anything; other triggers can still consume function concurrency.
+### 3. Maximum Concurrency
+Limits how many concurrent instances a **specific SQS event source mapping (ESM)** can invoke.
 
-4. **Provisioned Mode — ESM** (SQS and Kafka/MSK) — allocates dedicated event pollers for an SQS/Kafka ESM with configurable min/max. Per-poller capacity is an **OR** envelope and differs by source: **SQS = 1 MB/s or 10 concurrent invokes**; **Kafka/MSK = 5 MB/s or 5 concurrent invokes**. Use for high-throughput or spiky traffic where standard ramp-up (5 → +300/min) is too slow.
+- **Scope:** Per ESM. **Range:** 2–1,000. **Sources:** SQS only.
+- Does **not** reserve anything — other triggers can still consume function concurrency.
+- Use for: multiple SQS queues on one function, rate-limiting a specific queue.
 
-## Key numbers and interactions
+### 4. Provisioned Mode — ESM (Kafka 2024, SQS 2025)
+Allocates **dedicated event pollers** for an SQS or Kafka ESM with configurable min/max.
 
-- **Account RPS quota = 10 × account concurrency** (e.g. 1,000 concurrency → 10,000 RPS, across all functions). This is an account quota, not a per-instance cap. Per-instance throughput = 1 / function duration.
-- **Max reservable = account limit − 100.** Lambda always keeps 100 unreserved.
-- **Scaling rate: 1,000 new environments / 10s, per function**
-- Provisioned ≤ Reserved when both are set (reserved is the ceiling).
-- Provisioned counts against the account limit even when idle — monitor `ClaimedAccountConcurrency`.
+- **Scope:** Per ESM.
+- Standard mode: ~5 pollers, +300/min, max 1,250 invokes. Provisioned mode: you control
+  min/max pollers. Each handles up to 1 MB/s, 10 concurrent invokes.
+- Use for: high-throughput SQS/Kafka, spiky traffic where standard ramp-up is too slow.
+
+---
+
+## Interaction matrix
 
 | Combination | OK? | Notes |
 |-------------|:---:|-------|
 | Reserved + Provisioned | Yes | Provisioned ≤ Reserved |
-| Reserved + Maximum Concurrency (ESM) | Yes | Reserved ≥ Σ(Maximum Concurrency across ESMs) |
-| Provisioned + Maximum Concurrency / Provisioned Mode (ESM) | Yes | Different layers |
-| **Maximum Concurrency + Provisioned Mode (same ESM)** | **No** | **Mutually exclusive** |
-| **Provisioned Concurrency + SnapStart** | **No** | **Mutually exclusive** |
-
-**At the limit:** Sync → 429. Async → retries up to 6h then DLQ. Streams → polling throttled, messages stay in source.
+| Reserved + Max Concurrency (ESM) | Yes | Reserved ≥ Σ(max concurrency across ESMs) |
+| Reserved + Provisioned Mode (ESM) | Yes | Independent layers |
+| Provisioned + Max Concurrency (ESM) | Yes | Different layers |
+| Provisioned + Provisioned Mode (ESM) | Yes | Warms envs vs warms pollers |
+| **Max Concurrency + Provisioned Mode (same ESM)** | No | **Mutually exclusive** |
+| **Provisioned Concurrency + SnapStart** | No | **Mutually exclusive** |
 
-**RPS gotcha:** a 50ms function at 20,000 RPS needs only 1,000 concurrency, but the RPS limit (10×1,000 = 10,000) throttles it. Request account concurrency = 2,000.
+**Key rules:** Account limit is the hard ceiling. Reserved carves from the pool — Lambda
+always keeps **100 unreserved**. Provisioned ≤ Reserved when both set. Max Concurrency is
+advisory to the ESM, not the function.
 
-```bash
-aws service-quotas request-service-quota-increase \
-  --service-code lambda --quota-code L-B99A9384 --desired-value 5000
 ```
+┌──────────────────────────────────────────────────────┐
+│  ACCOUNT: 1,000 concurrency                          │
+│  ┌─────────────────┐  ┌───────────────────────────┐  │
+│  │ RESERVED (400)   │  │ UNRESERVED POOL (600)     │  │
+│  │ ┌─────────────┐  │  │ Shared by all others      │  │
+│  │ │PROVISIONED  │  │  │ Must keep ≥100 always     │  │
+│  │ │(200 warm)   │  │  └───────────────────────────┘  │
+│  │ └─────────────┘  │                                 │
+│  │ + 200 on-demand  │  ESM LAYER (per mapping):       │
+│  └─────────────────┘  Max Concurrency — OR —          │
+│                        Provisioned Mode (not both)     │
+└──────────────────────────────────────────────────────┘
+```
+
+---
 
 ## Decision scenarios
 
-| Scenario | Reserved | Provisioned | Maximum Concurrency (ESM) | Prov Mode (ESM) |
+| Scenario | Reserved | Provisioned | Max Conc (ESM) | Prov Mode (ESM) |
 |----------|:--------:|:-----------:|:--------------:|:---------------:|
-| Protect critical API / cap downstream | Yes | — | — | — |
-| Eliminate cold starts (user-facing API) | Optional | Yes | — | — |
+| Protect critical API from starvation | Yes | — | — | — |
+| Cap function to protect downstream DB | Yes | — | — | — |
+| Eliminate cold starts for user-facing API | Optional | Yes | — | — |
 | Multiple SQS queues, prevent hogging | Yes | — | Yes | — |
 | High-throughput SQS, low-latency | Optional | Optional | — | Yes |
-| Kafka/SQS ESM with spiky traffic | — | — | — | Yes |
-| Predictable daily traffic | — | Yes + AutoScale | — | — |
+| Kafka ESM with spiky traffic | — | — | — | Yes |
+| Predictable daily traffic | — | Yes+AutoScale | — | — |
 | Emergency shutoff | Yes (=0) | — | — | — |
+| Java/.NET heavy init | — | Yes or SnapStart | — | — |
+
+**A — Checkout API:** Reserved=200 + Provisioned=150 + Auto Scaling for peak.
+**B — 3 SQS queues → 1 function:** Reserved=300, Max Concurrency=100 per ESM.
+**C — Kafka stream (spiky):** Provisioned Mode min=5, max=50 pollers.
+**D — Batch job:** Reserved=50, no provisioned.
+
+---
+
+## Account limits and scaling
+
+| Quota | Default | Adjustable? |
+|-------|---------|:-----------:|
+| Account concurrency | 1,000 / Region | Yes |
+| Reservable concurrency | Account − 100 | Scales |
+| RPS limit | 10 × concurrency | Scales |
+| Scaling rate | 1,000 envs / 10s / function | No |
+
+Scaling is per-function, continuously refilled, unused capacity does not accumulate.
+~50 seconds to reach 5,000 concurrency from zero.
+
+**At the limit:** Sync → 429. Async → retries up to 6h then DLQ. Streams → polling
+throttled, messages stay in source.
+
+**RPS constraint:** A 50ms function at 20,000 RPS needs only 1,000 concurrency but the RPS
+limit (10×1,000=10,000) throttles it. Request account concurrency = 2,000.
+
+```bash
+aws service-quotas request-service-quota-increase \
+  --service-code lambda --quota-code L-B99A9384 --desired-value 5000
+```
+
+---
 
 ## Common mistakes
 
-1. **Reserved = 0 left over from an incident** — blocks ALL invocations (429). If a function throttles at low traffic, check this first.
-2. **Reserved too low** — reserve 50, need 80 → throttled at 51 even with spare account capacity.
-3. **Starving other functions** — reserved is subtracted even when unused; be conservative.
-4. **Provisioned without auto scaling** — paying for idle off-peak, spilling on-peak.
-5. **Provisioned on `$LATEST`** — doesn't work; publish a version, create an alias.
-6. **Maximum Concurrency > reserved** — ESM tries 100, function caps at 50. Ensure reserved ≥ Σ(Maximum Concurrency).
-7. **Confusing ESM Maximum Concurrency with reserved** — Maximum Concurrency reserves nothing; API Gateway can still consume all concurrency.
-8. **Forgetting the 100-unit buffer** — max reservable = account limit − 100.
+1. **Reserved set to 0** — Blocks ALL invocations (429 TooManyRequestsException). Sometimes
+   set during an incident and not restored. If a function is throttled at low traffic, check
+   this first.
+
+2. **Reserved too low** — Reserve 50, need 80 → throttled at 51 even with spare account
+   capacity. Fix: monitor `ConcurrentExecutions`, set above peak + buffer.
+
+3. **Starving other functions** — Reserve 800/1,000 → others share 200. Reserved is
+   subtracted even when unused. Fix: be conservative.
+
+4. **Provisioned without auto scaling** — Paying for idle envs off-peak, spilling on-peak.
+   Fix: Auto Scaling targeting ~70% `ProvisionedConcurrencyUtilization`.
+
+5. **Provisioned on `$LATEST`** — Doesn't work. Fix: publish a version, create an alias.
 
-## SnapStart vs Provisioned Concurrency
+6. **Max concurrency > reserved** — ESM tries 100, function caps at 50. Fix: ensure
+   `reserved ≥ Σ(max concurrency across ESMs)`.
 
-> **Mutually exclusive on the same function.**
+7. **Confusing ESM max with reserved** — Max concurrency doesn't reserve anything. API
+   Gateway can still consume all concurrency. Fix: use reserved on the function.
+
+8. **Both ESM controls on same ESM** — Mutually exclusive; API rejects it. Fix: choose one.
+
+9. **Forgetting 100-unit buffer** — Max reservable = account limit − 100.
+
+10. **Not tracking ClaimedAccountConcurrency** — Provisioned counts against account limit
+   even when idle. Monitor the metric.
+
+---
+
+## SnapStart interaction
+
+| Aspect | SnapStart | Provisioned Concurrency |
+|--------|-----------|------------------------|
+| Cold start | Seconds → sub-second | Seconds → ~0 |
+| Runtimes | Java 11+, Python 3.12+, .NET 8+ | All |
+| Scales with traffic | Yes (snapshot restore) | Only up to provisioned count |
+
+> **SnapStart and Provisioned Concurrency are mutually exclusive on the same function.**
 
 ```
-Runtime Java 11+ / Python 3.12+ / .NET 8+
+Is runtime Java 11+, Python 3.12+, or .NET 8+?
 ├─ No  → Provisioned Concurrency
 └─ Yes
    ├─ Need guaranteed <50ms on EVERY request? → Provisioned Concurrency
    ├─ Need EFS or >512MB ephemeral storage?   → Provisioned Concurrency
-   └─ Otherwise → SnapStart first; if P99 still too high, switch (they cannot coexist)
+   └─ Otherwise → SnapStart first; if P99 still too high, switch to Provisioned Concurrency (they cannot coexist)
 ```
 
+Limitations: no EFS, no >512MB ephemeral, no container images, must handle uniqueness,
+re-validate network connections on restore.
+
+---
+
 ## SAM/CDK property reference
 
-| Type | SAM | CDK |
+| Concurrency type | SAM property | CDK property |
 |---|---|---|
-| Reserved | `ReservedConcurrentExecutions` | `reservedConcurrentExecutions` |
-| Provisioned | `AutoPublishAlias` + `ProvisionedConcurrencyConfig.ProvisionedConcurrentExecutions` | `new lambda.Alias({ provisionedConcurrentExecutions })` (alias, not `$LATEST`) |
-| Maximum Concurrency (ESM) | `ScalingConfig.MaximumConcurrency` | `maxConcurrency` on `EventSourceMapping` |
-| Provisioned Mode (ESM) | `ProvisionedPollerConfig.MinimumPollers` / `MaximumPollers` | `provisionedPollerConfig: { minimumPollers, maximumPollers }` |
+| Reserved | `ReservedConcurrentExecutions: 100` | `reservedConcurrentExecutions: 100` |
+| Provisioned | `AutoPublishAlias: live` + `ProvisionedConcurrencyConfig.ProvisionedConcurrentExecutions: 50` | `new lambda.Alias({ provisionedConcurrentExecutions: 50 })` — must use alias, not `$LATEST` |
+| Maximum Concurrency (ESM) | `ScalingConfig.MaximumConcurrency: 50` | `maxConcurrency: 50` on `EventSourceMapping` |
+| Provisioned Mode (ESM) | `ProvisionedPollerConfig.MinimumPollers` / `MaximumPollers` | `provisionedPollerConfig: { minimumPollers, maximumPollers }` on `EventSourceMapping` |
 | SnapStart | `SnapStart.ApplyOn: PublishedVersions` + `AutoPublishAlias` | `snapStart: lambda.SnapStartConf.ON_PUBLISHED_VERSIONS` |
 
-Auto scaling: `alias.addAutoScaling({ minCapacity, maxCapacity })` then `scaling.scaleOnUtilization({ utilizationTarget: 0.7 })`.
+Auto scaling for Provisioned Concurrency: `alias.addAutoScaling({ minCapacity, maxCapacity })` then `scaling.scaleOnUtilization({ utilizationTarget: 0.7 })`.

package/dist/global-skills/aws-serverless/references/deployment.md

@@ -1,6 +1,6 @@
 # Deployment Reference
 
-Serverless-specific resource types and fast-iteration tools. For step-by-step deployment procedures (custom domain REST API, API Gateway stages, connecting Lambda to API Gateway/DynamoDB), use the specialized skills in SKILL.md's routing table.
+Serverless-specific deployment patterns, resource types, and fast iteration tools.
 
 ## Contents