chore(s3): updated documentation to provide better insights when using grant methods for the Bucket resource

packages/aws-cdk-lib/aws-s3/README.md

@@ -156,6 +156,22 @@ bucket.grantReadWrite(myLambda);
 Will give the Lambda's execution role permissions to read and write
 from the bucket.
 
+### Understanding "grant" Methods
+
+The S3 construct library provides several grant methods for the `Bucket` resource, but two of them have a special behavior. This two accept an `objectsKeyPattern` parameter to restrict granted permissions to specific resources:
+- `grantRead`
+- `grantReadWrite`
+
+When examining the synthesized policy, you'll notice it includes both your specified object key patterns and the bucket itself.
+This is by design. Some permissions (like `s3:ListBucket`) apply at the bucket level, while others (like `s3:GetObject`) apply to specific objects.
+
+Specifically, the [`s3:ListBucket` action operates on bucket resources](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html#amazons3-bucket)
+and requires the bucket ARN to work properly. This might be seen as a bug, giving the impression that more permissions were granted than the ones you intended, but the reality is that the policy does not ignore your `objectsKeyPattern` - object-specific actions like `s3:GetObject`
+will still be limited to the resources defined in your pattern.
+
+If you need to restrict the `s3:ListBucket` action to specific paths, you can add a `Condition` to your policy that limits the `objectsKeyPattern` to specific folders. For more details and examples, see the [AWS documentation on bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-folders).
+
+
 ## AWS Foundational Security Best Practices
 
 ### Enforcing SSL