@kensio/yulin 1.20.15 → 1.20.17

package/dist/service/sts/auth-z/assume-role-source-account-auth-z.js

@@ -1,4 +1,4 @@
-import { makeSimAwsAccountRootPrincipal } from "../../aws/caller/sim-aws-account-root-principal.js";
+import { simAwsCallerFor } from "../../aws/caller/sim-aws-resolved-caller.js";
 import { SimIamAccessDenied } from "../../iam/error/sim-iam.error.js";
 /**
  * Authorizes the caller's request to assume a role against IAM in the source
@@ -10,8 +10,8 @@ import { SimIamAccessDenied } from "../../iam/error/sim-iam.error.js";
  * trust authorization is a separate responsibility and must be performed even
  * when the source and target Account are the same.
  *
- * When no caller principal is supplied, Sim IAM applies its normal default
- * caller behavior for the source Account.
+ * When no caller principal is supplied, sim IAM applies its own default caller
+ * behaviour for the source Account.
  */
 export class AssumeRoleSourcePrincipalAuthorizer {
     sourceAccountId;
@@ -30,18 +30,19 @@ export class AssumeRoleSourcePrincipalAuthorizer {
      */
     authorize(input) {
         const sourceIam = this.iamResolver.iamForAccount(this.sourceAccountId);
-        const callerPrincipal = input.callerPrincipal ??
-            makeSimAwsAccountRootPrincipal(this.sourceAccountId);
+        // A request with no caller of its own is left for sim IAM to attribute.
+        // The simulation's default caller reaches this decision the way it reaches
+        // every other one.
         const decision = sourceIam.authorize({
             action: "sts:AssumeRole",
             resource: input.roleArn,
             region: this.regionName,
-            caller: callerPrincipal,
+            caller: input.caller === undefined ? undefined : simAwsCallerFor(input.caller),
         });
         if (decision.isExplicitDeny ||
             (decision.isImplicitDeny && Boolean(input.identityPolicyAllowRequired))) {
             throw new SimIamAccessDenied({
-                principal: callerPrincipal,
+                principal: decision.caller.principal,
                 action: "sts:AssumeRole",
                 resource: input.roleArn,
             });

package/dist/service/sts/auth-z/assume-role-target-auth-z.d.ts

@@ -1,4 +1,4 @@
-import type { SimAwsPrincipal } from "../../aws/caller/sim-aws-caller.js";
+import type { SimAwsResolvedCaller } from "../../aws/caller/sim-aws-caller-resolver.js";
 import type { SimAwsAccountId } from "../../aws/sim-aws-account.js";
 import type { AwsRegionName } from "../../aws/sim-aws-region.js";
 import type { SimIamAccountResolver } from "../../iam/registry/sim-iam-account-resolver.js";
@@ -17,7 +17,7 @@ type AssumeRoleTargetRole = SimGetRoleCommandOutput["Role"];
 interface AssumeRoleTargetAuthorizationInput {
     readonly roleArn: string;
     readonly target: IamRoleArnParts | SimAwsAccountId;
-    readonly caller: SimAwsPrincipal;
+    readonly caller: SimAwsResolvedCaller;
     readonly conditionContext?: Readonly<Record<string, SimIamConditionValue>> | undefined;
 }
 interface AssumeRoleTargetAuthorization {

package/dist/service/sts/auth-z/assume-role-trust-policy-authorizer.d.ts

@@ -1,4 +1,4 @@
-import type { SimAwsPrincipal } from "../../aws/caller/sim-aws-caller.js";
+import type { SimAwsResolvedCaller } from "../../aws/caller/sim-aws-caller-resolver.js";
 import type { AwsRegionName } from "../../aws/sim-aws-region.js";
 import type { SimGetRoleCommandOutput } from "../../iam/command/role/get-role/get-role.command.js";
 import type { SimIamConditionValue } from "../../iam/policy/sim-iam-policy.js";
@@ -14,7 +14,7 @@ interface AssumeRoleTrustPolicyAuthorizationInput {
      * target Account's service control policies can be conditioned on.
      */
     readonly region?: AwsRegionName | undefined;
-    readonly caller: SimAwsPrincipal;
+    readonly caller: SimAwsResolvedCaller;
     readonly conditionContext?: Readonly<Record<string, SimIamConditionValue>> | undefined;
 }
 export interface AssumeRoleTrustPolicyAuthorization {
@@ -46,5 +46,9 @@ export declare class AssumeRoleTrustPolicyAuthorizer {
      * no trust-policy statement grants access, even if no explicit Deny matched.
      */
     authorize(input: AssumeRoleTrustPolicyAuthorizationInput): AssumeRoleTrustPolicyAuthorization;
+    /**
+     * Refuse the request as the caller that made it.
+     */
+    private refuse;
 }
 export {};

package/dist/service/sts/auth-z/assume-role-trust-policy-authorizer.js

@@ -1,4 +1,5 @@
 import { jsonParse } from "../../../util/type-guard/json.js";
+import { simAwsCallerFor } from "../../aws/caller/sim-aws-resolved-caller.js";
 import { SimIamAccessDenied } from "../../iam/error/sim-iam.error.js";
 import { AssumeRoleTrustGrantClassifier } from "./assume-role-trust-grant-classifier.js";
 /**
@@ -27,18 +28,14 @@ export class AssumeRoleTrustPolicyAuthorizer {
      */
     authorize(input) {
         if (input.role.AssumeRolePolicyDocument === undefined) {
-            throw new SimIamAccessDenied({
-                principal: input.caller,
-                action: "sts:AssumeRole",
-                resource: input.roleArn,
-            });
+            this.refuse(input);
         }
         const trustPolicy = jsonParse(input.role.AssumeRolePolicyDocument);
         const decision = input.targetIam.authorize({
             action: "sts:AssumeRole",
             resource: input.roleArn,
             region: input.region,
-            caller: input.caller,
+            caller: simAwsCallerFor(input.caller),
             conditionContext: input.conditionContext,
             resourcePolicies: [
                 {
@@ -50,15 +47,21 @@ export class AssumeRoleTrustPolicyAuthorizer {
             ],
         });
         if (decision.isDenied || !decision.isAllowedByTrustPolicy) {
-            throw new SimIamAccessDenied({
-                principal: input.caller,
-                action: "sts:AssumeRole",
-                resource: input.roleArn,
-            });
+            this.refuse(input);
         }
         return {
             decision,
             isDirectPrincipalGrant: this.trustGrantClassifier.hasDirectPrincipalGrant(decision.trustAllowStatements),
         };
     }
+    /**
+     * Refuse the request as the caller that made it.
+     */
+    refuse(input) {
+        throw new SimIamAccessDenied({
+            principal: input.caller.principal,
+            action: "sts:AssumeRole",
+            resource: input.roleArn,
+        });
+    }
 }

package/dist/service/sts/command/assume-role/assume-role.handler.d.ts

@@ -4,7 +4,8 @@ import type { SimAssumeRoleCommand, SimAssumeRoleCommandOutput } from "./assume-
 import { type BackgroundScheduler } from "../../../../util/background/background.js";
 import type { SimAwsAccountId } from "../../../aws/sim-aws-account.js";
 import type { AwsRegionName } from "../../../aws/sim-aws-region.js";
-import type { SimAwsCaller } from "../../../aws/caller/sim-aws-caller.js";
+import type { SimAwsCaller, SimAwsDefaultCaller } from "../../../aws/caller/sim-aws-caller.js";
+import type { SimAwsAmbientCaller } from "../../../aws/caller/sim-aws-ambient-caller.js";
 interface AssumeRoleCommandHandlerProperties {
     readonly sourceAccountId: SimAwsAccountId;
     /**
@@ -13,6 +14,14 @@ interface AssumeRoleCommandHandlerProperties {
     readonly regionName: AwsRegionName;
     readonly iamResolver: SimIamAccountResolver;
     readonly background?: BackgroundScheduler;
+    /**
+     * The caller this simulation attributes a request naming none to.
+     */
+    readonly defaultCaller?: SimAwsDefaultCaller | undefined;
+    /**
+     * Where a request naming no caller looks before the default.
+     */
+    readonly ambientCaller?: SimAwsAmbientCaller | undefined;
 }
 /**
  * STS AssumeRoleCommand handler.

package/dist/service/sts/command/assume-role/assume-role.handler.js

@@ -16,7 +16,7 @@ import { AssumeRoleAuthorizationCoordinator } from "../../auth-z/assume-role-aut
  */
 export class AssumeRoleCommandHandler {
     background;
-    callerResolver = new SimAwsCallerResolver();
+    callerResolver;
     requestParser = new SimStsAssumeRoleRequestParser();
     authorizationCoordinator;
     sessionCreator;
@@ -25,6 +25,10 @@ export class AssumeRoleCommandHandler {
         const { sourceAccountId, regionName, iamResolver, background = new BackgroundTasks(), } = properties;
         this.sourceAccountId = sourceAccountId;
         this.background = background;
+        this.callerResolver = new SimAwsCallerResolver({
+            defaultCaller: properties.defaultCaller,
+            ambientCaller: properties.ambientCaller,
+        });
         this.authorizationCoordinator = new AssumeRoleAuthorizationCoordinator({
             sourceAccountId,
             iamResolver,
@@ -56,7 +60,7 @@ export class AssumeRoleCommandHandler {
         const role = await this.authorizationCoordinator.authorize({
             roleArn: request.roleArn,
             roleArnParts: request.roleArnParts,
-            caller: caller.principal,
+            caller,
             conditionContext: request.conditionContext,
         });
         return this.sessionCreator.create({

package/dist/service/sts/command/get-caller-identity/get-caller-identity.handler.d.ts

@@ -1,11 +1,20 @@
 import type { CommandHandler } from "../../../../command/command-handler.js";
-import type { SimAwsCaller } from "../../../aws/caller/sim-aws-caller.js";
+import type { SimAwsCaller, SimAwsDefaultCaller } from "../../../aws/caller/sim-aws-caller.js";
+import type { SimAwsAmbientCaller } from "../../../aws/caller/sim-aws-ambient-caller.js";
 import type { SimAwsAccountId } from "../../../aws/sim-aws-account.js";
 import type { SimIamAccountResolver } from "../../../iam/registry/sim-iam-account-resolver.js";
 import type { SimGetCallerIdentityCommand, SimGetCallerIdentityCommandOutput } from "./get-caller-identity.command.js";
 interface GetCallerIdentityCommandHandlerProperties {
     readonly sourceAccountId: SimAwsAccountId;
     readonly iamResolver: SimIamAccountResolver;
+    /**
+     * The caller this simulation attributes a request naming none to.
+     */
+    readonly defaultCaller?: SimAwsDefaultCaller | undefined;
+    /**
+     * Where a request naming no caller looks before the default.
+     */
+    readonly ambientCaller?: SimAwsAmbientCaller | undefined;
 }
 /**
  * Simulated STS GetCallerIdentity handler.

package/dist/service/sts/command/get-caller-identity/get-caller-identity.handler.js

@@ -13,12 +13,16 @@ import { simStsCallerUserId } from "./sim-sts-caller-user-id.js";
  * https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sts/command/GetCallerIdentityCommand/
  */
 export class GetCallerIdentityCommandHandler {
-    callerResolver = new SimAwsCallerResolver();
+    callerResolver;
     sourceAccountId;
     iamResolver;
     constructor(properties) {
         this.sourceAccountId = properties.sourceAccountId;
         this.iamResolver = properties.iamResolver;
+        this.callerResolver = new SimAwsCallerResolver({
+            defaultCaller: properties.defaultCaller,
+            ambientCaller: properties.ambientCaller,
+        });
     }
     /**
      * Report the identity behind this request.

package/dist/service/sts/service-role/sim-service-role.js

@@ -1,3 +1,4 @@
+import { simAwsResolvedCallerOf } from "../../aws/caller/sim-aws-resolved-caller.js";
 import { SimIamAccessDenied } from "../../iam/error/sim-iam.error.js";
 import { AssumeRoleTrustPolicyAuthorizer } from "../auth-z/assume-role-trust-policy-authorizer.js";
 import { simServiceRoleConditionContext, } from "./sim-service-role-source.js";
@@ -25,7 +26,10 @@ export async function assumeSimServiceRole(assumption) {
             role,
             targetIam: iam,
             region: scope.accountRegionScope.regionName,
-            caller: { kind: "service", service: servicePrincipal },
+            caller: simAwsResolvedCallerOf({
+                kind: "service",
+                service: servicePrincipal,
+            }),
             conditionContext: simServiceRoleConditionContext(source),
         });
     }

package/dist/service/sts/sim-sts.d.ts

@@ -3,12 +3,27 @@ import type { SimIamAccountResolver } from "../iam/registry/sim-iam-account-reso
 import type { SimAssumeRoleCommand, SimAssumeRoleCommandOutput } from "./command/assume-role/assume-role.command.js";
 import type { SimGetCallerIdentityCommand, SimGetCallerIdentityCommandOutput } from "./command/get-caller-identity/get-caller-identity.command.js";
 import type { SimAwsAccountRegionScope } from "../aws/sim-aws-account-region-scope.js";
-import type { SimAwsCaller } from "../aws/caller/sim-aws-caller.js";
+import type { SimAwsCaller, SimAwsDefaultCaller } from "../aws/caller/sim-aws-caller.js";
+import type { SimAwsAmbientCaller } from "../aws/caller/sim-aws-ambient-caller.js";
 import type { SimSdkCommandRouter } from "../../sdk/index.js";
 interface SimStsProperties {
     readonly accountRegionScope?: SimAwsAccountRegionScope;
     readonly iamResolver?: SimIamAccountResolver;
     readonly background?: BackgroundScheduler;
+    /**
+     * The caller this simulation attributes a request naming none to.
+     *
+     * Left out, such a request is the source Account's root principal, which is
+     * the identity GetCallerIdentity then reports.
+     */
+    readonly defaultCaller?: SimAwsDefaultCaller | undefined;
+    /**
+     * Where a request naming no caller looks before the default.
+     *
+     * A run-as block decides who the requests inside it are, so an unattributed
+     * GetCallerIdentity in one reports the caller that block named.
+     */
+    readonly ambientCaller?: SimAwsAmbientCaller | undefined;
 }
 /**
  * Simulated AWS Security Token Service.
@@ -21,6 +36,8 @@ export declare class SimSts {
     private readonly accountRegionScope;
     private readonly background;
     private readonly iamResolver;
+    private readonly defaultCaller?;
+    private readonly ambientCaller?;
     private readonly sdkRouter;
     constructor(properties?: SimStsProperties);
     /**

package/dist/service/sts/sim-sts.js

@@ -15,12 +15,16 @@ export class SimSts {
     accountRegionScope;
     background;
     iamResolver;
+    defaultCaller;
+    ambientCaller;
     sdkRouter = new SimStsSdkCommandRouter(this);
     constructor(properties = {}) {
         this.accountRegionScope =
             properties.accountRegionScope ?? simAwsAccountRegionScopeFactory.make();
         this.iamResolver = properties.iamResolver ?? new SimIamRegistry();
         this.background = properties.background ?? new BackgroundTasks();
+        this.defaultCaller = properties.defaultCaller;
+        this.ambientCaller = properties.ambientCaller;
     }
     /**
      * Handle an AssumeRoleCommand from the SDK.
@@ -31,6 +35,8 @@ export class SimSts {
             regionName: this.accountRegionScope.regionName,
             iamResolver: this.iamResolver,
             background: this.background,
+            defaultCaller: this.defaultCaller,
+            ambientCaller: this.ambientCaller,
         });
         return await handler.handle(command, options);
     }
@@ -41,6 +47,8 @@ export class SimSts {
         const handler = new GetCallerIdentityCommandHandler({
             sourceAccountId: this.accountRegionScope.accountId,
             iamResolver: this.iamResolver,
+            defaultCaller: this.defaultCaller,
+            ambientCaller: this.ambientCaller,
         });
         return await handler.handle(command, options);
     }

package/dist/util/memo/bounded-memo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Memoization cache holding a bounded number of values.
+ *
+ * The bound stops a long-running process accumulating entries without limit.
+ * Which values survive it matters little. A caller gets the same value back
+ * either way, and an evicted one costs another call to the factory that made
+ * it.
+ *
+ * Eviction is by insertion order, and a value read again stays where it is. A
+ * memo worth bounding is one whose reads are hot, and reordering the cache on
+ * every read costs more than the occasional recomputation it saves.
+ *
+ * A cached value has to be something (undefined stands for a key the cache is
+ * missing). A hit then costs one map lookup.
+ */
+export declare class BoundedMemo<T extends NonNullable<unknown>> {
+    private readonly limit;
+    private readonly cache;
+    /**
+     * Hold up to `limit` values, dropping the oldest to make room past that.
+     */
+    constructor(limit: number);
+    /**
+     * Returns the cached value for the given key, or creates and caches it using
+     * `factory`.
+     */
+    getOrCreate<V extends T>(key: PropertyKey, factory: () => V): V;
+    /**
+     * Returns whether the cache is currently holding `key`.
+     */
+    has(key: PropertyKey): boolean;
+    /**
+     * Drop what was cached first, until the cache is back within its limit.
+     */
+    private evictOverflow;
+}

package/dist/util/memo/bounded-memo.js

@@ -0,0 +1,58 @@
+/**
+ * Memoization cache holding a bounded number of values.
+ *
+ * The bound stops a long-running process accumulating entries without limit.
+ * Which values survive it matters little. A caller gets the same value back
+ * either way, and an evicted one costs another call to the factory that made
+ * it.
+ *
+ * Eviction is by insertion order, and a value read again stays where it is. A
+ * memo worth bounding is one whose reads are hot, and reordering the cache on
+ * every read costs more than the occasional recomputation it saves.
+ *
+ * A cached value has to be something (undefined stands for a key the cache is
+ * missing). A hit then costs one map lookup.
+ */
+export class BoundedMemo {
+    limit;
+    cache = new Map();
+    /**
+     * Hold up to `limit` values, dropping the oldest to make room past that.
+     */
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /**
+     * Returns the cached value for the given key, or creates and caches it using
+     * `factory`.
+     */
+    getOrCreate(key, factory) {
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = factory();
+        this.cache.set(key, value);
+        this.evictOverflow();
+        return value;
+    }
+    /**
+     * Returns whether the cache is currently holding `key`.
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Drop what was cached first, until the cache is back within its limit.
+     */
+    evictOverflow() {
+        while (this.cache.size > this.limit) {
+            const oldest = this.cache.keys().next();
+            /* v8 ignore next 3 -- a cache over its limit has a first key */
+            if (oldest.done === true) {
+                return;
+            }
+            this.cache.delete(oldest.value);
+        }
+    }
+}

package/docs/README.md

@@ -0,0 +1,54 @@
+# Simulated AWS usage documentation
+
+This directory contains area-specific documentation for Yulin. Each page explains the simulated
+behaviour and includes example code that can be copied into tests or local development scripts.
+
+## Service documentation
+
+- [ACM](https://yulinsim.dev/services/acm/ "Simulated ACM usage docs")
+- [API Gateway HTTP APIs](https://yulinsim.dev/services/apigatewayv2/ "Simulated API Gateway HTTP API usage docs")
+- [API Gateway REST APIs](https://yulinsim.dev/services/apigateway/ "Simulated API Gateway REST API usage docs")
+- [Athena](https://yulinsim.dev/services/athena/ "Simulated Amazon Athena usage docs")
+- [Bedrock](https://yulinsim.dev/services/bedrock/ "Simulated Amazon Bedrock usage docs")
+- [CloudFormation](https://yulinsim.dev/services/cloudformation/ "Simulated CloudFormation usage docs")
+- [CloudFront](https://yulinsim.dev/services/cloudfront/ "Simulated CloudFront usage docs")
+- [CloudWatch metrics](https://yulinsim.dev/services/cloudwatch/ "Simulated CloudWatch metrics usage docs")
+- [Cognito user pools](https://yulinsim.dev/services/cognito/ "Simulated Cognito user pools usage docs")
+- [DynamoDB](https://yulinsim.dev/services/dynamodb/ "Simulated DynamoDB usage docs")
+- [ECR](https://yulinsim.dev/services/ecr/ "Simulated ECR usage docs")
+- [ECS](https://yulinsim.dev/services/ecs/ "Simulated ECS usage docs")
+- [Elastic Load Balancing](https://yulinsim.dev/services/elbv2/ "Simulated Application Load Balancer usage docs")
+- [EventBridge](https://yulinsim.dev/services/eventbridge/ "Simulated EventBridge usage docs")
+- [Glue](https://yulinsim.dev/services/glue/ "Simulated Glue Data Catalog usage docs")
+- [IAM](https://yulinsim.dev/services/iam/ "Simulated IAM usage docs")
+- [Kinesis Data Firehose](https://yulinsim.dev/services/firehose/ "Simulated Kinesis Data Firehose usage docs")
+- [Kinesis Data Streams](https://yulinsim.dev/services/kinesis/ "Simulated Kinesis Data Streams usage docs")
+- [KMS](https://yulinsim.dev/services/kms/ "Simulated KMS usage docs")
+- [Lambda](https://yulinsim.dev/services/lambda/ "Simulated Lambda usage docs")
+- [CloudWatch Logs](https://yulinsim.dev/services/logs/ "Simulated CloudWatch Logs usage docs")
+- [Organizations](https://yulinsim.dev/services/organizations/ "Simulated Organizations service control policies usage docs")
+- [Personalize](https://yulinsim.dev/services/personalize/ "Simulated Amazon Personalize usage docs")
+- [Rekognition](https://yulinsim.dev/services/rekognition/ "Simulated Rekognition usage docs")
+- [Route53](https://yulinsim.dev/services/route53/ "Simulated Route53 usage docs")
+- [S3](https://yulinsim.dev/services/s3/ "Simulated S3 usage docs")
+- [Scheduler](https://yulinsim.dev/services/scheduler/ "Simulated EventBridge Scheduler usage docs")
+- [Secrets Manager](https://yulinsim.dev/services/secretsmanager/ "Simulated Secrets Manager usage docs")
+- [SES](https://yulinsim.dev/services/ses/ "Simulated SES usage docs")
+- [SNS](https://yulinsim.dev/services/sns/ "Simulated SNS usage docs")
+- [SQS](https://yulinsim.dev/services/sqs/ "Simulated SQS usage docs")
+- [SSM Parameter Store](https://yulinsim.dev/services/ssm/ "Simulated SSM Parameter Store usage docs")
+- [Step Functions](https://yulinsim.dev/services/stepfunctions/ "Simulated Step Functions usage docs")
+- [STS](https://yulinsim.dev/services/sts/ "Simulated STS usage docs")
+- [WAFv2](https://yulinsim.dev/services/wafv2/ "Simulated WAFv2 usage docs")
+
+## Feature documentation
+
+- [AI skill](https://yulinsim.dev/ai-skill/ "Yulin AI skill usage docs")
+- [The AWS CLI](https://yulinsim.dev/cli/ "The AWS CLI against simulated AWS usage docs")
+- [AWS SDK interception](https://yulinsim.dev/sdk/ "Simulated AWS SDK usage docs")
+- [Event factories](https://yulinsim.dev/factories/ "Test factories for AWS event shapes usage docs")
+- [Linting CloudFront Functions JS2](https://yulinsim.dev/lint/ "CloudFront Functions JS2 lint config usage docs")
+- [Non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/ "Dependencies Yulin does not simulate usage docs")
+- [Serving on localhost](https://yulinsim.dev/serve/ "Serving simulated AWS on localhost usage docs")
+- [Simulated time](https://yulinsim.dev/time/ "Simulated time usage docs")
+- [Terraform](https://yulinsim.dev/terraform/ "Deploying Terraform into simulated AWS usage docs")

package/docs/ai-skill/README.md

@@ -0,0 +1,69 @@
+# AI skill
+
+Yulin has an AI skill that teaches a coding agent how to test AWS code with the simulator well. It
+is `yulin-aws-simulation`, a `SKILL.md` written to the
+[Agent Skills specification](https://agentskills.io/specification) and installable into Claude Code,
+Codex CLI, Cursor, VS Code and anything else that reads one. It covers the part that lives outside
+the API.
+
+These docs and the skill answer different questions. A page here says what a simulated service does
+and what its commands take. The skill says what to do with that. An AI agent reaching for Yulin
+without it tends to build a harness around the simulator, leave hand-rolled stubs in place beside
+it, or write an `instanceof` check against an SDK exception class that passes in production and
+fails against the simulation.
+
+## Install
+
+```bash
+npx @kensio/skills add yulin-aws-simulation
+```
+
+That copies the skill into `.agents/skills/`, the directory Codex CLI, Cursor, VS Code and Gemini
+CLI read. `--agent claude` puts it in `.claude/skills/`, and `--user` installs it under your home
+directory for every project.
+
+As a Claude Code plugin:
+
+```bash
+claude plugin marketplace add KensioSoftware/kensio.ai
+claude plugin install yulin-aws-simulation@kensio
+```
+
+It is also on npm as `@kensio/yulin-aws-simulation`, and every
+[kensio.ai release](https://github.com/KensioSoftware/kensio.ai/releases) carries it as a zip for a
+machine with no registry reach.
+
+## What it covers
+
+- Using `SimAws` and `SimSdk` directly, and spotting the helper class or `setupSimulatedAws()`
+  wrapper that starts to grow around them.
+- One synthesized CDK template behind the tests, the dev server and production, deployed with
+  `deployTemplateFile` or `deployCdkOut`.
+- When to register a resource at a chosen id, and when to deploy the stack that creates it.
+- Interception over hand-rolled stubs, down to the requests a fake accepts and the simulation
+  refuses.
+- Freezing the clock, then advancing it on purpose.
+- Assertions that read the simulation back.
+- Why service errors match by `name` and not by `instanceof`.
+- Deploying an expensive stack once per test file.
+- Running a handler as a real simulated Lambda, under its execution role, its declared environment
+  and its own log group.
+- Refusals as a feature, and gaps raised upstream.
+
+## Reading the API alongside it
+
+The skill sends the AI agent to these docs for anything API-shaped, and
+[llms.txt](https://yulinsim.dev/llms.txt) is the index it uses. Every page here is available as
+plain markdown by appending `llms.txt` to its URL, one file per guide and one per simulated service.
+That index works with or without the skill installed.
+
+The same pages ship inside the package. An installed project holds them under
+`node_modules/@kensio/yulin/docs/`, indexed by `node_modules/@kensio/yulin/llms.txt`, and they
+document the version in that package rather than the current release. An agent with no network
+reach has them, and so does one working on a project held a few versions back. Ripgrep and most
+editor search skip `node_modules` by default. An agent finds these files when something names the
+path for it.
+
+The skill lives at
+[kensio.ai/skills/yulin-aws-simulation](https://kensio.ai/skills/yulin-aws-simulation), versioned
+separately from Yulin and licensed Apache-2.0.