website/docs: blueprints: add a bit more info (#17704)

* website/docs: blueprints: add a bit more info

* this might be worth mentioning

* fix

* a bit more info

website/docs/customize/blueprints/v1/structure.md

@@ -31,10 +31,16 @@ context:
 entries:
     - # Model in app.model notation, possibilities are listed in the schema (required)
       model: authentik_flows.flow
-      # The state this object should be in (optional, can be "present", "created" or "absent")
-      # Present will keep the object in sync with its definition here, created will only ensure
-      # the object is created (and create it with the values given here), and "absent" will
-      # delete the object
+      # The state this object should be in (optional, can be "present", "created", "must_created", or "absent")
+      # - present (default): Creates the object if it doesn't exist, or updates the fields
+      #   specified in attrs if it does exist. This will overwrite any manual changes to those
+      #   fields, but fields not in attrs are left unchanged.
+      # - created: Creates the object if it doesn't exist, but never updates it afterward.
+      #   Manual changes are preserved.
+      # - must_created: Creates the object only if it doesn't exist. If the object already exists,
+      #   the blueprint will fail with a validation error.
+      # - absent: Deletes the object if it exists. This uses Django's .delete() which may
+      #   cascade to related objects (e.g., deleting a Flow will delete its FlowStageBindings).
       state: present
       # An optional list of boolean-like conditions. If all conditions match (or
       # no conditions are provided) the entry will be evaluated and acted upon
@@ -49,12 +55,25 @@ entries:
           - 2
           - !Condition [AND, ...] # See custom tags section
       # Key:value filters to uniquely identify this object (required)
+      # On creation: identifiers are merged with attrs to create the object
+      # On lookup: identifiers are used to find existing objects (using OR logic - see below)
+      # On update: only attrs are applied (if state is present)
+      #
+      # Multiple identifiers create an OR query: an object matches if ANY identifier matches.
+      # Example: identifiers with both slug and pk will match if either the slug OR pk matches.
+      #
+      # Dictionary values use Django's __contains query for JSON field matching:
+      # identifiers:
+      #     attributes: {foo: bar}  # Matches if attributes JSON contains {"foo": "bar"}
       identifiers:
           slug: initial-setup
       # Optional ID for use with !KeyOf
       id: flow
       # Attributes to set on the object. Only explicitly required settings should be stated
-      # as these values will override existing attributes
+      # as these values will override existing attributes.
+      # Note: When creating objects, both identifiers and attrs are merged together.
+      # On updates (state: present), only fields specified in attrs are modified - other
+      # fields (like auto-generated client_id/client_secret) are left unchanged.
       attrs:
           denied_action: message_continue
           designation: stage_configuration