chore: document organization settings flows

Author: jonas-jonas

docs/kratos/organizations/organizations.mdx

@@ -261,6 +261,37 @@ your system but need the identity to be created in Ory Network first, before the
 To achieve this, set the `organization_id` property to the ID of the created organization in the identity, either when creating
 the identity, or by updating the identity's data using the Ory APIs.
 
+## Bind an identity to an organization through the settings flow
+
+A signed-in user can join an organization by linking one of its SSO connections through the
+[settings flow](../self-service/flows/user-settings.mdx). When the user completes the link, Ory sets the identity's
+`organization_id` to that organization. There is no need to sign the user out or to pre-provision the identity.
+
+To scope a settings flow to an organization, pass the organization ID in the `organization` query parameter when you initialize
+the flow:
+
+```
+https://$PROJECT_SLUG.projects.oryapis.com/self-service/settings/browser?organization=$ORGANIZATION_ID
+```
+
+The same parameter works for the API (native) flow at `/self-service/settings/api`.
+
+An organization-scoped settings flow behaves differently from a regular settings flow:
+
+- The flow returns link nodes only for the organization's OIDC and SAML connections. Other settings methods, such as password or
+  social sign-in, are not part of the flow.
+- Connections the identity has already linked render as disabled. The organization owns the binding, so the user cannot remove it.
+- Submitting a link starts authentication with the organization's identity provider. On the callback, Ory links the credential and
+  sets the identity's `organization_id`.
+- Unlink submissions are rejected. To remove a member from an organization, use the identity admin API.
+
+When the signed-in identity is already bound to an organization, that organization takes precedence over the `organization` query
+parameter. An identity cannot be silently re-bound to a different organization through the settings flow.
+
+If the identity's `organization_id` points to an organization that was deleted, the settings flow falls back to a regular,
+unscoped flow. This keeps account recovery and self-service settings working for users who were offboarded from a deleted
+organization.
+
 ## SAML
 
 SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data

docs/kratos/self-service/flows/user-settings.mdx

@@ -615,6 +615,14 @@ Social Sign In is not possible for API Clients. It will be possible in a future
 
 :::
 
+:::info
+
+You can scope the settings flow to an organization by passing the `organization` query parameter. The flow then returns link nodes
+only for that organization's SSO connections, and linking one binds the identity to the organization. See
+[Bind an identity to an organization through the settings flow](../../organizations/organizations.mdx#bind-an-identity-to-an-organization-through-the-settings-flow).
+
+:::
+
 ## Settings form validation
 
 The form payloads are then submitted to Ory Identities which follows up with: