chore(core): update some experience API doc descriptions

packages/core/src/routes/experience/experience.openapi.json

@@ -60,10 +60,10 @@
               "schema": {
                 "properties": {
                   "verificationId": {
-                    "description": "The ID of the verification record used to identify the user. <br/>- `SignIn` and `ForgotPassword` interactions: Required to verify the user's identity. <br/>- `Register` interaction: Optional. If provided, it updates the profile data with the verification record before account creation. If omitted, the account is created using existing profile data in the current interaction."
+                    "description": "The ID of the verification record used to identify the user. <br/>- For `SignIn` and `ForgotPassword` interactions: Required to verify the user's identity. <br/>- For `Register` interaction: Optional. If provided, new profile(s) will be attached to the registration session using the information from the verification record and trigger the account creation attempt. If not provided, the user account creation attempt will be triggered using the existing profile data in the interaction."
                   },
                   "linkSocialIdentity": {
-                    "description": "Applies to the SignIn interaction only, and is used when a SocialVerification type verificationId is provided. <br/>- If `true`, the user is identified using the verified email or phone number from the social identity provider, and the social identity is linked to the user's account. <br/>- If `false` or not provided, the API identifies the user solely through the social identity. <br/> This parameters is used for linking a non-existing social identity to a related user account that can be identified through the verified email or phone number."
+                    "description": "Applies only to the SignIn interaction and is used when a SocialVerification type verification ID is provided. <br/>- If `true`, the user is identified using the verified email or phone number from the social identity provider, and the social identity is linked to the user's account. <br/>- If `false` or not provided, the API identifies the user solely through the social identity. <br/>This parameter is used to link a non-existing social identity to a related user account identified by the verified email or phone number."
                   }
                 }
               }

packages/core/src/routes/experience/verification-routes/social-verification.openapi.json

@@ -59,7 +59,7 @@
               "schema": {
                 "properties": {
                   "verificationId": {
-                    "description": "The ID of the Social verification record."
+                    "description": "The ID of the social verification record. Optional for Google one tap login, as it does not have a pre-created social verification record in session."
                   },
                   "connectorData": {
                     "description": "Arbitrary data returned by the social provider to complete the verification process."

packages/schemas/src/types/interactions.ts

@@ -82,7 +82,12 @@ export const socialAuthorizationUrlPayloadGuard = z.object({
 export type SocialVerificationCallbackPayload = {
   /** The callback data from the social connector. */
   connectorData: Record<string, unknown>;
-  /**  The verification ID returned from the authorization URI. Optional for Google one tap callback */
+  /**
+   * Verification ID is used to retrieve the verification record.
+   * Throws an error if the verification record is not found.
+   *
+   * Optional for Google one tap callback as it does not have a pre-created verification record.
+   **/
   verificationId?: string;
 };
 export const socialVerificationCallbackPayloadGuard = z.object({
@@ -103,6 +108,13 @@ export const passwordVerificationPayloadGuard = z.object({
 /** Payload type for `POST /api/experience/verification/totp/verify`. */
 export type TotpVerificationVerifyPayload = {
   code: string;
+  /**
+   * Required for verifying the newly created TOTP secret verification record in the session.
+   * (For new TOTP setup use only)
+   *
+   * If not provided, a new TOTP verification will be generated and validated against the user's existing TOTP secret in their profile.
+   * (For existing TOTP verification use only)
+   */
   verificationId?: string;
 };
 export const totpVerificationVerifyPayloadGuard = z.object({
@@ -121,8 +133,12 @@ export const backupCodeVerificationVerifyPayloadGuard = z.object({
 /** Payload type for `POST /api/experience/identification`. */
 export type IdentificationApiPayload = {
   /**
-   * The ID of the verification record that is used to identify the user.
-   * Optional for the register interaction event
+   * SignIn and ForgotPassword interaction events:
+   * Required to retrieve the verification record to validate the user's identity.
+   *
+   * Register interaction event:
+   *  - If provided, new user profiles will be appended to the registration session using the verified information from the verification record.
+   *  - If not provided, the user creation process will be triggered directly using the existing profile information in the current registration session.
    */
   verificationId?: string;
   /**