From ae7167fe583ca4b63682d261c49f85b72f4866ad Mon Sep 17 00:00:00 2001
From: Guillaume Faas <59444272+Tr00d@users.noreply.github.com>
Date: Mon, 14 Sep 2026 10:07:10 +0200
Subject: [PATCH] docs: update SignUp documentation in C# reference (#48733)

Addresses https://github.com/supabase-community/gotrue-csharp/issues/85

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Clarified sign-up behavior, including returned sessions, email
confirmation, automatic session adoption, and sign-in events.
- Documented existing-user obfuscation and the error raised when
registration is rejected.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/spec/supabase_csharp_v1.yml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/apps/docs/spec/supabase_csharp_v1.yml b/apps/docs/spec/supabase_csharp_v1.yml
index dd5e3078e4d..9c9279e37d6 100644
--- a/apps/docs/spec/supabase_csharp_v1.yml
+++ b/apps/docs/spec/supabase_csharp_v1.yml
@@ -116,14 +116,15 @@ functions:
     description: |
       Creates a new user.
     notes: |
-      - By default, the user needs to verify their email address before signing in. To turn this off, disable **Confirm email** in [your project](https://supabase.com/dashboard/project/_/auth/providers).
+      - `SignUp()` returns a `Session`. Inspect `Session.User` to determine the outcome; an empty `Session.User.Identities` list indicates the account already existed.
+      - By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](https://supabase.com/dashboard/project/_/auth/providers).
       - **Confirm email** determines if users need to confirm their email address after signing up.
-        - If **Confirm email** is enabled, a `user` is returned but `session` is null.
-        - If **Confirm email** is disabled, both a `user` and a `session` are returned.
+        - If **Confirm email** is enabled, the returned user is unconfirmed (`Session.User.ConfirmedAt` is null and `Session.User.ConfirmationSentAt` is set) and the client is not signed in.
+        - If **Confirm email** is disabled, the user is auto-confirmed, the returned `Session` is adopted as the current session, and a `SignedIn` state change fires.
       - When the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/guides/auth/concepts/redirect-urls) by default. You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).
-      - If SignUp() is called for an existing confirmed user:
-        - When both **Confirm email** and **Confirm phone** (even when phone provider is disabled) are enabled in [your project](/dashboard/project/_/auth/providers), an obfuscated/fake user object is returned.
-        - When either **Confirm email** or **Confirm phone** (even when phone provider is disabled) is disabled, the error message, `User already registered` is returned.
+      - If `SignUp()` is called for an existing confirmed user, GoTrue avoids revealing that the account exists, so the outcome depends on your project's settings:
+        - When both **Confirm email** and **Confirm phone** (even when phone provider is disabled) are enabled in [your project](/dashboard/project/_/auth/providers), a `Session` is returned whose `Session.User.Identities` list is empty (an obfuscated user; no new account was created).
+        - When either **Confirm email** or **Confirm phone** (even when phone provider is disabled) is disabled, a `GotrueException` with the message `User already registered` is thrown.
     examples:
       - id: sign-up
         name: Sign up.