@raishin/vanguard-frontier-agentic 2.8.0 → 2.10.0

package/skills/aws/aws-agentcore/references/gateway-integration.md

@@ -17,6 +17,8 @@ Official AWS docs imply at least five separate concerns:
 3. **target modeling** — Lambda, OpenAPI/API, Smithy/AWS-service style targets, or MCP servers
 4. **policy enforcement** — Cedar-based controls over who can call what
 5. **tool discovery** — including optional semantic search
+6. **MCP session behavior** — session IDs, per-user scoping, timeout, streaming, and downstream target session state
+7. **interactive MCP flows** — elicitation, sampling, progress notifications, and logging notifications
 
 If you only think “endpoint + tool,” you are missing the real security model.
 
@@ -28,10 +30,12 @@ AWS docs describe Gateway as:
 - a way to connect APIs, Lambda functions, existing services, and pre-existing MCP servers
 - a service that handles both **ingress auth** and **egress auth**
 - a policy-enforced surface where Cedar-based policies gate tool calls
+- a stateful MCP gateway for clients and downstream MCP targets when sessions are enabled
+- a streaming and interactive channel for MCP targets that use elicitation, sampling, progress, or logging messages
 
 That is the key insight:
 
-> Gateway is not just transport. It is identity + auth + policy + discovery.
+> Gateway is not just transport. It is identity + auth + policy + discovery + session governance.
 
 ## Non-negotiable design rules
 
@@ -93,6 +97,34 @@ Different targets mean different risks:
 
 One gateway pattern does not fit all four.
 
+### 6. MCP sessions change state and audit assumptions
+
+Current release notes describe Gateway MCP sessions with a unique `Mcp-Session-Id`, per-authenticated-user scoping, configurable timeouts, and downstream MCP target session state.
+
+Design implications:
+
+- decide whether stateful sessions are required or whether stateless tool calls are safer
+- set session timeout intentionally instead of inheriting defaults blindly
+- bind audit logs to principal + session ID + target tool
+- test what happens when downstream MCP target sessions expire or request user input
+- do not reuse session IDs across users, tenants, or unrelated workflows
+
+### 7. Streaming, elicitation, sampling, progress, and logs are not harmless extras
+
+Newer Gateway docs/release notes describe:
+
+- response streaming via SSE for multiple JSON-RPC messages
+- elicitation pass-through for user input during tool execution
+- sampling messages where MCP servers request LLM completions from the client
+- progress notifications and structured logging notifications
+
+These features increase capability and risk:
+
+- elicitation needs UI/user-consent handling and phishing-resistant prompts
+- sampling can create unexpected model-call cost and data exposure
+- progress/log streams can leak sensitive tool inputs or downstream identifiers
+- streaming clients must handle partial, failed, or reordered events safely
+
 ## Minimal safe implementation flow
 
 1. Identify target type
@@ -100,8 +132,9 @@ One gateway pattern does not fit all four.
 3. Define outbound auth path
 4. Define Cedar policy boundary
 5. Add one target only
-6. Verify tool schema and least-privilege behavior
-7. Add semantic search only if tool catalog size justifies it
+6. Decide whether MCP sessions/streaming/elicitation/sampling are allowed
+7. Verify tool schema and least-privilege behavior
+8. Add semantic search only if tool catalog size justifies it
 
 ## High-risk assumptions to kill
 
@@ -123,6 +156,8 @@ Verify against current docs and local tooling before use:
 - inbound authorization requirements
 - outbound authorization setup
 - policy engine wiring and mode
+- MCP session timeout and `Mcp-Session-Id` behavior
+- SSE/streaming, elicitation, sampling, progress, and logging behavior when using MCP targets
 
 ## When to push back
 

package/skills/aws/aws-agentcore/references/getting-started.md

@@ -10,6 +10,8 @@ Do not blur these together:
 2. **Existing code-based agent** — adapt/configure what exists; do not scaffold over it
 3. **Import/migration from Amazon Bedrock Agents** — use the import flow if the goal is migration, not greenfield creation
 4. **Managed harness** — a config-based path that current AWS docs describe as preview
+5. **Direct code deployment** — current release notes include Node.js direct code deployment as well as Python-oriented paths; do not imply container-only or Python-only deployment.
+6. **Resource import / operational CLI work** — current release notes mention resource import, bash command execution in runtime/local containers, BYO Dockerfile, and Memory streaming. Verify exact installed CLI help before giving commands.
 
 If you pick the wrong path, your advice becomes cargo cult.
 
@@ -19,6 +21,7 @@ If you pick the wrong path, your advice becomes cargo cult.
 - npm
 - AWS credentials configured through AWS CLI, environment variables, or a named profile
 - Python **3.10 or later** for agent code
+- Node.js runtime support exists for direct code deployment; verify the installed CLI/runtime path before assuming Python-only project structure
 - IAM permissions to call AgentCore APIs and assume the CDK bootstrap roles used during deployment
 
 Install the current recommended CLI for new projects:
@@ -70,6 +73,7 @@ Useful flags verified locally:
 Key assumption many people miss:
 
 - For non-Bedrock providers, official harness docs say you need an **API key ARN**, not just “some secret somewhere”.
+- If the project needs shared prompts, skills, datasets, or intermediate artifacts, check whether runtime/harness filesystem mounts with S3 Files or EFS are appropriate before inventing custom download/sync code.
 
 ## Existing code-based agent path
 
@@ -144,12 +148,16 @@ Also:
 - harness skills are **filesystem paths inside the runtime environment**
 - `--skill-path` references a path; it does **not** upload the skill for you
 - some harness docs mention `agentcore invoke --exec` shell access, but installed CLIs may not expose that surface the same way yet
+- release notes now include attached filesystems for runtime and harness sessions; mount paths become part of the runtime contract and must be reviewed for data perimeter, retention, and path-collision risk
+- Agent Inspector can make local `agentcore dev` workflows more observable, but do not assume it is available unless the installed CLI exposes it
 
 ## Security-critical realities
 
 - SigV4 authentication does **not** give per-user identity propagation into downstream tool calls the way the OAuth bearer-token path can.
+- OBO token exchange exists for user-scoped protected resource access. Prefer it over copying user tokens into tool configs when the use case is on-behalf-of access.
 - Gateway security is not “create gateway and done”; policy design is a separate concern.
 - Custom observability requires more than default metrics; official docs call out ADOT and CloudWatch prerequisites for richer traces.
+- Payments are preview and introduce wallet, spending-limit, transaction authorization, and audit requirements. Do not include payments in a production path without explicit preview-risk handling.
 
 ## Minimum safe workflow
 
@@ -161,3 +169,4 @@ Also:
 6. Run `agentcore dev`
 7. Test with `agentcore invoke --dev`
 8. Only then discuss deploy, Memory, Gateway, Policy, Browser, or Code Interpreter wiring
+9. For production agents, add Evaluations / batch evaluation / user simulation / A/B validation before rollout when quality regressions are plausible

package/skills/aws/aws-agentcore/references/memory-integration.md

@@ -15,7 +15,8 @@ AgentCore Memory design has at least four separate concerns:
 1. **resource lifecycle** — create, wait for `ACTIVE`, inspect, delete
 2. **identity model** — `actor_id` and `session_id` are not interchangeable
 3. **namespace design** — what gets stored where
-4. **retention / expiry / deletion** — what survives, for how long, and how you remove it
+4. **metadata filtering** — indexed keys and retrieval filters that change what memories are visible
+5. **retention / expiry / deletion** — what survives, for how long, and how you remove it
 
 If you do not model those explicitly, you create memory bugs that look like “the AI is weird.”
 
@@ -27,7 +28,8 @@ AWS docs and Context7 show Memory supports:
 - long-term strategies such as:
   - session summarization
   - user preference extraction
-  - semantic / fact extraction
+- semantic / fact extraction
+- structured metadata extraction and filtering for long-term memory retrieval
 
 Typical namespace patterns in official examples include:
 
@@ -73,7 +75,18 @@ You need to decide:
 
 If your skill does not surface expiry/deletion, it is not production-ready.
 
-### 4. Wait for resource readiness
+### 4. Metadata schema is an isolation and relevance boundary
+
+Current docs/release notes describe structured metadata filtering for long-term memory. Indexed keys can be declared when creating memory and metadata filters can narrow retrieval/listing.
+
+Do not bolt this on casually:
+
+- decide indexed keys before creation; changing indexed-key strategy later may require new resources or migration
+- avoid indexing sensitive values unless the access model and logs are understood
+- test retrieval with and without filters for same actor/session, new session, and different actor
+- document whether metadata is extracted by LLM strategy, application code, or both
+
+### 5. Wait for resource readiness
 
 Official examples explicitly poll until the memory resource becomes `ACTIVE`.
 
@@ -84,12 +97,14 @@ Do not assume “create returned” means “safe to wire into the agent.”
 1. Create the memory resource
 2. Wait until it is `ACTIVE`
 3. Decide namespace strategy
-4. Wire `memory_id`, `actor_id`, and `session_id` into the agent intentionally
-5. Test:
+4. Decide metadata/index/filter strategy for long-term memory
+5. Wire `memory_id`, `actor_id`, and `session_id` into the agent intentionally
+6. Test:
    - same actor + same session
    - same actor + new session
    - different actor
-6. Verify expiry/deletion behavior before broad rollout
+   - same actor with restrictive metadata filters
+7. Verify expiry/deletion behavior before broad rollout
 
 ## Example patterns from official docs
 
@@ -110,6 +125,7 @@ That means your real integration surface is not just “turn memory on”; it is
 - resource ID
 - actor/session mapping
 - retrieval behavior
+- metadata extraction and filter behavior
 
 ## Adversarial checklist
 
@@ -118,6 +134,8 @@ Before recommending Memory, answer these:
 - What is the source of truth for `actor_id`?
 - What causes a new `session_id`?
 - Which namespace stores preferences vs facts vs summaries?
+- Which metadata fields are indexed?
+- Who can set or influence metadata values?
 - What expires automatically?
 - What is the deletion story?
 - What happens if two applications share the same memory resource?

package/skills/aws/aws-agentcore/references/official-sources.md

@@ -28,12 +28,36 @@ Use this reference when grounding current Amazon Bedrock AgentCore behavior.
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html
 - AgentCore Observability
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html
+- AgentCore generated observability data
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-service-provided.html
 - Browser tool
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html
 - Code Interpreter
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter.html
+- AgentCore Evaluations
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/evaluations.html
+- AgentCore Registry
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html
+- AgentCore Payments
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html
 - AgentCore tools configuration
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html
+- Runtime file system configurations
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html
+- Runtime custom header passthrough
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-header-allowlist.html
+- Gateway MCP sessions
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-sessions.html
+- Gateway MCP elicitation
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-elicitation.html
+- Gateway MCP sampling
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-sampling.html
+- Gateway MCP progress notifications
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-progress.html
+- Gateway MCP logging notifications
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-logging.html
+- Long-term memory metadata filtering
+  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/long-term-memory-metadata.html
 - Policy in AgentCore
   https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html
 - Create a policy
@@ -57,11 +81,47 @@ Use this reference when grounding current Amazon Bedrock AgentCore behavior.
 - Harness overview docs note regional rollout is ongoing and the currently documented harness availability is limited; do not assume every AgentCore feature is live in every region.
 - Official harness docs describe `agentcore invoke --exec` shell access to the session environment, but installed CLI surfaces can drift. Verify the local CLI before promising that workflow.
 
+## Current release-note deltas to account for
+
+The following items were missing or underrepresented in earlier skill guidance and must now be considered before giving implementation advice:
+
+- **Core service map expanded** — current overview docs list Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Payments, Evaluations, Policy, and Registry as AgentCore services/capabilities.
+- **Gateway MCP is now stateful and more interactive** — release notes describe MCP sessions, response streaming, elicitation pass-through, sampling messages, progress notifications, and logging notifications. Gateway advice must cover session scope, timeouts, human-in-the-loop prompts, client streaming behavior, and audit/log handling.
+- **Runtime and Harness support attached filesystems** — release notes describe Amazon S3 Files and Amazon EFS access point mounts for sharing skills, prompt templates, datasets, and intermediate outputs. Treat mounts as data-perimeter and lifecycle risks, not just convenience.
+- **Agent quality loop is first-class** — release notes describe optimization, batch evaluation, user simulation, and A/B testing. Do not treat evaluation as an external afterthought when the user asks for production readiness.
+- **Payments are preview** — payment flows add wallet, spending-limit, x402 endpoint, and transaction-governance risks. Keep this separate from GA runtime/gateway guidance.
+- **Node.js direct code deployment exists** — do not imply Python/container-only deployment paths.
+- **VPC egress and OBO token exchange exist** — Identity, Gateway, and Runtime can reach private resources; user-scoped access can use on-behalf-of token exchange. Verify network and identity boundaries instead of assuming public egress or raw static credentials.
+- **Memory supports structured metadata filtering** — namespace design is no longer enough; indexed metadata keys and retrieval filters can materially change isolation and relevance.
+- **Observability requires setup** — current docs call out CloudWatch Transaction Search setup, tracing enablement for memory resources, consistent session IDs, distributed tracing, custom attributes, resource usage monitoring, and alerts.
+- **AgentCore Registry is in preview** — registry-based discovery and governance can reduce sprawl but introduces approval, publication, semantic-search, and access-control decisions.
+- **AgentCore MCP server exists in awslabs/mcp** — coding agents may operate AgentCore resources through a user-configured AWS credential chain. Treat this as live AWS access requiring the user's read-only or explicitly approved profile.
+
 ## Starter toolkit caveat
 
 - The Bedrock AgentCore Starter Toolkit repository is still useful for migration and existing Python-based workflows.
 - Based on current official AWS devguide evidence, do not present the starter toolkit as the recommended starting point for new projects when the newer `@aws/agentcore` CLI is available.
 
+## Current MCP/documentation refresh (2026-06-02)
+
+Service facts from official docs:
+- Current AgentCore docs cover Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Payments, Evaluations, Policy, and Registry as AgentCore services or capabilities.
+- Gateway MCP guidance includes sessions, response streaming, elicitation, sampling, progress notifications, and logging notifications; these are tool/session governance concerns, not just integration features.
+- AgentCore filesystem, Memory metadata filtering, observability setup, evaluations, registry, payments, VPC egress, and on-behalf-of token exchange materially affect security and production-readiness guidance.
+
+Sampled live evidence:
+- Read-only regional availability sampling reported `isAvailableIn` for Amazon Bedrock AgentCore, Amazon Bedrock, Amazon CloudWatch, and AWS IAM Identity Center in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
+- Read-only API sampling surfaced AgentCore operations for Memory, runtime invocation/commands, Browser, Code Interpreter, Evaluations, A/B tests, recommendations, workload access tokens, and payment operations. Some sampled payment operations were visible only in `us-east-1` and `us-west-2`; treat this as sampled availability evidence only.
+
+Review implications:
+- Keep AgentCore Gateway, Identity, Memory, Browser, Code Interpreter, Evaluations, Registry, Payments, filesystem, and harness advice in references and re-query docs/tooling before promising exact CLI flags, maturity status, API coverage, or regional support.
+- Service/API availability does not prove the user's account quotas, IAM permissions, deployed AgentCore resources, CLI version, or whether preview features are enabled.
+
+## MCP grounding
+
+- Use current AWS documentation tools to find and read the cited AgentCore behavior.
+- Use read-only AWS MCP or read-only AWS CLI evidence for live availability and current-state claims when available. Treat that evidence as complementary to documentation, not as proof of the user's account configuration and never as permission to mutate AWS state.
+
 ## Grounding rule
 
 Docs explain service behavior. They do not prove the user's installed CLI version, active AWS account, IAM role, Region support, quotas, deployed AgentCore resources, or whether preview-only features are enabled in that account.

package/skills/aws/aws-agentcore/references/safety-checklist.md

@@ -10,20 +10,24 @@ Use before AgentCore deployment, tool exposure, Memory/Gateway changes, Identity
 - Prefer AgentCore Gateway and AgentCore Identity for managed credential handling where applicable.
 - Keep action/tool permissions least-privilege and scoped to the task.
 - Confirm logging, metrics, tracing, and CloudWatch visibility before production rollout.
+- Confirm CloudWatch Transaction Search / trace destination setup when relying on AgentCore observability.
 - Confirm whether the answer relies on code-based agent GA behavior or harness preview behavior.
 - Confirm whether the target region supports the specific AgentCore capability being recommended.
-- Require explicit approval before deployment, exposing tools, enabling browser/code execution, or changing memory persistence.
+- Require explicit approval before deployment, exposing tools, enabling browser/code execution, attaching filesystems, enabling payment flows, or changing memory persistence.
 
 ## Component risks
 
 - **Runtime:** wrong entrypoint, broad execution role, public network mode, missing logs, unbounded session lifetime.
-- **Memory:** PII retention, namespace leakage, actor/session mixups, memory poisoning, untested deletion/expiry behavior.
-- **Gateway/MCP tools:** overbroad tool access, raw bearer tokens, unsafe OpenAPI targets, excessive scopes, no tool audit trail.
+- **Memory:** PII retention, namespace leakage, actor/session mixups, metadata-filter bypass, memory poisoning, untested deletion/expiry behavior.
+- **Gateway/MCP tools:** overbroad tool access, raw bearer tokens, unsafe OpenAPI targets, excessive scopes, no tool audit trail, unsafe session reuse, ungoverned elicitation/sampling/streaming/log notifications.
 - **Identity:** unmanaged secrets, unclear credential provider, missing rotation, broad OAuth scopes, assuming SigV4 preserves end-user identity when official docs say it does not.
-- **Environment/skills:** assuming `--skill-path` uploads local folders, forgetting ECR/VPC/container prerequisites, or binding nonexistent in-container paths.
+- **Environment/skills/filesystems:** assuming `--skill-path` uploads local folders, forgetting ECR/VPC/container prerequisites, overbroad S3 Files/EFS mounts, path collisions, or binding nonexistent in-container paths.
 - **Policy:** creating Gateway tools without Cedar policy boundaries or clear principal/resource conditions.
 - **Browser:** browsing sensitive sites, recording exposure, egress risk, uncontrolled side effects.
 - **Code Interpreter:** data exfiltration, untrusted code, package/network risk, missing sandbox boundaries.
+- **Evaluations/optimization:** optimizing against unreviewed production traces, leaking prompt/tool data into eval datasets, promoting A/B winners without guardrail review.
+- **Registry:** publishing unreviewed agents/tools/skills, semantic search surfacing sensitive tools, unclear approval workflow.
+- **Payments:** preview maturity, wallet custody, spending limits, x402 endpoint trust, transaction auditability, refund/dispute handling.
 
 ## Evidence labels
 

package/skills/aws/aws-agentcore/references/workflow-and-output.md

@@ -16,29 +16,38 @@ Use this reference for full AgentCore implementation, deployment, or production-
    - Identity/credential flow
    - Observability/instrumentation
    - Browser or Code Interpreter tool usage
+   - Evaluations, batch evaluations, user simulation, optimization, or A/B testing
+   - Registry publishing/discovery/governance
+   - Payments / x402 / wallet-backed agent transactions
+   - Runtime or harness filesystem mounts
    - Policy/Cedar controls for Gateway tool access
 
 2. **Verify tooling and docs**
    - Check installed AgentCore CLI/toolkit version when local commands will run.
    - Check whether the user is on a code-based agent path or the harness preview path.
    - For new projects, default to the npm CLI package `@aws/agentcore` unless the user is intentionally staying on an older Python toolkit workflow.
-   - Prefer current official docs, Context7, or configured AgentCore MCP documentation tools.
+   - Prefer `AwsDocumentationMcpServer` for current official docs, then Context7 or configured AgentCore MCP documentation tools.
    - If AWS docs and starter-toolkit examples disagree, prefer the newer AWS devguide wording and call out the mismatch.
    - Treat bundled commands as examples until verified against local tooling.
-   - Confirm region support before recommending harness-specific workflows.
+   - Confirm region/API support before recommending AgentCore Runtime, Harness, Gateway, Memory, Evaluations, Browser, Code Interpreter, Payments, Registry, or Policy workflows.
 
 3. **Implement minimally**
    - Existing agents: wrap/adapt runtime entrypoint; do not scaffold over code.
    - New projects: prefer non-interactive generation with the recommended CLI only when project creation is requested.
    - Skills: treat `--skill-path` as a container/session filesystem reference, not a skill uploader.
+   - Filesystems: treat S3 Files/EFS mounts as data-perimeter resources with explicit path, lifecycle, and tenant-isolation decisions.
    - Memory/Gateway/Identity: create and test resources separately before wiring production flows.
-   - Gateway: pair tool onboarding with policy and identity decisions; do not stop at endpoint creation.
+   - Gateway: pair tool onboarding with policy, identity, session, streaming, elicitation, sampling, progress, and logging decisions; do not stop at endpoint creation.
    - Harness: call out preview status and identity propagation caveats if you recommend it.
+   - Evaluations: use batch evaluation/user simulation/A-B validation for quality-sensitive production changes.
+   - Registry: require publication, approval, access, and discovery governance before recommending broad catalog rollout.
+   - Payments: treat as preview; require spending limits, wallet/provider choice, transaction audit, and rollback/disable path.
 
 4. **Validate**
    - Run local invoke/test loop.
    - Confirm IAM role, network mode, environment variables, package dependencies, logs, metrics, tracing prerequisites, and rollback path.
    - Confirm which commands actually exist in the installed CLI before giving automation steps.
+   - Confirm CloudWatch Transaction Search or equivalent telemetry destination if the recommendation relies on AgentCore observability.
 
 ## Output contract
 

package/skills/aws/aws-api-edge-delivery-review/SKILL.md

@@ -4,8 +4,8 @@ description: Review AWS API and edge delivery posture across API Gateway, CloudF
 allowed-tools: Read Grep Glob
 metadata:
   author: "github: Raishin"
-  version: "0.1.2"
-  updated: "2026-05-05"
+  version: "0.1.4"
+  updated: "2026-06-02"
   category: networking
 ---
 
@@ -26,7 +26,7 @@ Use this skill for:
 
 ## Lean operating rules
 
-- Prefer `AwsDocumentationMcpServer` when available via `uvx awslabs.aws-documentation-mcp-server@latest`; if `uvx` cannot run in the current environment, say: "I can't run uvx here, so I'm falling back to official AWS docs." Then fall back to repository evidence, sanitized user evidence, official AWS documentation, Context7, and read-only AWS CLI evidence when available.
+- Prefer current AWS documentation tools for service behavior. Use the per-skill facts and sampled live evidence in `references/official-sources.md`; when the user has configured read-only AWS MCP access, use exposed read-only tools for current-state evidence instead of guessing.
 - Separate confirmed facts from inference. If state was not queried or shown, say so.
 - Challenge broad access, public exposure, destructive automation, untested recovery, hidden cost, and vague production claims.
 - Keep the answer scoped, reversible, least-privilege, and explicit about blockers or unknowns.
@@ -39,6 +39,10 @@ Load these only when needed:
 - [Workflow and output contract](references/workflow-and-output.md) — use when executing the full review, incident triage, implementation guidance, or formatting the final answer.
 - [Safety checklist](references/safety-checklist.md) — use before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.
 - [Official sources](references/official-sources.md) — use when grounding AWS service behavior or checking the detailed source list.
+- [API Gateway controls](references/api-gateway-controls.md) — use for API Gateway routes, stages, authorizers, throttling, quotas, logging, and resource policies.
+- [CloudFront origin protection](references/cloudfront-origin-protection.md) — use for distributions, origins, OAC/OAI, cache policies, TLS, and DNS/rollback design.
+- [WAF, Shield, and abuse controls](references/waf-shield-abuse-controls.md) — use for web ACLs, managed rules, rate-based rules, Bot Control, labels, Shield, and anti-DDoS posture.
+- [Observability and incident playbook](references/observability-incident-playbook.md) — use for 4xx/5xx, latency, throttling, WAF false-positive, origin, cache, or cost incidents.
 
 ## Response minimum
 

package/skills/aws/aws-api-edge-delivery-review/metadata.json

@@ -17,11 +17,16 @@
     "https://docs.aws.amazon.com/apigateway/latest/developerguide/security-best-practices.html",
     "https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html",
     "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html",
-    "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-awswaf.html"
+    "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html",
+    "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-cloudfront-to-s3-origin.html",
+    "https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html",
+    "https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups.html",
+    "https://docs.aws.amazon.com/waf/latest/developerguide/waf-anti-ddos-best-practices.html",
+    "https://docs.aws.amazon.com/waf/latest/developerguide/ddos-overview.html"
   ],
   "security_notes": "Do not approve public API or edge changes without auth, throttling, TLS, logging, WAF/origin protection where appropriate, sensitive-log controls, and rollback path.",
-  "last_verified": "2026-04-29",
+  "last_verified": "2026-06-02",
   "path": "skills/aws/aws-api-edge-delivery-review",
   "author": "github: Raishin",
-  "version": "0.1.2"
+  "version": "0.1.4"
 }

package/skills/aws/aws-api-edge-delivery-review/references/api-gateway-controls.md

@@ -0,0 +1,120 @@
+# API Gateway Control Guide
+
+Use this reference when the review scope includes API Gateway REST, HTTP, or WebSocket APIs, custom domains, authorizers, throttling, quotas, stages, resource policies, or API Gateway logging.
+
+## What people get wrong
+
+The lazy story is:
+
+> API Gateway is managed, so the API edge is safe by default.
+
+Wrong. API Gateway removes server management; it does not remove API abuse, auth, quota, logging, or data-exposure risk.
+
+Common bad assumptions:
+
+- A public API is acceptable because the backend is private.
+- JWT authorizer exists, so authorization is solved.
+- Account-level throttling is enough for per-tenant abuse.
+- CloudWatch metrics exist, so audit evidence exists.
+- CORS is a browser concern, not a security review item.
+- Stage variables, access logs, and mapping templates cannot leak sensitive data.
+
+## Officially grounded controls
+
+Current AWS documentation points API Gateway reviewers toward these control families:
+
+- IAM authorization, Lambda/JWT/Cognito authorizers, and resource policies for access control.
+- CloudWatch metrics/logs and access logging for observability.
+- CloudTrail for API management-plane audit activity.
+- AWS Config and Security Hub CSPM for configuration/security evidence.
+- Throttling and quotas to limit request rates and protect downstream systems.
+
+Treat those as required evidence categories, not optional polish.
+
+## Non-negotiable review checks
+
+### 1. Identify API type before giving guidance
+
+REST API, HTTP API, and WebSocket API do not expose the same controls or operational surfaces. Do not give one-size-fits-all recommendations.
+
+Capture:
+
+- API type and stage
+- custom domain and TLS policy
+- integration type and backend
+- authorizer type
+- resource policy, if any
+- usage plan/API key design, if any
+- throttling/quota settings
+- access-log format and destination
+
+### 2. Split authentication from authorization
+
+An authorizer answers “who is this?” or “is this token acceptable?”. It does not automatically prove per-route, per-tenant, or object-level authorization.
+
+Look for:
+
+- route/method authorization coverage
+- claims-to-permission mapping
+- tenant isolation checks
+- explicit deny paths
+- unauthenticated OPTIONS/CORS behavior
+- bypasses through alternate stages/domains
+
+### 3. Treat throttling as layered protection
+
+Review all relevant layers:
+
+- account-level throttles
+- stage/method throttles
+- usage plans and quotas
+- WAF rate-based rules
+- downstream service capacity
+- retry behavior from clients and integrations
+
+A single throttle setting is not an abuse-control strategy.
+
+### 4. Logs must be useful and safe
+
+Access logs should answer who/what/when/outcome without leaking secrets.
+
+Check for:
+
+- request ID / extended request ID
+- principal or anonymized tenant identifier
+- route/method/status/integration latency
+- WAF decision correlation where applicable
+- no bearer tokens, cookies, API keys, passwords, or PII payloads in logs
+- retention and KMS controls for log groups
+
+## Minimum safe workflow
+
+1. Classify API type, stage, custom domain, and backend integration.
+2. Enumerate all public routes and unauthenticated routes.
+3. Verify authorizer, resource policy, and route authorization coverage.
+4. Verify throttles, quotas, usage plans, and downstream capacity assumptions.
+5. Inspect access-log settings and log redaction posture.
+6. Check CloudTrail/Config/Security Hub evidence for management-plane and config drift.
+7. Identify rollback: stage variable, canary, deployment, DNS, or previous deployment ID.
+
+## Verification targets
+
+Use read-only evidence when available:
+
+- API Gateway API/stage/domain/authorizer/resource-policy descriptions
+- route/method authorization settings
+- stage access-log settings
+- usage plan and API key attachment where used
+- CloudWatch metrics: 4xx, 5xx, latency, integration latency, throttles
+- CloudTrail events for recent API/stage/domain changes
+
+## When to push back
+
+Push back if the design says:
+
+- “public for now, auth later”
+- “API keys are authentication”
+- “JWT means authorization is done”
+- “we do not need throttling because traffic is low”
+- “we log full requests for debugging”
+- “rollback is redeploying main”

package/skills/aws/aws-api-edge-delivery-review/references/cloudfront-origin-protection.md

@@ -0,0 +1,100 @@
+# CloudFront Origin Protection Guide
+
+Use this reference when the review scope includes CloudFront distributions, origins, cache behaviors, origin access control, TLS, custom headers, cache keys, origin request policies, or distribution rollback.
+
+## What people get wrong
+
+The naive story is:
+
+> CloudFront is in front, so the origin is protected.
+
+Wrong. CloudFront only protects the origin if the origin is configured to reject direct access and the cache/origin policies do not leak or amplify risk.
+
+Common bad assumptions:
+
+- S3 origin is private because CloudFront uses it.
+- Origin access identity and origin access control are interchangeable.
+- Viewer HTTPS is enough; origin HTTPS does not matter.
+- Forwarding all headers/cookies/query strings is safer because it is “complete”.
+- Cache invalidation is the rollback plan.
+- Custom origin headers are secrets.
+
+## Officially grounded controls
+
+Current AWS docs ground these CloudFront controls:
+
+- Origin Access Control for restricting S3 origins, including migration from legacy OAI and SSE-KMS permission considerations.
+- HTTPS viewer/origin policies for encrypted transport.
+- Custom origin headers for origin request shaping, with documented header restrictions.
+- Cache behavior, cache key, and origin request policy choices that affect correctness, privacy, and cost.
+- AWS WAF association for edge filtering and rule enforcement.
+
+## Non-negotiable review checks
+
+### 1. Prove the origin cannot be bypassed
+
+For S3 origins, verify bucket policy allows the CloudFront distribution/OAC path and denies unintended direct access.
+
+For custom origins, verify one or more controls:
+
+- origin only reachable from expected networks
+- secret header is not the only control unless risk accepted
+- ALB/security group/origin firewall rules restrict direct access
+- origin TLS certificate and hostname behavior are correct
+
+### 2. Cache keys are security boundaries
+
+Cache policies can leak tenant/user-specific responses if identity-bearing inputs are omitted from the cache key.
+
+Check:
+
+- Authorization/cookie/query/header forwarding
+- whether authenticated responses are cached
+- error response caching
+- compression and content negotiation
+- cache behavior path precedence
+
+### 3. TLS and domain posture are part of rollback
+
+Capture:
+
+- viewer protocol policy
+- minimum TLS protocol
+- certificate scope and expiration
+- alternate domain names
+- DNS cutover/rollback path
+
+### 4. Origin request controls can create data exposure
+
+Forwarding too much can expose cookies and auth headers to origins that do not need them. Forwarding too little can break authorization or cache correctness.
+
+## Minimum safe workflow
+
+1. Map viewer domain -> distribution -> behavior -> origin -> backend.
+2. Identify every origin and whether direct access is blocked.
+3. Review cache and origin request policies for sensitive variance.
+4. Verify TLS policy, certificate, and DNS ownership.
+5. Verify WAF association and logging posture.
+6. Define rollback: previous distribution config, DNS change, origin failover, or behavior revert.
+
+## Verification targets
+
+Use read-only evidence when available:
+
+- distribution config and status
+- cache behaviors and origin request/cache policies
+- OAC/OAI config and S3 bucket policy
+- origin protocol policy and custom headers
+- WAF web ACL association
+- standard or real-time log delivery
+- CloudWatch metrics and CloudFront 4xx/5xx/error-rate signals
+
+## When to push back
+
+Push back if the design says:
+
+- “the S3 bucket is public but hidden behind CloudFront”
+- “we forward everything to avoid bugs”
+- “custom header is our only origin protection”
+- “we can invalidate if something goes wrong”
+- “CloudFront is global so regional evidence is irrelevant” without explaining global-control-plane implications