🔍 Description

What changed?

Reworked the JSDoc on GoTrueClient.signOut so the default scope: 'global' is impossible to miss:

• Added a ⚠️ warning callout directly under the one-liner description noting that the default signs out every device and pointing at { scope: 'local' } as the common choice.
• Strengthened the @remarks bullet with the same guidance (shared/public devices are the canonical pain point).
• Renamed the @example headings so the default is labelled "Sign out of every device (global – default)" with a ⚠️ comment, local is tagged "(recommended for most apps)", and others reads as "keep the current one".

No runtime, type, or API changes — just the JSDoc block above signOut() in packages/core/auth-js/src/GoTrueClient.ts.

Why was this change needed?

Issue #1608 flagged that supabase.auth.signOut() defaults to scope: 'global' — unlike most auth libraries — which signs the user out of every device they're signed in on, including phones/other tabs. The existing JSDoc mentioned the default in passing, but it was easy to miss. Users have spent days debugging why sessions randomly disappear on unrelated devices after a routine sign-out (linked from #1608).

Addresses the first of the three asks in #1608 ("Add a big fat red warning about this"). The error-message rename ("refresh token not found" → "refresh token has been revoked") and the potential behavior change for a major release are out of scope for this docs-only PR and left for separate discussion.

Refs #1608

📸 Screenshots/Examples

Before (existing JSDoc, paraphrased):

By default, signOut() uses the global scope, which signs out all other sessions that the user is logged into as well.

After — the warning is hoisted above @remarks, flagged with ⚠️, and the @example block labels each scope with its real-world use:

@example Sign out of every device (global – default)
// ⚠️ Also signs the user out of every other device / browser they're on.
await supabase.auth.signOut()

@example Sign out only the current session (recommended for most apps)
await supabase.auth.signOut({ scope: 'local' })

@example Sign out of all other sessions, keep the current one
await supabase.auth.signOut({ scope: 'others' })

🔄 Breaking changes

• This PR contains no breaking changes

📋 Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: docs(auth): surface global-scope warning on signOut JSDoc
• I have run prettier --check on the changed file (clean)
• No tests needed — JSDoc-only change, no runtime/type surface altered
• Documentation updated (this is the doc update)

📝 Additional notes

Scoped intentionally narrow: the same warning probably belongs on the hosted guide at https://supabase.com/docs/guides/auth/signout and on gotrue-js equivalents. Happy to open follow-ups in those repos if this direction looks right.