@kensio/yulin 1.21.6 → 1.21.8

package/docs/services/organizations/README.md

@@ -1,18 +1,14 @@
 # Simulated Organizations
 
-Yulin simulates AWS Organizations service control policies. A test can find out that the
-organization around an account forbids something before a deployment does.
+Yulin simulates AWS Organizations service control policies (SCPs) and organization structure.
 
-A service control policy filters what an account's principals may do and grants nothing. Policies
-attach to the organization root, to an organizational unit, or to one account, and an account
-inherits every policy on the path down to it. Sim IAM evaluates them ahead of that account's
-identity and resource policies. An SCP therefore applies to a CloudFormation deployment, an
-intercepted SDK client, and a direct service call alike.
+An SCP limits permissions granted by identity and resource policies. Attach one to the organization
+root, an organizational unit or an account. An account inherits policies from every node on its path
+from the root. Simulated IAM applies them to direct calls, intercepted clients and CloudFormation.
 
 ## Attach a policy to an organizational unit
 
-A policy is usually attached to an organizational unit rather than to one account, and every account
-under that unit inherits it. Units nest, and the root sits above all of them.
+Create an organizational unit and attach an SCP to it. Accounts below the unit inherit the policy.
 
 ```typescript sim-organizations-organizational-unit
 /**
@@ -44,16 +40,13 @@ const decision = simAws.account("123456789012").iam().authorize({
 console.log(decision.value); // "ExplicitDeny"
 ```
 
-The policy hangs two levels above the account and still reaches it. `createOrganizationalUnit` takes
-a parent unit as its second argument, and leaves the unit under the root without one.
-`organizations.root()` is the node above everything, and a policy attached there covers every
-account in the organization.
+Pass a parent as the second argument to `createOrganizationalUnit` to nest units. With no parent, the
+new unit sits below `organizations.root()`.
 
 ## Every level has to allow the action
 
-An account is filtered by each node on the path from the root down to it, and each one has to allow
-an action on its own. A root allowing S3 and a unit allowing DynamoDB leave an account beneath them
-able to do neither.
+Every node on the path must allow the action. An allow at one level cannot supply an allow missing
+at another. A deny at any level rejects the request.
 
 ```typescript sim-organizations-every-level-allows
 /**
@@ -89,15 +82,12 @@ console.log(decision.value); // "ImplicitDeny"
 console.log(decision.serviceControlPolicy.unallowedLevels); // [ "Workloads" ]
 ```
 
-`unallowedLevels` names the nodes that allowed nothing matching. That is the part of a real SCP
-denial that takes longest to track down.
-
-A `Deny` at any level ends the request whatever another level allows.
+`unallowedLevels` identifies the nodes with no matching allow.
 
 ## The management account
 
-`setManagementAccount` names the account AWS exempts from every service control policy. That account
-is decided by its identity and resource policies alone, whatever is attached above it.
+Use `setManagementAccount` to exempt one account from SCP evaluation. Its identity and resource
+policies still apply.
 
 ```typescript sim-organizations-management-account
 /**
@@ -126,9 +116,8 @@ console.log(decision.serviceControlPolicy.isApplied); // false
 
 ## Attach a service control policy to an Account
 
-A policy attached straight to an account applies to that account alone. An organization spans
-accounts, so it belongs to the whole simulated environment and is reached as
-`simAws.organizations()`, not from an account scope.
+An SCP attached directly to an account applies only to that account. Organization state belongs to
+the whole `SimAws` instance and is available through `simAws.organizations()`.
 
 ```typescript sim-organizations-attach-scp
 /**
@@ -159,17 +148,15 @@ console.log(decision.serviceControlPolicy.isDenied); // true
 console.log(decision.serviceControlPolicy.denyStatements[0]?.Sid); // "DenyBucketCreation"
 ```
 
-The account also gets AWS's own `FullAWSAccess` policy, as it would in a real organization. One
-`Deny` statement therefore denies that one action and leaves the rest of the account working.
+New organization nodes receive the AWS-managed `FullAWSAccess` policy. A deny-list SCP can then
+block one action while leaving other actions allowed.
 
-An account with no policy attached to it stays outside the organization's reach, and its identity
-and resource policies decide its requests as they did before.
+An account outside the organization is unaffected by SCPs.
 
 ## Catch a deployment the policy denies
 
-Sim CloudFormation creates each resource through the owning service's command handler, and that
-handler authorizes. A deployment that names no principal is decided as the account root. An SCP
-applies to a member account's root the same way AWS does.
+CloudFormation creates resources through each service's authorized command path. A deployment with
+no caller runs as the account root, and SCPs apply to that root.
 
 ```typescript sim-organizations-scp-deployment
 /**
@@ -213,14 +200,13 @@ const failed = simAws
 console.log(failed?.status); // "CREATE_FAILED"
 ```
 
-The resource is left `CREATE_FAILED` and the deployment rejects. A test asserting that a stack
-deploys then fails on the policy, with the policy named in the message.
+When an SCP denies creation, the resource enters `CREATE_FAILED` and the deployment rejects. The
+error names the policy.
 
 ## Name the principal a deployment runs as
 
-An organization that denies its accounts' root principals is ordinary, and a deployment decided as
-the root fails under one. `caller` says which principal the resources are created as, and a
-statement conditioned on `aws:PrincipalArn` then has a deploy role to match against.
+Pass `caller` when the deployment should run as a role. SCP conditions on `aws:PrincipalArn` then
+evaluate against that role.
 
 ```typescript sim-organizations-scp-deploy-role
 /**
@@ -285,17 +271,15 @@ const stack = await simAws.cloudFormation().deployTemplate({
 console.log(stack.getResource("ReportsBucket")?.status); // "CREATE_COMPLETE"
 ```
 
-The Role is created before the policy is attached. Creating it afterwards is a call the policy
-denies the root, and the account root is who a bare `createRole` runs as.
+Create the role before attaching a policy that would deny the setup call.
 
 ## Name the caller the rest of a test reads as
 
-A deployment names its own principal. Every other call in the test still names none, and each one is
-the account root. Under a policy denying that root, a test reading back what a stack made is denied
-on every read.
+A deployment caller applies only to that deployment. Other calls still use the account root unless
+the simulation has a default caller.
 
-`defaultCaller` on `SimAws` says who those calls are. A test then reads the account as the person or
-role that would really be looking at it, and an explicit `caller` still wins wherever one is given.
+Set `defaultCaller` on `SimAws` to choose the principal for unattributed calls. An explicit `caller`
+still takes precedence.
 
 ```typescript sim-organizations-scp-default-caller
 /**
@@ -369,17 +353,13 @@ console.log(read.Parameter?.Value); // "reports-bucket"
 console.log(identity.Arn); // "arn:aws:iam::123456789012:role/Administrator"
 ```
 
-Setup runs before the policy is attached, for the same reason the deploy Role above does. The Role a
-simulation reads as has to exist and hold a policy, and creating it is itself a call.
-
-Naming a default caller says who an unattributed call comes from, and leaves the root's own identity
-access where it was. A test about root behaviour names `simAws.account().rootPrincipal` and gets the
-root. Under the policy above that call is denied, which is what the statement is written to do.
+Create and configure the default caller before attaching policies that would deny those setup calls.
+Pass `simAws.account().rootPrincipal` explicitly when a test needs to make a request as root.
 
 ## Write an allow list instead of a deny list
 
-`detachFullAwsAccess` takes AWS's own policy off an account. What remains has to allow an action
-for the account to be allowed it. That is an organization run as an allow list.
+Call `detachFullAwsAccess` to use an allow-list SCP. The remaining policies must explicitly allow an
+action.
 
 ```typescript sim-organizations-scp-allow-list
 /**
@@ -407,16 +387,13 @@ console.log(decision.denialReason);
 // "because no service control policy allows the s3:GetObject action"
 ```
 
-An account root holds unrestricted access in sim IAM, and this denies it anyway. That is what an
-SCP does in AWS, and it is why an allow list is worth writing in a test at all.
-
-Detaching `FullAWSAccess` on its own leaves the account holding no policy, and every action is then
-denied. AWS behaves the same way, and warns about it.
+SCPs still limit an account root. Removing `FullAWSAccess` without adding another allow policy denies
+every action.
 
 ## Deploy an organization from CloudFormation
 
-A template's `AWS::Organizations::*` resources build the organization they describe, so a stack
-already managing the org chart is the same one a test deploys.
+Simulated CloudFormation supports the organization, organizational unit, account and policy
+resource types.
 
 ```typescript sim-organizations-cloudformation
 /**
@@ -470,17 +447,13 @@ const decision = simAws.account("123456789012").iam().authorize({
 console.log(decision.value); // "ExplicitDeny"
 ```
 
-`Content` takes the policy document inline or as JSON text. `TargetIds` takes a list or a single
-value, and each entry names the root, a unit, or an Account. A policy reaches every target it names
-or none of them. A target this organization has never heard of fails the resource before anything is
-attached.
+`Content` accepts an object or JSON text. `TargetIds` accepts one target or a list of roots, units and
+accounts. An unknown target fails the resource before the policy is attached anywhere.
 
-A simulated environment has one organization from the start, so
-`AWS::Organizations::Organization` records the one already there rather than making another. It is
-worth declaring for `RootId`, which is what a unit hangs off.
+A `SimAws` instance starts with one organization. `AWS::Organizations::Organization` adopts it and
+exposes its `RootId`.
 
-`AWS::Organizations::Account` creates an Account with an id nobody chose, as AWS does. Read that id
-back with `Ref` or `Fn::GetAtt AccountId`.
+`AWS::Organizations::Account` generates an account ID. Read it with `Ref` or `Fn::GetAtt AccountId`.
 
 These are the properties read from each resource:
 
@@ -491,10 +464,8 @@ These are the properties read from each resource:
 | `AWS::Organizations::Account`            | `AccountName`, `Email`, `ParentIds`    | `Tags`, `RoleName`    |
 | `AWS::Organizations::Policy`             | `Name`, `Type`, `Content`, `TargetIds` | `Tags`, `Description` |
 
-Tearing the stack down takes its own policies off the nodes they were attached to, removes the
-units, and takes any Account the stack created back out of the organization. A node holding
-policies from more than one stack keeps the others. A unit that still holds something when it goes
-hands what it holds to its parent, so every Account keeps a path to the root.
+Stack teardown removes resources created by that stack. Policies from other stacks remain attached.
+Accounts and child units move to the deleted unit's parent.
 
 ## Reading a denial
 
@@ -510,21 +481,16 @@ sides, through `decision.serviceControlPolicy`:
 | `denyStatements`  | The matching `Deny` statements.                             |
 | `allowStatements` | The matching `Allow` statements.                            |
 
-`decision.denialReason` carries the wording AWS puts on the `AccessDenied` message, and every
-simulated service passes it through to the error it throws.
+`decision.denialReason` contains the text used by service access-denied errors.
 
-`simAws.organizations().serviceControlPoliciesFor(accountId)` returns the policies in force for an
-account, in the order they were evaluated, including `FullAWSAccess` where it is still attached.
+`serviceControlPoliciesFor(accountId)` returns the policies in evaluation order.
 
-`serviceControlPolicySetFor(accountId).levels` keeps the policies grouped by the node they hang on,
-root first. That grouping is what sim IAM evaluates.
+`serviceControlPolicySetFor(accountId).levels` groups policies by node, starting at the root.
 
-The flattened list is empty in three cases that behave differently. An account that was never named
-sits outside the organization and stays unrestricted. The management account is exempt and equally
-unrestricted. An account left holding no policy is denied everything. `applies` separates the last
-of those from the other two.
-`serviceControlPolicySetFor(accountId).applies` tells the two apart, and so does
-`decision.serviceControlPolicy.isApplied`.
+An empty policy list can mean that the account is outside the organization, is the management
+account or has no policies. The first two are exempt. The last is denied every action. Check
+`serviceControlPolicySetFor(accountId).applies` or `decision.serviceControlPolicy.isApplied` to
+distinguish them.
 
 ## Available functionality
 
@@ -567,7 +533,6 @@ Simulated Organizations supports:
 | Service-linked roles        | Evaluated like any other principal. AWS exempts a service-linked role from SCPs.                                                    |
 | Other policy types          | Resource control policies, declarative policies, tag policies, backup policies and AI services opt-out policies are not simulated.  |
 | The Organizations SDK       | `CreatePolicy`, `AttachPolicy`, `ListAccounts` and the rest of the API are not handled. Policies are attached through the accessor. |
-| CloudFormation              | `AWS::Organizations::Organization`, `::OrganizationalUnit`, `::Account` and `::Policy` are not created from a template.             |
 | Organization condition keys | `aws:PrincipalOrgID` and `aws:PrincipalOrgPaths` are not populated. A condition naming either fails to match.                       |
 | Service principals          | A request whose caller is a service principal or anonymous belongs to no Account and is subject to no policy.                       |
 | Condition operator coverage | The operators above are evaluated. Anything else fails closed and the statement holding it matches nothing.                         |

package/docs/services/personalize/README.md

@@ -1,17 +1,15 @@
 # Simulated Personalize
 
-Simulated Personalize holds the resources a recommendation is served from. No model is trained and
-no data is read, in the way simulated ACM issues certificates without producing real TLS
-certificates. A dataset group, a solution, a solution version and a campaign all exist, carry what
-the request gave them, and reach `ACTIVE` straight away.
+Yulin simulates the Personalize resources and API calls used to serve recommendations. It does not
+train a model or derive results from datasets. Tests declare the recommendations that a campaign or
+recommender should return. Created resources become `ACTIVE` immediately.
 
 Personalize-specific types are imported from the `@kensio/yulin/personalize` subpath.
 
 ## Building the chain to a campaign
 
-Every runtime recommendation names a campaign, and a campaign is the far end of a chain. The dataset
-group holds the data, the solution picks a recipe, the solution version is the trained model, and
-the campaign serves it.
+A campaign is built from a resource chain. A dataset group contains the datasets, a solution selects
+a recipe, a solution version represents the trained model, and a campaign serves that version.
 
 ```typescript sim-personalize-campaign-chain
 /**
@@ -73,9 +71,8 @@ expects.
 
 ## Recommendations from a campaign
 
-A campaign answers the runtime API from results declared against it. No model is fitted and no
-interaction history is held. A test says what one campaign recommends for one item, and the code
-under test makes the calls it would make against AWS.
+A campaign returns results declared during test setup. Application code still sends the same
+Personalize Runtime commands it sends to AWS.
 
 The two runtime operations live on `simAws.personalizeRuntime()`, and an intercepted
 `PersonalizeRuntimeClient` reaches the same place. They arrive from a separate SDK package
@@ -140,9 +137,8 @@ const recommended = await simAws.personalizeRuntime().getRecommendations(
 console.log(recommended.itemList?.map((item) => item.itemId).join(" "));
 ```
 
-Results are declared per campaign, through `recommendations()` and `rankings()`. A campaign serves
-one solution version trained on one recipe, and two campaigns in a dataset group answer the same
-entry differently.
+Declare results per campaign through `recommendations()` and `rankings()`. Two campaigns in the same
+dataset group can return different results for the same input.
 
 An item rule is read first where the request carries an item, then a user rule, then the default.
 That order follows the recipes. `aws-similar-items` requires an `itemId` and looks at no user, and
@@ -152,9 +148,8 @@ would have used. Matching is exact, with no pattern syntax.
 `numResults` cuts a declared list to length. A request no rule matches gets the campaign's default,
 and an empty `itemList` where no default is declared.
 
-An item is declared as an id on its own, or as an id with a score for a test to assert on. The
-number comes from the declaration, and a rule that leaves it out answers with an item carrying no
-score.
+Declare an item as an ID or as an ID with a score. An item declared without a score is returned
+without one.
 
 ```typescript sim-personalize-recommendation-scores
 /**
@@ -228,10 +223,8 @@ Runtime does.
 
 ## Datasets and schemas
 
-A dataset belongs to a dataset group and has one of five types. The dataset ARN carries the group
-and the type rather than the name the request gave, which is how real Personalize builds it. One
-dataset group therefore holds one dataset of each type, and two dataset groups can each hold an
-`INTERACTIONS` dataset without colliding.
+A dataset belongs to a dataset group and has one of five types. Its ARN contains the group and type,
+not the requested name. Each group can contain one dataset of each type.
 
 ```typescript sim-personalize-dataset
 /**
@@ -289,8 +282,8 @@ domain dataset group refuses them here too.
 
 ## Recording events
 
-An event tracker is where `PutEvents` sends item interactions. It is created against a dataset
-group and reports a tracking ID back, and every `PutEvents` names that ID.
+An event tracker records the item interactions sent through `PutEvents`. Create it for a dataset
+group, then pass its tracking ID to each request.
 
 ```typescript sim-personalize-event-tracker
 /**
@@ -464,10 +457,9 @@ console.log(group.domain);
 
 ## Recommenders and their use cases
 
-A recommender goes straight onto a Domain dataset group, for one of the ten use cases AWS trained.
-There is no solution and no solution version in between. `GetRecommendations` then names a
-`recommenderArn` where the custom path names a `campaignArn`, and results are declared against it
-through the same `recommendations()` rules.
+A recommender belongs directly to a domain dataset group and selects one of ten AWS use cases. It
+does not use a solution or solution version. Pass its ARN to `GetRecommendations` and declare its
+results with the same `recommendations()` API used for campaigns.
 
 ```typescript sim-personalize-recommender
 /**
@@ -525,9 +517,8 @@ Real Personalize trains for hours and retrains every seven days.
 
 ### The ten use cases
 
-The recipe ARN picks the use case, and the use case decides what a request has to carry. A request
-leaving out a parameter its use case requires is refused, which is what real Personalize does with
-it. That refusal is the part of the domain path worth simulating, and everything else here is state.
+The recipe ARN selects the use case. Each use case defines whether `itemId` and `userId` are
+required, optional, or unused. Requests missing a required parameter are rejected.
 
 | Use case                           | Recipe ARN suffix                              | `itemId` | `userId` |
 | ---------------------------------- | ---------------------------------------------- | -------- | -------- |
@@ -555,9 +546,6 @@ A parameter marked unused is ignored rather than matched on. A `Top picks for yo
 an `itemId` as well as its `userId` is answered from the user rule, since that is the tier real
 Personalize would have used. An optional one is matched where the request carries it.
 
-These are the requirements AWS documents against each use case. Both pages are worth reading before
-writing a request, since two of them differ from the e-commerce use case they otherwise mirror.
-
 ### Starting and stopping
 
 `StopRecommender` leaves the recommender in place and stops it serving. `GetRecommendations` against
@@ -602,8 +590,7 @@ and solutions gone. A group still holding one is reported as `ResourceInUseExcep
 
 `AWS::Personalize::DatasetGroup`, `AWS::Personalize::Schema`, `AWS::Personalize::Dataset`,
 `AWS::Personalize::Solution` and `AWS::Personalize::EventTracker` deploy into simulated Personalize.
-A project that declares them in CDK or CloudFormation can deploy the same template its application
-deploys, with no hand-written test setup.
+A project can deploy its synthesized template without hand-written Personalize setup.
 
 Each one goes through the ordinary create command. A template and an SDK caller get the same
 validation, the same refusals and the same ARN.
@@ -710,19 +697,16 @@ wiring one resource into another reads `Fn::GetAtt`. An event tracker publishes
 does not publish fails the deploy, since answering one would let a template deploy here and fail on
 AWS.
 
-### A stack stops at the solution
+### Resources without CloudFormation types
 
-CloudFormation has no `AWS::Personalize::Campaign` type and no `AWS::Personalize::Recommender` type.
-A campaign is what every runtime call names, and it is always created out of band through the SDK,
-the CLI or the console. A deployed stack gets as far as a solution and stops there. A test creates
-the solution version and the campaign itself, as the example above does. This is real Personalize
-behaviour and worth knowing before reading it as a gap in the simulation.
+CloudFormation has no `AWS::Personalize::Campaign` or `AWS::Personalize::Recommender` type. Create
+these resources through the SDK after deploying the stack, as the example above does.
 
 The domain path stops in the same place. `Domain` is a property of `AWS::Personalize::DatasetGroup`,
 and a template can declare a Domain dataset group. No `AWS::Personalize::Recommender` type exists to
 put a recommender on it.
 
-### Types a stack steps over
+### Skipped resource types
 
 `AWS::Personalize::BatchInferenceJob`, `AWS::Personalize::BatchSegmentJob`,
 `AWS::Personalize::DataDeletionJob`, `AWS::Personalize::MetricAttribution` and
@@ -763,9 +747,9 @@ console.log(group?.name, group?.status);
 
 ## Deleting resources
 
-Deletion follows real Personalize. A dataset group holding datasets, solutions or an event tracker
-is reported as `ResourceInUseException`, and so is a solution a campaign still deploys. Tear a chain
-down from the campaign end.
+Delete resources from the campaign end of the chain. A dataset group that still contains datasets,
+solutions, or an event tracker raises `ResourceInUseException`. A solution still used by a campaign
+raises the same error.
 
 Deleting an event tracker leaves the events it accepted recorded, as real Personalize leaves the
 interactions it wrote in the dataset behind it.

package/docs/services/rekognition/README.md

@@ -1,8 +1,8 @@
 # Simulated Rekognition
 
-Simulated Rekognition answers detection calls from results declared against images. A test can say
-which image fails moderation or holds a cat, with no image analysis happening. The bytes are never
-looked at.
+Yulin simulates Rekognition by returning results declared for an image name or content hash. It does
+not analyze the image. Tests can define labels, moderation results, faces, and face matches while
+application code uses the normal Rekognition commands.
 
 Rekognition-specific types are imported from the `@kensio/yulin/rekognition` subpath.
 
@@ -67,9 +67,8 @@ const detected = await simAws
 
 ## Detecting labels in an image
 
-`DetectLabels` answers with the objects, scenes and concepts an image is declared to hold. Each
-label carries the parents, aliases, categories and instances it was declared with, and no more. A
-label is reported as written.
+`DetectLabels` returns the objects, scenes, and concepts declared for an image. Each label contains
+only the parents, aliases, categories, and instances in its declaration.
 
 ```typescript sim-rekognition-detect-labels
 /**
@@ -131,19 +130,16 @@ console.log(detected.LabelModelVersion); // "3.0"
 Labels come back in descending order of confidence, which is the order real Rekognition reports them
 in. A declared instance with no confidence of its own takes its label's.
 
-An image no rule matches gets the built-in default result. That is the one `Mobile Phone` label from
-the example response in the AWS `DetectLabels` documentation, with the parent, alias, category and
-bounding box AWS documents it with. It is a real Rekognition response, though which labels an
-unconfigured image gets is a simulator convention rather than what AWS would return for it.
+An image that matches no rule gets a built-in `Mobile Phone` result based on the AWS
+`DetectLabels` example response. This default is a Yulin convention. AWS results depend on the image.
 
-A label name fills in nothing of its own. Declaring `Cat` with no parents reports `Cat` with no
-parents, and declaring a `Pizza` nobody has heard of reports `Pizza`. Yulin ships no general label
-ontology to check a name against or to expand one from.
+Yulin does not validate or expand general detection labels. Declaring `Cat` without parents returns
+`Cat` without parents.
 
 ## Detecting faces in an image
 
-`DetectFaces` answers with the faces an image is declared to hold. A face says where it is and what
-it looks like, and the response carries the attributes the request asked for.
+`DetectFaces` returns the faces declared for an image, including their positions and requested
+attributes.
 
 ```typescript sim-rekognition-detect-faces
 /**
@@ -204,8 +200,7 @@ Faces come back in the order they were declared. An attribute with no confidence
 the face's, and a face detected at 99.4 is reported as smiling at 99.4. A face declared with no
 confidence at all is detected at the built-in one.
 
-An image with nobody in it is `{ faces: [] }`. Two built-in results cover the counting a test
-usually does:
+Use `{ faces: [] }` for an image with no faces. Two built-in results cover common face-count tests:
 
 ```typescript
 import {
@@ -219,10 +214,8 @@ faces.onName("incoming/landscape.png", simRekognitionNoFaces);
 faces.onName("incoming/crowd.png", simRekognitionSeveralFaces);
 ```
 
-An image no rule matches gets the built-in default result. That is the one face from the example
-response in the AWS `DetectFaces` documentation, with the attributes and all thirty landmarks AWS
-documents it with. It is a real Rekognition response, though which face an unconfigured image gets is
-a simulator convention rather than what AWS would return for it.
+An image that matches no rule gets the face from the AWS `DetectFaces` example response, including
+its attributes and 30 landmarks. This default is a Yulin convention.
 
 ## Choosing the facial attributes
 
@@ -305,11 +298,10 @@ excludes the chin.
 
 ## Declaring results
 
-Results are declared per operation. `moderation()` holds the rules `DetectModerationLabels` answers
-from, `labels()` holds the rules `DetectLabels` answers from, `faces()` holds the rules
-`DetectFaces` answers from, and `faceMatches()` holds the rules `SearchFacesByImage` answers from.
-All four take the same three kinds of rule, being an exact S3 object name, an exact content hash, or
-anything at all.
+Declare results separately for each operation. Use `moderation()` for `DetectModerationLabels`,
+`labels()` for `DetectLabels`, `faces()` for `DetectFaces`, and `faceMatches()` for
+`SearchFacesByImage`. Each API accepts rules for an exact S3 object name, an exact content hash, or a
+default result.
 
 ```typescript sim-rekognition-moderation-rules
 /**
@@ -340,8 +332,8 @@ moderation.onHash(simRekognitionImageHash(fixture), {
 });
 ```
 
-A hash rule wins, then a name rule, then the default. Matching is exact, with no pattern syntax.
-Which rule applies never depends on how specific a pattern looks.
+Rules use exact matching. Hash rules take precedence over name rules, which take precedence over the
+default.
 
 A name is the `Name` in the request, the S3 object key. It is matched on its own, with the Bucket
 left out, so a rule for a key applies to that key in whichever Bucket the request names. An image
@@ -412,9 +404,8 @@ refused where the rule is written.
 
 ## Sample images
 
-Simulated Rekognition ships with five images whose hashes are already declared. A test uploads one
-through its own code and gets a known answer without registering anything. That is what makes an
-application generating its own object keys testable, since the test never has to know the key.
+Yulin includes five small images with predeclared hash rules. Application code can upload one under
+any object key and receive a known result without registering another rule.
 
 | Image                                              | Format | Detected as                                       |
 | -------------------------------------------------- | ------ | ------------------------------------------------- |
@@ -477,9 +468,8 @@ simAws
   .onHash(simRekognitionImageHash(sample), { labels: [] });
 ```
 
-The images are real 16 by 16 PNG and JPEG files, 1,909 bytes in total. The format check reads their
-magic bytes as it does for any other image. What they are pictures of decides nothing, since no
-image is looked at.
+The images are valid 16 by 16 PNG and JPEG files. Rekognition checks their file signatures but does
+not inspect their visual content.
 
 ## Moderation labels come back with their parents
 
@@ -772,7 +762,7 @@ ever. Filter the notification configuration by prefix or suffix, as this one doe
 
 ## Face collections
 
-A collection is what lets an application recognise the same person twice, where a detection answers what is in one image.
+A collection stores indexed faces so an application can search for the same person later.
 
 ```typescript sim-rekognition-collections
 /**
@@ -970,9 +960,7 @@ An image is read from a Bucket in another Account when that Bucket's policy allo
 real Rekognition reads across Accounts. A Bucket in another Region is refused, as real Rekognition
 reads only Buckets in its own Region.
 
-## Available functionality
-
-Simulated Rekognition currently supports:
+## Supported operations
 
 - `DetectModerationLabelsCommand`, `DetectLabelsCommand` and `DetectFacesCommand`, for an image
   supplied as `Image.Bytes` or as `Image.S3Object`