chore: add page on feature deprecations

docs/actions/require-verified-address.mdx

@@ -112,6 +112,51 @@ ory patch identity-config --project <project-id> --workspace <workspace-id> \
 The `verification` and `show_verification_ui` actions in login flows (but not sign up!) are also deprecated. Use
 `require_verified_address` instead.
 
+### Verified-address login error (`legacy_require_verified_login_error`)
+
+When the "require verified address" login hook blocks a login because the address is not yet verified, the response changed. The
+legacy behavior returned a `400 Bad Request` with a static error and skipped the check for non-password methods (such as social
+sign-in). The new behavior starts a verification flow and returns an actionable `continue_with` entry — `403 Forbidden` with
+`continue_with` for API clients, or a `303` redirect to the verification screen for browser clients — and applies to all login
+methods. The `feature_flags.legacy_require_verified_login_error` flag restores the old behavior and defaults to `false`.
+
+#### Am I affected?
+
+You are affected if any of the following apply:
+
+- [ ] Your configuration sets `feature_flags.legacy_require_verified_login_error: true`.
+- [ ] You enforce verified addresses at login and your client handles the unverified case by checking for a `400 Bad Request`
+      error rather than parsing `continue_with` (or following the browser redirect).
+- [ ] You rely on social sign-in / OIDC logins bypassing the verified-address requirement.
+
+If your client already parses `continue_with` (or follows the verification redirect) on login, you are not affected.
+
+#### Why was this change made?
+
+Returning a verification `continue_with` instead of a terminal error lets users recover from an unverified-address login without a
+dead end, and applying the check to all login methods closes a gap where social sign-in could bypass the requirement.
+
+#### How to adapt to this change?
+
+Update your login client to handle the new response before disabling the legacy flag:
+
+- For API / SDK clients, handle `403 Forbidden` and read the `show_verification_ui` action from the `continue_with` array to send
+  the user into the verification flow.
+- For browser clients, follow the `303` redirect to the verification screen.
+- If you use social sign-in / OIDC, confirm that requiring a verified address for those logins is acceptable, because the new
+  behavior no longer exempts them.
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    After your login client handles the `continue_with` verification response, disable
+    `feature_flags.legacy_require_verified_login_error` in <ConsoleLink route="project.settings.advanced" />.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    After your login client handles the `continue_with` verification response, set
+    `feature_flags.legacy_require_verified_login_error` to `false` in your Kratos configuration and redeploy.
+  </TabItem>
+</Tabs>
+
 ## Verification on sign up
 
 Ory supports two options after sign up:
@@ -198,6 +243,61 @@ ory patch identity-config --project <project-id> --workspace <workspace-id> \
   --add '/feature_flags/legacy_continue_with_verification_ui=true'
 ```
 
+### Verification UI in `continue_with` (`legacy_continue_with_verification_ui`)
+
+After registration, login, or settings, Kratos can tell the client to show a verification screen by adding a
+`show_verification_ui` entry to the flow's `continue_with` array. Previously this entry was added automatically for every
+unverified address. Going forward, it is only added when you explicitly enable the `show_verification_ui` hook. The
+`feature_flags.legacy_continue_with_verification_ui` flag restores the automatic behavior and defaults to `false`.
+
+#### Am I affected?
+
+You are affected if any of the following apply:
+
+- [ ] Your configuration sets `feature_flags.legacy_continue_with_verification_ui: true`.
+- [ ] Your UI or SDK reads `continue_with` for a `show_verification_ui` action **and** you have **not** added the
+      `show_verification_ui` hook to your post-registration / post-login / post-settings hooks.
+
+If you already configure the `show_verification_ui` hook, or you do not rely on the verification `continue_with` entry, you are not
+affected.
+
+#### Why was this change made?
+
+Making the verification screen an explicit hook gives you control over when the verification UI is surfaced, instead of Kratos
+always emitting it. It also makes the verification `continue_with` entry behave like other `continue_with` actions, which are
+driven by hooks.
+
+#### How to adapt to this change?
+
+Add the `show_verification_ui` hook to the `after` hooks of every flow where you want the verification screen surfaced
+(registration, login, and settings as applicable). Once the hook is configured, your client receives the same
+`show_verification_ui` entry in `continue_with`, and you can set the legacy flag to `false`.
+
+```yaml
+selfservice:
+  flows:
+    registration:
+      after:
+        hooks:
+          - hook: show_verification_ui
+    login:
+      after:
+        hooks:
+          - hook: show_verification_ui
+```
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    Add the `show_verification_ui` hook to the relevant flows in your project's identity configuration (via the Ory CLI or the Ory
+    Console configuration editor), then disable
+    `feature_flags.legacy_continue_with_verification_ui` in <ConsoleLink route="project.settings.advanced" />.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    Add the `show_verification_ui` hook to the relevant flows in your Kratos configuration, set
+    `feature_flags.legacy_continue_with_verification_ui` to `false`, and redeploy.
+  </TabItem>
+</Tabs>
+
 ## Verification on address change
 
 When a user updates their email address or phone number in the settings flow, Ory sends a verification code to the new address. By

docs/guides/integrate-with-ory-cloud-through-webhooks.mdx

@@ -4,6 +4,9 @@ title: Trigger custom logic and integrate with external systems with webhooks
 sidebar_label: Ory Actions
 ---
 
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
 Ory Actions supports webhooks, which are HTTP callbacks that can be triggered by specific events in your Ory-powered application.
 Webhooks allow Ory Actions to notify external systems, such as Hubspot, Mailchimp, when certain events occur, such as a user
 registration or profile update. Aside from integrating with external systems, webhooks allow you to use custom, external business
@@ -625,6 +628,61 @@ trigger these hooks is `after` flows.
 
 :::
 
+### Web hook interrupts (`can_interrupt`)
+
+The `can_interrupt` option on the `web_hook` allowed a webhook to abort a self-service flow by returning an error response. It has
+been replaced by `response.parse`, which is functionally equivalent and lives inside the structured `response` configuration object.
+The deprecated `can_interrupt` field still works today but is scheduled for removal.
+
+#### Am I affected?
+
+You are affected if any of the following apply to your configuration:
+
+- [ ] You self-host Ory Kratos and any `web_hook` in your `selfservice` configuration sets `config.can_interrupt: true`.
+- [ ] Your Ory Network project configuration contains a `web_hook` with `config.can_interrupt: true`.
+
+If you do not use webhooks, or none of your webhooks set `can_interrupt`, you are not affected.
+
+#### Why was this change made?
+
+The single boolean `can_interrupt` was folded into a structured `response` object so that response-handling behavior can be
+configured consistently and extended in the future. The `response` object also exposes `response.ignore` (fire-and-forget
+webhooks), and Kratos rejects configurations that set both `response.ignore` and `response.parse` to `true`, because parsing a
+response you intend to ignore is contradictory.
+
+#### How to adapt to this change?
+
+Replace `can_interrupt: true` with `response.parse: true` in each affected webhook. The behavior is identical: the webhook
+response is parsed and can interrupt the flow by returning validation errors.
+
+```yaml
+# Before
+- hook: web_hook
+  config:
+    url: https://example.com/webhook
+    method: POST
+    can_interrupt: true
+
+# After
+- hook: web_hook
+  config:
+    url: https://example.com/webhook
+    method: POST
+    response:
+      parse: true
+```
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    Update your project's identity configuration with the Ory CLI (`ory patch identity-config`) or the configuration editor in the
+    Ory Console so that each affected webhook uses `response.parse` instead of `can_interrupt`.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    Edit your Kratos configuration file and replace `can_interrupt: true` with `response.parse: true` for every affected webhook,
+    then redeploy.
+  </TabItem>
+</Tabs>
+
 ### Webhook retries
 
 Sometimes webhook delivery can fail due to issues such as network problems or server errors. To mitigate this, Ory Network

docs/identities/sign-in/two-step-registration.mdx

@@ -5,6 +5,9 @@ sidebar_label: Two-step registration
 slug: two-step-registration
 ---
 
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
 [Identity traits](../../kratos/manage-identities/managing-users-identities-metadata#traits) are data associated with an identity
 that can be modified by the user. The traits are configured through the identity schema.
 
@@ -19,3 +22,58 @@ when you have more than two authentication methods enabled.
 
 To disable the one-step unified registration, Go to <ConsoleLink route="project.settings.advanced.route" /> and disable **Enable
 unified sign up**.
+
+## One-step registration (`enable_legacy_one_step`)
+
+The boolean `selfservice.flows.registration.enable_legacy_one_step` is replaced by the string option
+`selfservice.flows.registration.style`, which accepts `unified` (one-step) or `profile_first` (two-step). The default is
+`profile_first`, so new projects use two-step registration, where users provide their profile information first and their
+credentials second.
+
+### Am I affected?
+
+You are affected if any of the following apply:
+
+- [ ] Your configuration sets `selfservice.flows.registration.enable_legacy_one_step`.
+- [ ] Your Kratos logs contain the warning `Found use of deprecated configuration key "selfservice.flows.registration.enable_legacy_one_step"`.
+- [ ] You have a custom registration UI that assumes a single combined registration form.
+
+If you do not set `enable_legacy_one_step` and use the default registration UI, you are not affected.
+
+### Why was this change made?
+
+A single boolean could not express the growing set of registration layouts. The `style` enum replaces it and leaves room for
+additional styles. Two-step registration (`profile_first`) became the default because it produces a clearer experience when
+multiple credential methods (password, passkey, code) are enabled.
+
+### How to adapt to this change?
+
+Remove `enable_legacy_one_step` and set `style` explicitly. Use `unified` to keep one-step registration, or `profile_first` to
+adopt the two-step default. If you operate a custom registration UI, verify it renders correctly for the style you choose —
+two-step registration renders profile fields and credential fields on separate screens with a "back" navigation node.
+
+```yaml
+# Before
+selfservice:
+  flows:
+    registration:
+      enable_legacy_one_step: true
+
+# After (keep one-step behavior)
+selfservice:
+  flows:
+    registration:
+      style: unified
+```
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    In <ConsoleLink route="project.settings.advanced" />, review your registration configuration and set the registration `style`
+    to `unified` or `profile_first` instead of relying on `enable_legacy_one_step`. Test the registration flow with your UI before
+    rolling the change out.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    Replace `enable_legacy_one_step` with the `style` option in your Kratos configuration and redeploy. As long as
+    `enable_legacy_one_step` is present and `true`, Kratos keeps one-step registration and logs a deprecation warning.
+  </TabItem>
+</Tabs>

docs/kratos/concepts/ui-user-interface.mdx

@@ -96,6 +96,83 @@ Nodes are grouped (using the `group` key) based on the source that generated the
 
 You can use the node group to filter out items, re-arrange them, render them differently - up to you!
 
+### OIDC registration node group (`legacy_oidc_registration_node_group`)
+
+During registration, profile fields collected by the OIDC (social sign-in) method used to be placed in the `oidc` UI node group.
+Going forward they are placed in the `default` group, consistent with the other methods. The
+`feature_flags.legacy_oidc_registration_node_group` flag restores the old grouping for backwards compatibility and defaults to
+`false`.
+
+#### Am I affected?
+
+You are affected if any of the following apply:
+
+- [ ] You enable OIDC / social sign-in for registration **and** your custom registration UI selects, filters, or styles form nodes
+      by the `oidc` group.
+- [ ] Your configuration sets `feature_flags.legacy_oidc_registration_node_group: true`.
+
+If you use the default Ory UI, or your UI does not branch on node groups, you are not affected.
+
+#### Why was this change made?
+
+Placing OIDC profile fields in the `default` group makes registration node grouping consistent across all methods, which
+simplifies custom UIs and unifies the experience with two-step registration.
+
+#### How to adapt to this change?
+
+Update your custom registration UI to read OIDC profile fields from the `default` node group instead of the `oidc` group. Once your
+UI no longer depends on the `oidc` group, set the flag to `false` (or remove it) to adopt the new behavior.
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    Ory Network projects use the `default` grouping unless the legacy flag was explicitly enabled. Review
+    <ConsoleLink route="project.settings.advanced" /> to confirm the flag is disabled after your UI is updated.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    After updating your UI, ensure `feature_flags.legacy_oidc_registration_node_group` is unset or `false` in your Kratos
+    configuration, then redeploy.
+  </TabItem>
+</Tabs>
+
+### Password registration node group (`password_profile_registration_node_group`)
+
+This mirrors the OIDC node-group change for the password method. Profile fields collected by the password method during
+registration used to be placed in the `password` UI node group when single-step registration was used; they are now placed in the
+`default` group. The `selfservice.methods.password.config.password_profile_registration_node_group` option toggles between
+`password` and `default` and defaults to `default`.
+
+#### Am I affected?
+
+You are affected if all of the following apply:
+
+- [ ] Your configuration sets `password_profile_registration_node_group: password`.
+- [ ] You use one-step registration (registration `style` is not `profile_first`).
+- [ ] Your custom registration UI selects, filters, or styles form nodes by the `password` group.
+
+If the option is unset (defaults to `default`), or you use two-step registration, you are not affected.
+
+#### Why was this change made?
+
+As with the OIDC change, placing password profile fields in the `default` group makes node grouping consistent across methods and
+aligns single-step registration with two-step registration.
+
+#### How to adapt to this change?
+
+Update your custom registration UI to read password profile fields from the `default` node group, then set
+`password_profile_registration_node_group` to `default` or remove it. Adopting two-step registration (`style: profile_first`)
+bypasses this option entirely, because profile fields are then collected by the dedicated profile step.
+
+<Tabs>
+  <TabItem value="network" label="Ory Network">
+    Ory Network projects use the `default` grouping unless the legacy value was explicitly set. After updating your UI, confirm the
+    option is `default` or unset in <ConsoleLink route="project.settings.advanced" />.
+  </TabItem>
+  <TabItem value="self-hosted" label="Self-hosted (OSS or OEL)">
+    After updating your UI, set `selfservice.methods.password.config.password_profile_registration_node_group` to `default` (or
+    remove it) in your Kratos configuration, then redeploy.
+  </TabItem>
+</Tabs>
+
 ## UI node types
 
 UI Nodes can have several types!

docs/kratos/deprecations/index.mdx

@@ -0,0 +1,59 @@
+---
+id: index
+title: Feature deprecations
+sidebar_label: Feature deprecations
+---
+
+This section lists deprecated behavior in Ory Kratos. Check this section regularly to avoid relying on deprecated functionality.
+
+## Who does this apply to?
+
+Users of the Ory Network, Ory Kratos (open source) and the OEL (Ory Enterprise License) are affected by this section.
+
+## How to use this section
+
+Documentation for each deprecated feature now lives alongside the feature it affects. Each entry provides information about the
+deprecated feature, including:
+
+- A brief description of the feature and its purpose.
+- The reason for deprecation, if available.
+- The version in which the feature was deprecated.
+- Any recommended alternatives or migration paths, if applicable.
+
+If you're using an Ory Network project, your configuration will not change, unless you have explicitly disabled the deprecated
+feature via a project level feature flag. To check which flags are currently enabled, go to
+
+<ConsoleLink route="project.settings.advanced" />.
+
+If you're self-hosting Ory Kratos (either through open source or the OEL), you should review your configuration and codebase to
+identify any usage of deprecated features before upgrading to a new version. This will help you avoid any potential issues that
+may arise from the removal of deprecated features in future releases.
+
+## Stay informed
+
+Subscribe to the [Ory Changelog](https://changelog.ory.com) to receive updates on new releases, including information about
+deprecated features and their removal timelines. Additionally, consider joining the Ory community on Slack or GitHub to stay
+engaged with other users and developers, and to get support for any questions or issues related to deprecated features.
+
+## Impacted functionality
+
+Deprecation notes are documented with the features they affect:
+
+- **Admin session extension API (`faster_session_extend`)** —
+  [Refresh sessions](../session-management/20_refresh-extend-session.mdx)
+- **Web hook interrupts (`can_interrupt`)** —
+  [Trigger custom logic and integrate with external systems with webhooks](../../guides/integrate-with-ory-cloud-through-webhooks.mdx)
+- **WebAuthn and passkey relying party origin (`rp.origin` and `rp.icon`)** —
+  [Passkeys & WebAuthN](../passwordless/05_passkeys.mdx)
+- **Link strategy base URL (`link.config.base_url`)** —
+  [Wrong domain in magic links](../../troubleshooting/magic-link-verification-url.mdx)
+- **One-step registration (`enable_legacy_one_step`)** —
+  [Two-step registration](../../identities/sign-in/two-step-registration.mdx)
+- **OIDC registration node group (`legacy_oidc_registration_node_group`)** —
+  [UI node groups](../concepts/ui-user-interface.mdx#ui-node-groups)
+- **Password registration node group (`password_profile_registration_node_group`)** —
+  [UI node groups](../concepts/ui-user-interface.mdx#ui-node-groups)
+- **Verification UI in `continue_with` (`legacy_continue_with_verification_ui`)** —
+  [Address verification](../../actions/require-verified-address.mdx)
+- **Verified-address login error (`legacy_require_verified_login_error`)** —
+  [Address verification](../../actions/require-verified-address.mdx)