Deployment to K8s: document S3PolicyBinding kind: Bucket subjects

Deployment-to-Kubernetes-and-Minikube.md

@@ -138,7 +138,7 @@ commands:
 | `S3Identity` | An IAM user |
 | `S3Credentials` | An access key pair for an identity, mirrored into a Kubernetes `Secret` (generated or adopted) |
 | `S3Policy` | An IAM policy (structured statements or a raw AWS-style document) |
-| `S3PolicyBinding` | Attaches a policy to a set of identities |
+| `S3PolicyBinding` | Attaches a policy to a set of identities, or stores it as a bucket policy when a subject is a `Bucket` |
 
 For example, a user, a key pair stored in a Secret, a bucket, and a policy
 attachment:
@@ -178,6 +178,19 @@ spec:
     - { kind: S3Identity, name: alice }
 ```
 
+A `kind: Bucket` subject instead stores the bound policy's document as that
+bucket's bucket policy, which the S3 gateway evaluates on every request to the
+bucket — including `Condition` clauses such as `ForAnyValue:StringEquals` on
+`jwt:groups` for authorization driven by multi-valued OIDC claims. The
+`S3Policy` must carry a raw `spec.policyDocument` with a `Principal` per
+statement (a *resource* policy, not an identity policy); its `Resource` entries
+may name any of the bound buckets, so one document can be shared across a whole
+project's buckets. A bucket holds a single policy document — when two bindings
+claim the same bucket the older wins and the loser reports
+`reason: BucketConflict`; `status.attachedBuckets` lists the buckets a binding
+manages, and `reclaimPolicy: Retain` leaves the document in place when the CR is
+deleted.
+
 These resources require the cluster's embedded IAM service to allow writes — see
 the [IAM write access with persistence](#iam-configuration-example) example above.
 For the full field reference, see the