Skip to content

Accounts and identity UX implementation plan

Status: implementation handoff specification

Date: 2026-08-21

Audience: product/design implementers and coding agents working on feat/accounts-identity-foundation

Lifecycle: active implementation contract where the roadmap still schedules the work. Check the platform roadmap before treating an unchecked step as current priority.

This document is the player-facing and implementation handoff companion to Accounts and subscriptions plan. That document remains authoritative for the overall identity, BFF trust-boundary, storage, and billing architecture. This document is authoritative for account UI, user journeys, state transitions, recovery behavior, errors, undo semantics, and the order in which those experiences should be implemented.

The Engagement platform plan remains authoritative for the broader product principles: anonymous play remains available, account prompts appear only at natural value moments, groups are the social boundary, and the puzzle remains the quietest screen.

This document deliberately refines two earlier implementation sketches: the OIDC callback now uses the non-mutating prepare/pause/commit seam in section 6.2.1 whenever player choice is required, and account deletion retains only legally required pseudonymized financial/audit records rather than promising indiscriminate deletion from Stripe or other processors. If older plan wording conflicts on those two points, this document controls the implementation handoff.

The duplicate-play and concurrent-merge algorithms in section 7 mirror section 3a of doc/accounts-and-subscriptions-plan.md. Treat them as one locked cross-document contract and update both documents together if a future game requires different logical-play semantics.

1. Locked product decisions

The following decisions are settled for the first account release.

  1. Playing without an account remains a complete supported mode. First visit never begins with an account wall.
  2. A Verbolus account owns the player's canonical profile, plays, statistics, streaks, groups, preferences, and future entitlements.
  3. A Verbolus account can have multiple sign-in methods from its first release.
  4. The intended sign-in methods are:
  5. email address and password through Microsoft Entra External ID;
  6. Google Account;
  7. personal Microsoft account (MSA: Outlook.com, Hotmail, Xbox, and personal Microsoft 365);
  8. Facebook is optional and must remain disabled in the hosted user flow until approved.
  9. “Continue with Microsoft” means personal Microsoft accounts. A connection to one organization's workforce Entra tenant must not be substituted or labeled as generic Microsoft sign-in.
  10. The local method is called email and password in user-facing copy. Do not call it username and password unless Verbolus later deliberately adopts Entra's username/alias preview feature.
  11. Microsoft Entra External ID owns credential entry, email verification, password creation, password reset, provider consent, and provider authentication. Verbolus never receives or logs a password or social-provider token.
  12. The hosted authentication page is branded “Verbolus.” There is no duplicate Verbolus-built provider chooser. A Verbolus CTA redirects to the single Entra-hosted flow.
  13. The player's display name is a Verbolus nickname shown in groups and leaderboards. It is separate from the login email and from any provider's profile name.
  14. An existing cookie-only profile is never silently discarded or silently merged. The player sees a summary and chooses whether to keep its progress, start fresh, or cancel.
  15. Identity methods are never auto-linked merely because two providers return the same email address. Linking requires a currently authenticated Verbolus account and successful proof of control of the new method.
  16. Social providers are authentication only. Request only the minimal OIDC scopes needed for authentication. Do not import contacts, Facebook friends, profile posts, or Google People data. Result sharing continues through the existing explicit native share/copy actions.
  17. Signing out signs out of Verbolus on the current device. It does not unexpectedly sign the user out of Google, Microsoft, or Facebook.
  18. Switching accounts is distinct from signing out and distinct from merging accounts.
  19. The one-time Stripe tip does not require an account and never grants an entitlement. A future recurring Supporter subscription requires a verified account and recent authentication.

2. Terminology and identity model

Use these terms consistently in code, contracts, telemetry, tests, and user-facing documentation.

Term Meaning Player-facing wording
Guest profile The existing cookie-only player record on one browser/install “Progress on this device”
Verbolus account The durable canonical player identity “Your Verbolus account”
Sign-in method One verified external identity attached to an account “Email and password,” “Google,” “Microsoft,” or “Facebook”
playerId Stable canonical account/profile identifier Never display it
installationId Stable identifier for one browser/PWA installation Normally never display it
External identity Stable OIDC issuer + subject (and provider metadata) Display only the friendly provider name and masked identifier
Session The current device's verified access to a Verbolus account “Signed in on this device”
Guest import Attaching a guest profile's data to an account “Keep this device's progress”
Account merge Combining two independently established Verbolus accounts “Combine accounts”

One provider identity maps to exactly one canonical playerId. One playerId may have many provider identities. Provider email is metadata, not the account key and not proof that two identities belong to the same person.

3. Account states

Model these states explicitly. Do not infer them from whether a display name or email happens to be present.

State Meaning Allowed experience
guest Valid signed anonymous cookie; no verified identity Full ordinary play, local progress, account prompts at value moments
authenticating OIDC transaction has started Return/cancel safely; do not change player identity yet
needs-account-decision OIDC succeeded; guest data and target account disposition await choice Only the completion/merge flow and safe cancellation
merge-pending A confirmed idempotent import/merge operation is running or awaiting reconciliation Show progress and retry status; source and target remain protected
verified Valid account session Cross-device data, sign-in-method management, future billing
reauth-required Account session is valid, but the requested sensitive action needs fresh proof Preserve form/context and launch step-up authentication
session-expired This installation previously used an account, but verified session expired Prompt to sign in again; do not silently present an empty new profile as the account
deletion-scheduled Renewal is canceled and account deletion awaits its effective date Read-only warning, cancel-deletion action, export, sign out
deletion-running Destructive deletion job has crossed its irreversible checkpoint Status only; do not claim completion until reconciliation succeeds
deleted Player data and identity mappings are removed/anonymized as specified A later sign-up creates a new empty account; old progress is not restored

Transitions must be server-authoritative and idempotent. Browser query parameters and local storage may choose presentation but never establish authentication, merge completion, or entitlement.

4. Navigation and screens

4.1 Header and menu

Preserve the existing compact header. Do not add a permanent avatar or account button.

In the hamburger menu:

  • guest: retain Settings; optionally add a quiet secondary line or menu item, Create account or sign in, only after the account feature is released;
  • verified: label the destination Account & settings, with a non-sensitive secondary line such as Signed in as Maya when a display name exists;
  • never display an email address in the closed menu or on a signed-out screen, because devices can be shared.

4.2 Settings information architecture

Evolve /settings from the current long form into a small index. The initial implementation may keep sections on one page if routes would delay delivery, but contracts and components should support these focused destinations:

Settings

Profile                 Display name
Appearance              Theme
Account                 Status and sign-in methods
Privacy and data        Consent, export, deletion
Membership              Supporter status, when available
Notifications           Later

4.3 Guest Account screen

Account

You're playing without an account.
Your progress is saved in this browser. Create an account to keep your streaks,
groups, and settings if you change devices.

[ Create account or sign in ]

You can keep playing without an account.

Do not use fear copy such as “Your progress is at risk” or imply that ordinary guest play is temporary. Explain the real limitation: clearing browser data, changing browsers, or losing the device can make a guest profile inaccessible.

4.4 Verified Account screen

Account

Signed in as Maya
Your progress is saved to your Verbolus account.

Sign-in methods
  Google             ma•••@gmail.com       Connected
  Microsoft          Not connected         [ Add ]
  Email and password Not connected         [ Add ]
  Facebook           Not connected         [ Add ]   (only when enabled)

[ Switch account ]
[ Sign out of this device ]

Danger zone
  [ Delete Verbolus account ]

Each connected method has a stable opaque method ID, friendly provider, masked identifier when available, link date, and whether it may be removed. Do not send raw issuer/subject values to a client component unless a server-only route needs them.

4.5 Entra-hosted screen

Use one hosted screen for sign-up and sign-in:

Verbolus

Email address
[                                      ]
No account? Create one
[ Next ]

---------------- or ----------------
[ Continue with Google ]
[ Continue with Microsoft ]
[ Continue with Facebook ]   (optional)

Use the actual provider brand assets and follow their branding requirements. Keep supporting text short: Sign in to save your progress across devices. Privacy and Terms links must point to current Verbolus pages.

5. Account entry points and prompt frequency

Always provide Account from Settings. Additionally show a dismissible contextual prompt only at a natural pause:

Trigger Copy direction Primary action
A meaningful Daily streak “Keep your 7-day streak across devices.” Save my progress
Immediately after creating or joining a group “Keep this group if you change phones.” Create account or sign in
Future supporter checkout “A Verbolus account keeps supporter benefits available on your devices.” Sign in to continue
Future cross-device notifications “Sign in to receive this event on your devices.” Sign in

Rules:

  • never prompt on the first page load;
  • never prompt over an active puzzle board;
  • never show more than one account prompt in one session;
  • dismissal suppresses that prompt reason for 30 days on the installation;
  • a materially different value moment may prompt later;
  • Settings remains available regardless of suppression;
  • track prompt reason and outcome without email, name, issuer, subject, or provider account ID.

6. End-to-end user workflows

6.1 First visit and continued guest play

  1. The proxy creates or preserves the signed anonymous player cookie.
  2. The player chooses a game and plays without registration.
  3. Plays, scorecard, streaks, settings, and groups continue to attach to the guest playerId.
  4. Settings describes the state as Playing without an account.
  5. Clearing the cookie is not treated as deletion. The privacy UI explains that deletion must be requested before clearing inaccessible browser state.
  6. A later contextual prompt may start account creation; ignoring it changes nothing.

Acceptance outcome: no account component, Entra request, or auth JavaScript blocks or delays first play.

6.2 Start sign-up or sign-in from a guest profile

  1. The player selects Create account or sign in.
  2. The BFF creates an authorization transaction containing:
  3. random transaction/operation ID;
  4. current guest playerId, resolved from the signed cookie;
  5. installation ID;
  6. validated same-origin return path and prompt reason;
  7. PKCE verifier/challenge, state, nonce, creation time, and expiry;
  8. no raw credential or provider token in browser-readable storage.
  9. The BFF redirects to the single Entra user flow.
  10. The player uses email/password or a provider.
  11. Cancellation, back navigation, or denial returns to the originating safe route with a neutral Sign-in canceled. Your device progress is unchanged. message.
  12. On callback, the BFF validates code, state, nonce, issuer, audience, timestamps, and PKCE before trusting any claim.
  13. Tokens remain server-side. The BFF resolves the external identity through the internal backend trust boundary.
  14. The BFF does not replace the guest cookie or issue a verified session until the account decision reaches a safe checkpoint.

6.2.1 Required callback-to-completion handoff

This is a required design and implementation boundary, not merely a UI detail. The OIDC callback finishes identity authentication, but sign-in is not necessarily complete. When meaningful guest data could be promoted, deferred, or merged, the player must decide what happens before Verbolus issues a verified account session.

Use this sequence:

Entra callback
    |
    | validate code + PKCE + state + nonce + token
    v
Prepare sign-in (server-side, no mutation of player ownership)
    |
    +-- no decision needed --> Commit automatically --> mint verified cookie
    |
    +-- decision needed ----> /account/finish --> player chooses
                                                |
                                                v
                                       Commit chosen operation
                                                |
                                                v
                                      mint verified cookie

Prepare

  1. The callback validates the OIDC result completely. At this point Verbolus knows that the user controls an external identity, but the browser still has its original guest/account session.
  2. The BFF sends the verified identity to a new non-destructive internal operation such as POST /v1/internal/identity/prepare, authenticated through the completed BFF app-role boundary and forwarding the original browser cookie.
  3. prepare resolves:
  4. current source playerId from the forwarded signed cookie;
  5. external identity owner, if any;
  6. whether the source contains meaningful data;
  7. whether this is a same-account sign-in, new-account promotion, existing-account sign-in, guest import, or sign-in-method collision;
  8. a fresh preview of plays, streaks, groups, settings, and display-name conflict.
  9. prepare must not call the current mutating link or merge operation. In particular, the existing /link endpoint links a previously unowned identity immediately and therefore cannot be the callback's first call when Keep this progress versus Start fresh is still undecided. Wrap/extend the current foundation with prepare/commit semantics rather than weakening the UX.
  10. The backend stores a short-lived pending sign-in attempt containing the verified identity, source/target references, mode, preview version, Entra-supplied Display Name candidate, safe return path reference, creation/expiry, and idempotency key. Raw provider tokens are not stored.
  11. Return an opaque attempt ID and one disposition:
  12. complete-same-account;
  13. complete-no-guest-data;
  14. choose-new-account-progress (Keep this progress / Start fresh / Cancel);
  15. choose-existing-account-import (Add this device's progress / Use account only / Cancel);
  16. choose-account-merge for a link-method collision;
  17. blocked for a security, billing, or unreconciled-account conflict.
  18. Do not return source/target player IDs, issuer, or subject to browser components. The opaque attempt ID is not sufficient authorization by itself.

Pause

  1. If no decision is needed, the callback may immediately call commit and finish sign-in.
  2. If a decision is needed, set a short-lived Secure, HttpOnly, intentional-SameSite pending cookie bound to the attempt and installation, then redirect to /account/finish with at most an opaque attempt reference.
  3. Keep the original signed guest cookie unchanged. Do not set authLevel=verified, expose account data through ordinary endpoints, or redirect to the requested paid/account action yet.
  4. /account/finish loads its current preview server-side. Browser code receives only the counts, labels, choices, and conflict data needed to render the screen.
  5. A second tab may keep playing while the decision screen is open. Commit must therefore re-read source state and either incorporate later safe changes or return preview-changed and require a refreshed confirmation; it must not silently act on a stale destructive preview.
  6. Pending attempts expire after a short fixed window (initial recommendation: 10 minutes). Expiry leaves the original guest/session cookie and all player data unchanged. The player restarts authentication; callbacks and attempts are one-time-use.

Commit

  1. The finish screen posts one explicit decision and the opaque attempt reference to a BFF action. The BFF combines the pending cookie, original browser cookie, CSRF proof, and app-role credential when calling a new internal operation such as POST /v1/internal/identity/commit.
  2. The backend verifies that the attempt is unexpired, unused, bound to the same source player and installation, and compatible with the requested decision.
  3. The backend records the durable operation before changing ownership, identity mappings, aliases, groups, or settings.
  4. keep promotes or merges; start-fresh creates/uses the clean target plus a deferred-import record; use-account-only signs into the existing target plus a deferred-import record; account-merge follows the separately confirmed account rules.
  5. Repeating commit with the same attempt/decision returns the same result. A conflicting second decision is rejected.
  6. Commit returns only after the canonical account and external-identity mapping have reached the documented safe checkpoint. Non-critical reconciliation may continue durably, with status shown to the player.
  7. Only now does the BFF mint/rotate the signed verified cookie for the canonical playerId, clear the pending cookie, invalidate the attempt, and redirect to the original allowed return path.
  8. A commit failure leaves the player in needs-account-decision or merge-pending; it never falls through to an apparently successful account session.
  9. If another operation currently owns a required account lease, commit keeps the same operation ID, honors Retry-After, and remains in merge-pending. After acquiring both current-root leases it re-resolves the roots and rechecks the material preview fingerprint; a changed duplicate winner or other material conflict returns to needs-account-decision instead of silently applying stale consent.

Cancel

  1. Cancel invalidates the pending attempt/cookie and returns to the original guest or verified session unchanged.
  2. It does not unlink an existing identity, delete an Entra customer object, delete guest data, or mint a verified session.
  3. The fact that Entra may retain its own SSO session does not mean Verbolus sign-in completed.

Evolve the existing signed cookie as described in doc/accounts-and-subscriptions-plan.md, with a versioned payload containing at least:

{ version, playerId, authLevel, issuedAt, expiresAt }
  • authLevel=anonymous means the cookie identifies a guest profile. Ordinary gameplay continues to work as it does today.
  • authLevel=verified means an OIDC identity was proven and the callback-to-completion commit above succeeded. Billing and other account-only endpoints require this level plus any recent-auth requirement.
  • Legacy bare/signed UUID cookies migrate as anonymous without changing their underlying player ID.
  • GetUserId() continues to expose only the resolved canonical player ID to ordinary endpoints; add a focused verified-session authorization helper/policy rather than scattering cookie parsing.
  • Enforce expiry server-side, rotate verified cookies through the BFF, and prevent session fixation.
  • Never set verified immediately after token validation if an account decision or merge is pending.

6.3 Create an account with email and password

  1. On the Entra page, the player enters an email address and selects Next.
  2. If no local identity exists, the player selects Create one.
  3. Entra verifies ownership of the email using its configured verification flow.
  4. Entra asks for password and confirmation. Password policy, visibility control, validation, throttling, and breach/risk protections belong to Entra; Verbolus must not duplicate rules it cannot authoritatively enforce.
  5. Entra collects Display Name during sign-up. Customize the label/help if supported: Shown in Verbolus groups and leaderboards. You can change it later.
  6. Display-name input is trimmed and normalized consistently with Verbolus settings. Maximum length is 32 Unicode characters/grapheme policy as implemented by the backend. Reject control characters and dangerous/invisible-only values. Do not require a real/legal name.
  7. Entra creates the customer identity and returns to the callback.
  8. Verbolus creates or resolves the canonical account and proceeds to the guest-progress decision in section 6.6.
  9. The explicit display name entered during this sign-up becomes the account's initial Verbolus display name. If an existing canonical account is being recovered, its existing name wins unless the player explicitly changes it later.
  10. The final success screen says Account created and summarizes what was kept. It never displays the password.

If the email is already registered, Entra moves to sign-in or presents recovery without revealing more account-existence information than its standard protected flow.

6.4 Create an account with Google, Microsoft MSA, or Facebook

  1. The player selects the provider on the Entra-hosted screen.
  2. The provider authenticates and displays its own consent experience.
  3. Request only openid, the stable subject, and the minimal profile/verified-email claims needed for display and support. Do not request contacts, posts, calendar, files, friend lists, or offline API access unrelated to authentication.
  4. If Entra needs an additional Display Name, it asks during the same sign-up flow using the Verbolus-specific explanation above.
  5. Provider cancellation or consent denial returns to Verbolus without changing the guest profile.
  6. On success, Verbolus resolves the identity and proceeds to section 6.6.

Microsoft MSA is a release requirement but a configuration spike is mandatory before UI work is declared complete. Prove personal Outlook/Hotmail/Xbox accounts end to end. Do not mark the task complete with only a workforce-tenant Entra federation.

6.5 Sign in to an existing account on a device with no meaningful guest data

  1. The player authenticates using any connected method.
  2. The identity lookup resolves the canonical playerId.
  3. If the current guest profile has no saved plays, streaks, group memberships, non-default settings, or meaningful local state, skip the merge preview.
  4. Issue/rotate the verified session for the canonical account.
  5. Redirect to the validated return path and show Signed in as Maya.
  6. Load canonical server data; never show an empty guest scorecard while account data is loading.

6.6 Create a new account from a guest profile with progress

After authentication creates a new identity and no existing account owns it, show:

Save this device's progress?

This browser already has:
  24 completed games
  A 7-day current streak
  2 groups
  Display name: Maya

[ Keep this progress ]
[ Start fresh ]
[ Cancel ]

Keep this progress:

  1. Promote the existing guest playerId in place whenever possible.
  2. Attach the new verified identity to that canonical profile.
  3. Preserve plays, statistics, streaks, groups, ownership, settings, and display name.
  4. If the sign-up flow supplied a different display name, explain the difference and let the player choose on the confirmation screen. Default to the newly entered name because it is the most recent explicit choice; do not silently overwrite.
  5. Issue the verified session only after the external-identity mapping and canonical profile are at a safe, idempotent checkpoint.

Start fresh:

  1. Create an empty canonical account for the verified identity.
  2. Do not attach or delete the guest profile immediately.
  3. Create a server-side deferred-import record linking the authenticated account, installation, and source guest profile for 30 days. Do not expose either player ID.
  4. Show a persistent-but-dismissible Settings notice during the grace period: Progress from this device was not added. Review and add it before September 20.
  5. Review and add returns to the same preview and can complete the import.
  6. At the end of 30 days, purge the abandoned guest profile and the deferred-import record through a reconciled deletion job. The original confirmation must say this will happen.

Cancel:

  1. Do not link the identity, create the verified session, or alter the guest cookie.
  2. If Entra has already created a customer directory object, it may remain unlinked until a later sign-in; the next successful attempt resumes account completion safely.
  3. Return to the originating route with all guest progress intact.

6.7 Sign in to an existing account from a guest device that has progress

Show a two-sided summary without exposing raw IDs:

We found your Verbolus account

Your account
  86 completed games · 12-day streak · 3 groups

Progress on this device
  5 completed games · 2-day streak · 1 group

[ Add this device's progress ]
[ Use my account without adding it ]
[ Cancel ]

Add this device's progress:

  1. Create an idempotent durable merge/import operation before mutation.
  2. Keep the existing verified account as canonical.
  3. Apply the conflict rules in section 7.
  4. Repoint group membership/ownership and installation-scoped services.
  5. Preserve an alias from the source profile until every dependent read, export, deletion, and reconciliation path understands the merge.
  6. Issue the canonical verified session at the safe checkpoint.
  7. Show Signed in. Progress from this device was added.

Use my account without adding it uses the 30-day deferred-import behavior from section 6.6. It must not immediately delete the guest data.

Cancel returns to guest play unchanged.

6.8 Merge is slow, interrupted, or partially completed

  1. After confirmation, route to a dedicated status surface keyed by an opaque operation ID.
  2. Show Combining your progress… You can leave this page.
  3. Poll with bounded backoff or refresh via a server response; never retry the mutation with a new operation ID.
  4. Refresh/retry uses the same idempotency key.
  5. If recoverable work is pending, say Your progress is safe. We're still finishing the update.
  6. Provide Try again only when it resumes/reconciles the same operation.
  7. A support reference may display a short non-secret correlation code, never a player ID, issuer, subject, token, or exception.
  8. Do not claim success until the canonical profile, external-identity lookup, aliases, and critical group ownership are consistent or recorded for guaranteed reconciliation.

6.9 Ordinary returning sign-in

  1. The player selects Sign in from Account or a contextual action.
  2. Entra may reuse its own SSO session or ask for credentials/provider choice.
  3. Verbolus resolves the returned identity to one canonical account.
  4. A guest preview appears only when meaningful guest data exists.
  5. The BFF rotates the verified session and redirects to the original same-origin path.
  6. An unrecognized identity goes through account completion; it must not receive another account's data because an email happens to match.

6.10 Add another sign-in method

This capability ships with accounts, not as a speculative later feature.

  1. From Account, select Add beside Email and password, Google, Microsoft, or Facebook.
  2. If the account session is not recently authenticated, complete reauthentication first.
  3. The BFF starts a link transaction bound to:
  4. current canonical account;
  5. requested provider;
  6. state/nonce/PKCE;
  7. validated Account return path;
  8. short expiry and one-time use.
  9. Entra/provider authenticates the new method. Provider selection is constrained to the method the player chose so a Google link cannot unexpectedly become Facebook.
  10. The backend checks the verified issuer + subject mapping.

Outcomes:

  • Not linked anywhere: attach it to the current canonical account and show Microsoft was added as a sign-in method.
  • Already linked to this account: treat as idempotent success and show Microsoft is already connected.
  • Linked to another account: do not move it silently. Continue to section 6.11.
  • Canceled/denied/expired: leave the method list unchanged and show a recoverable message.

Adding email and password from a social-only account requires verified email ownership and setting a password entirely in Entra. Do not accept an email/password pair through a Verbolus API.

6.11 New sign-in method belongs to another Verbolus account

Both accounts have now been independently authenticated, so offer an explicit account merge:

This Microsoft sign-in is already connected to another Verbolus account.

Current account
  Maya · 86 games · 3 groups

Other account
  Maya R · 14 games · 1 group

Combining accounts cannot be automatically undone.

[ Review combined account ]
[ Cancel ]

The review includes duplicate-play handling, groups, display-name choice, and membership/billing impact. When duplicate Dailies exist, say plainly that the first completed result remains official; do not describe the rule as “best score.” Rules:

  1. Keep the currently signed-in account canonical unless an active billing entitlement requires the other account to remain canonical.
  2. If exactly one account has an active subscription, preserve that account's canonical billing identity.
  3. If both have active subscriptions or incompatible billing records, block automatic merge and provide a support path. Never discard, duplicate, or transfer billing silently.
  4. Ask which display name to keep when both are nonempty and different.
  5. Combine all verified sign-in methods and prevent removal of the final one.
  6. Apply section 7's deterministic data rules.
  7. Record the merge and identity reassignment durably and idempotently.

6.12 Remove a sign-in method

  1. Show Remove only when at least one other usable verified method will remain.
  2. Require recent authentication using a method other than the one being removed when feasible.
  3. Confirm with explicit copy: Remove Google sign-in? This does not delete your Google Account. You can add it again later.
  4. Remove the external-identity mapping and update the account method list atomically or through a reconciled operation.
  5. Revoke/delete any Verbolus-held provider credential if one exists; ordinary authentication should avoid retaining provider access/refresh tokens beyond the OIDC session need.
  6. Show Google sign-in removed. with Add it again as a safe recovery action, not a client-only undo that bypasses provider authentication.
  7. Never allow removing the last method. Explain: Add another sign-in method before removing this one.

6.13 Change password

Only show this action when email and password is connected.

  1. Select Change password from Account.
  2. Explain before leaving Verbolus: Microsoft manages your password. You'll verify your email and choose a new password on the Verbolus sign-in page.
  3. Start a dedicated, server-bound password-management transaction and use Entra External ID's Microsoft-hosted self-service password reset (SSPR) experience. Require fresh proof; do not treat the current Verbolus cookie alone as authority to change a credential.
  4. The implementation must first prove the supported browser-delegated entry point in the configured tenant. Microsoft's current documented SSPR journey begins at the hosted sign-in page and its Forgot password? action. If Entra cannot directly enter that hosted journey, show the short instruction above and force the hosted login page rather than inventing a Verbolus password form.
  5. Do not use Microsoft Graph POST /me/changePassword in this architecture: it requires delegated Directory.AccessAsUser.All and would make Verbolus handle current/new password values. Adopting it would be a separate, explicit security-architecture decision, not a shortcut for this UI.
  6. Verbolus never renders current/new password inputs, logs password validation errors, or proxies password values through its backend.
  7. Return to Account on success or cancellation. Show Password changed. only if Entra provides a trustworthy success result for the dedicated transaction; an ordinary successful sign-in is not proof that the player used the reset link. Otherwise use neutral return copy.
  8. Existing sessions follow the chosen Entra/session revocation policy. At minimum, rotate the current Verbolus session after a proven change. Provide Sign out other devices only after a real server-side session registry exists.

6.14 Forgot password and signed-out recovery

  1. On the Entra email/password screen, select Forgot password?.
  2. Entra performs account discovery, email verification, throttling, and reset.
  3. Responses must avoid useful account enumeration. Use generic copy when Verbolus displays an error: If that address can be recovered, follow the instructions sent to it.
  4. After reset, return through the normal validated callback and account-resolution flow.
  5. Preserve the original Verbolus return path, but never put email or reset state in the URL.
  6. If the user normally signs in through Google/Microsoft/Facebook, direct them to that provider's recovery flow; Verbolus cannot reset those credentials.
  7. Support must never transfer an account based only on display name, claimed email, receipt image, cookie value, or player ID.

Recovery scenarios:

  • lost one provider but another linked method works: sign in with the working method, then remove or replace the inaccessible one;
  • inaccessible local email but a social method works: sign in socially, add and verify a new local method, then remove the old method;
  • only provider is inaccessible: use that provider's recovery; no manual Verbolus bypass;
  • deletion is scheduled but not executed: sign in, reauthenticate, and cancel deletion;
  • deletion completed: old data is not recoverable; create a new account.

6.15 Change email address for the local method

Model this as replacement of a verified sign-in method, not an unverified profile edit.

  1. Select Change sign-in email.
  2. Require recent authentication.
  3. Verify the new email through Entra before it becomes usable.
  4. Keep the old email method until the new method is confirmed.
  5. Once confirmed, replace/remove the old method and rotate the current session.
  6. If the new identity belongs to another account, use the explicit account-merge flow.

6.16 Edit display name

  1. Profile shows the current name and the existing explanation, Used in groups and leaderboards.
  2. Saving is allowed for guests and accounts; it does not require reauthentication.
  3. Trim and validate server-side; maximum 32 characters.
  4. Update current group/member/standings projections through the existing authoritative update mechanism so old snapshots do not remain indefinitely.
  5. Show inline validation and an announced success message.
  6. A later moderation/reporting policy may restrict names, but do not silently replace a rejected name with a provider's real name.

6.17 Session expiry

The deployed cookie policy and game recovery behavior are documented in Expired account session recovery. The following describes the original design proposal.

  1. Verified sessions use an explicit idle and absolute lifetime, with server-side rotation. A reasonable starting policy is 30-day idle and 90-day absolute expiry, subject to the security implementation's final review.
  2. Sensitive actions require authentication within the preceding 15 minutes.
  3. When a session expires, retain a non-sensitive indication that this installation previously used an account and show: Your session expired. Sign in again to access your saved Verbolus account.
  4. Do not silently mint a new guest identity and make the scorecard appear erased.
  5. Offer Sign in again and an explicit Continue as a guest choice.
  6. Starting guest play creates a new guest profile and never copies account data out of the expired session.

6.18 Sign out of this device

  1. Select Sign out of this device.
  2. Confirm only when the consequences need explanation: Your account and saved progress will remain. This device will start a new guest profile.
  3. Revoke/delete the Verbolus BFF session and refresh material for this device.
  4. Replace the account cookie with a new signed guest profile cookie; do not reuse the canonical account's playerId as a guest.
  5. Detach installation-scoped push subscriptions as specified by notification policy.
  6. Do not globally sign out of Google, Microsoft, or Facebook.
  7. Return home with Signed out on this device.

6.19 Switch account

  1. Select Switch account.
  2. Explain: You'll choose another Verbolus account for this device. Your current account remains unchanged.
  3. Start an OIDC flow that asks Entra/provider to select or authenticate an account rather than automatically reusing the current identity when technically possible.
  4. Keep the current Verbolus session until the replacement authentication succeeds.
  5. On cancel/failure, restore the current account unchanged.
  6. On success, replace the local Verbolus session with the selected canonical account.
  7. Do not merge the two signed-in accounts. Account merging occurs only through the explicit sign-in-method collision workflow.

6.20 Export data

Guests and verified users retain the existing export capability.

For verified accounts, export must include data owned through merged aliases, linked-provider metadata appropriate for the user (friendly provider, masked identifier/link date; never tokens), merge history needed to explain provenance, and future billing metadata required by the privacy policy. A merge is incomplete if exported/source play history disappears merely because play documents still carry an old userId.

Sensitive export from a verified account requires recent authentication. Generate bounded exports; move to an asynchronous expiring download if data volume outgrows a request.

6.21 Delete guest data

  1. Retain the existing Delete my Verbolus data action.
  2. Preview saved plays, scorecard, streaks, groups, and settings to be removed.
  3. Require typed DELETE confirmation.
  4. Explain that clearing cookies is not equivalent to server deletion.
  5. Delete/reconcile plays, profile, group memberships/ownership according to existing rules, and issue a new empty guest cookie.
  6. Once the irreversible request is accepted, there is no undo. Show completion only after the deletion operation reaches its committed checkpoint.

6.22 Delete a verified account without an active subscription

  1. Select Delete Verbolus account from the danger zone.
  2. Require recent authentication with a connected method.
  3. Offer Download my data before confirmation.
  4. Explain exactly what is deleted:
  5. plays, scorecard, statistics, streaks, display name, settings;
  6. group memberships and applicable ownership handling;
  7. Verbolus sign-in-method links and Entra customer account(s) controlled by Verbolus;
  8. installation/notification records and future non-required account data.
  9. Explain what is not deleted: Google, Microsoft, or Facebook accounts themselves; legally required security/audit/financial records retained under a documented policy.
  10. Require typed DELETE and a final destructive button labelled Delete Verbolus account.
  11. Create an idempotent durable deletion operation, revoke active Verbolus sessions, and cross the irreversible checkpoint only after the request is recorded.
  12. Delete every alias/source profile and all linked identity lookups; do not leave a merged profile accessible through an old cookie.
  13. Delete or disable the corresponding Entra customer identities so a later authentication cannot silently resurrect the deleted profile.
  14. Pseudonymize retained audit references and set explicit retention expiry.
  15. Return to a new guest state with Your Verbolus account was deleted.

There is no undo after the final request is accepted. The deliberate review, reauthentication, typed confirmation, and durable checkpoint are the undo boundary.

6.23 Delete a verified account with an active or prepaid subscription

Default policy:

  1. Explain the current paid-through date.
  2. Schedule deletion cancels renewal immediately and schedules account deletion for the end of the paid period so the player receives the benefit already purchased.
  3. While scheduled, show a persistent account notice with effective date, Cancel deletion, Download my data, and Delete now instead.
  4. Cancel deletion requires recent authentication and cancels only the deletion request; renewing the subscription remains a separate explicit Stripe action.
  5. Delete now instead requires another clear confirmation, ends Verbolus access/entitlements, and starts immediate deletion. Refund rights and support contact must be explained according to the published billing/refund policy.
  6. At effective deletion, remove/anonymize Verbolus data. Stripe may retain legally required transaction/tax records; minimize and pseudonymize Verbolus-side linkage rather than promising that payment records outside Verbolus are erased.

If product/legal review chooses a different cancellation policy, update the UI, Stripe configuration, privacy policy, terms, and tests together. Do not ship ambiguous behavior.

7. Deterministic migration and account-merge rules

These rules must live in one testable domain service and be shown accurately in the preview.

7.1 Canonical identity

  • Guest promotion keeps the existing guest playerId.
  • Signing into an existing account keeps the existing account's playerId.
  • When linking collides with another account, keep the current account canonical unless billing requires the other account; record the choice and aliases.
  • Never choose canonical identity based on newest email, provider, browser, or lexicographic ID.

7.2 Plays and statistics

  • Preserve all source play records for export/audit until the relevant retention policy expires.
  • Deduplicate by the game-owned logical puzzle identity, currently puzzleKey. A Daily puzzle contributes at most one completed play to statistics, streaks, scorecards, and standings.
  • If one record is completed and the other is in progress, the completed record is authoritative.
  • If both are completed, the earliest immutable completedAt is authoritative. Do not choose by score: Letter Golf is lower-score-wins, and selecting a preferred result would make merging a way to shop multiple guest attempts.
  • Add completedAt to persisted plays, assign it server-side only on the transition to Completed, and never accept or later change it from client input. For legacy records, fall back to updatedAt; if still tied/unknown, prefer the pre-merge canonical target's record and then ordinal playKey ({puzzleKey}|{userId} today) as the final deterministic fallback.
  • Combine eligibility flags conservatively. If any duplicate says solutions were viewed before completion, the merged logical play remains excluded from stats/streaks.
  • Preserve the non-authoritative record as superseded merge provenance for export/support/deletion, with an exclusion reason. It never contributes to aggregates, standings, or resumed play.
  • If both records are in progress, retain the pre-merge canonical target's state; if there is no canonical-target record, use the oldest createdAt and ordinal playKey fallback. Do not fabricate a union of two word lists.
  • Practice puzzles with distinct puzzle IDs remain distinct.
  • Recompute statistics and streaks chronologically from the deduplicated authoritative play set. A qualifying gameType + scope + puzzleDate contributes once, so overlapping devices never double-count a day and non-overlapping dates extend the combined streak normally.
  • All normal reads, scorecards, export, and deletion must resolve aliases. Merely recomputing aggregates while leaving source plays invisible to the canonical account is not sufficient.

7.3 Groups

  • Union memberships.
  • If both profiles belong to one group, retain one canonical membership.
  • Transfer source ownership to the canonical account.
  • If both memberships have distinct display snapshots, update to the chosen canonical display name.
  • Reconcile standings so the same person does not occupy two leaderboard rows after merge.
  • Never reveal private group names from one account until both accounts are authenticated and the merge preview is authorized.

7.4 Settings

  • For guest import into an existing account, the existing account's explicit settings win.
  • Fill only truly unset settings from the guest profile.
  • For a brand-new account promoted from a guest, guest settings are preserved.
  • Display-name conflicts require an explicit choice.
  • Consent does not automatically broaden during merge. Use the most privacy-preserving applicable state and let the player change it later.
  • Installation-local choices remain installation-local.

7.5 Sign-in methods and billing

  • Union verified methods after explicit account-merge confirmation.
  • A provider identity may map to only one canonical account after reconciliation.
  • Never use email equality as a merge rule.
  • One active Stripe customer/subscription maps to one canonical account.
  • Two active billing identities block automatic merge and require support resolution.

7.6 Concurrent merges and alias-graph safety

  • Resolve the current roots, then serialize a merge with renewable, ETag-guarded leases on both the source and target canonical root records, owned by the durable operation ID. Acquire them in ordinal playerId order, release an owned partial acquisition before retrying, and re-resolve both roots after acquiring them. This prevents both same-target lost updates and reciprocal A → B/B → A alias cycles.
  • Store lease owner, acquisition time, and expiry; never use an unbounded Boolean lock that can remain stuck after a crash. Renew during work and clear only a lease still owned by the operation.
  • A live competing required lease produces internal merge_account_busy (409 plus Retry-After). The BFF retries the same operation with bounded jitter while the UI remains on Combining your progress….
  • After acquiring both leases and revalidating the roots, re-read the canonical target, all aliases already merged into it, and the new source closure. Recompute plays/stats from that complete fresh union so a second near-simultaneous merge includes the first one's data.
  • Recompute the preview's material decision fingerprint. If the prior merge changed a duplicate winner, display-name decision, billing/canonical choice, or another user-visible conflict, return to needs-account-decision with a refreshed preview. Count-only changes may proceed without a new confirmation.
  • Save the target with ETag protection and re-read/recompute on conflict while the operation still owns both leases. Release or renew a lease only through a matching operation ID.
  • A crashed holder is recovered after lease expiry from its durable operation state. Same-operation retries converge; a source already merged elsewhere is a hard conflict, never an alias fork.
  • Ordinary plays may finish during a merge. Do not block gameplay; reconcile after the safe checkpoint so late plays appear once in the alias-aware canonical result.

8. Error, interruption, and edge-case matrix

Situation Player response System behavior
User cancels Entra/provider Sign-in canceled. Your progress is unchanged. Discard transaction; preserve current session/cookie
State/nonce/PKCE invalid We couldn't complete sign-in. Please try again. No identity change; security telemetry without token/PII
Auth transaction expired That sign-in attempt expired. + Try again Start a new transaction; never replay callback
Provider unavailable Google sign-in is temporarily unavailable. Try another method. Keep current state; provider-specific circuit/telemetry
Callback succeeds but backend unavailable You're signed in, but we couldn't finish connecting your progress. Retain resumable operation; no data deletion
Identity lookup race Neutral processing/retry UI Conditional create/idempotency; one canonical owner wins
Merge operation retried Same operation status Idempotent no-op/resume; never double-count
Display names conflict Ask which one to keep No silent overwrite
Duplicate Daily plays Explain that the first completed result remains official Earliest completedAt wins; other is preserved as superseded and excluded
Another merge holds a required account lease Continue showing Combining your progress… Retry the same operation after Retry-After; refresh preview only if material decisions changed
Add method already on same account Already connected. Idempotent success
Add method belongs to other account Account-merge preview No silent reassignment
Remove last method Inline explanation Reject server-side even if client bypassed
Password reset email delayed Entra recovery guidance No custom credential handling
Session expires during form Preserve non-sensitive form data; reauthenticate Resume action only after CSRF/session validation
Switch-account authentication canceled Account switch canceled. Keep original account session
Deletion job partially fails Deletion is still being completed. Durable retry/reconciliation; sessions stay revoked
Deleted identity signs up later New-account experience Never restore deleted player data
Facebook disabled after being linked Existing linked users can still sign in during deprecation window or must first add another method Never strand an account; removal plan required before provider shutdown
MSA spike cannot authenticate personal accounts Do not display Microsoft button Block required-provider launch or explicitly renegotiate scope; do not substitute workforce federation
Microsoft account chooser/passkey auto-selects the wrong personal MSA via an existing browser session Player must manually pick Use another account on Microsoft's own screen Known Microsoft-hosted limitation, not app-controllable; External ID's user-flow-based custom OIDC configuration has no field to force prompt=select_account on the upstream authorize request (that level of control needs Identity Experience Framework/custom policies, which External ID/CIAM does not support). Not a launch blocker.

All API errors use stable machine-readable codes and safe ProblemDetails. UI maps codes to useful copy. Never display stack traces, raw provider errors, issuer, subject, tenant IDs, client IDs, tokens, or internal player IDs.

9. Password and account security requirements

  1. Use authorization code + PKCE with validated state and nonce.
  2. Keep ID/access/refresh tokens server-side; never expose them to client JavaScript or local storage.
  3. Entra owns passwords, verification, lockout, risk controls, and password recovery.
  4. Configure Entra's current recommended password and smart-lockout protections. Do not create a weaker parallel password policy in Verbolus.
  5. Rate-limit auth start/callback completion, link, unlink, merge preview/commit, recovery initiation, session refresh, export, and deletion according to their abuse profiles.
  6. Require recent authentication (initially 15 minutes) for:
  7. adding/removing a sign-in method;
  8. changing password or sign-in email;
  9. account-to-account merge;
  10. beginning subscription checkout;
  11. opening billing management;
  12. exporting verified-account data;
  13. scheduling/canceling/immediately executing deletion.
  14. Protect cookie-authenticated mutations with explicit CSRF defenses in addition to intentional SameSite, Secure, and HttpOnly cookie settings.
  15. Validate return URLs against a same-origin allowlist; never accept arbitrary callback or post-auth redirects.
  16. Rotate verified sessions at sign-in, privilege/identity-method change, password change, and recovery. Prevent session fixation.
  17. Do not add Sign out all devices until sessions are individually registered and revocable.
  18. Do not claim MFA or passkey support until it is configured and tested end to end. Keep the UI model extensible so a future passkey is another sign-in method.
  19. Log security events with correlation IDs and provider category only. Exclude email, display name, subject, full IP where unnecessary, tokens, cookies, authorization codes, and password data.

10. Privacy and social boundaries

  • Update Privacy and Terms before public rollout to disclose Entra and enabled providers, stored identity metadata, account merge, retention, export/deletion behavior, and Stripe when applicable.
  • Collect only authentication scopes. Google, Microsoft, and Facebook sign-in do not grant Verbolus contact/friend access.
  • Do not build “Invite Facebook friends,” address-book upload, WhatsApp contact import, wall posting, or automatic social posting.
  • Keep groups private and invitation-based. Identity-provider account details never become a public profile.
  • Continue explicit native result sharing. The player chooses the destination in the OS/browser share sheet.
  • Display names are user-generated content. Normalize and validate them, and retain the existing plan for reporting/profanity/impersonation controls before profiles become more public.
  • Account and consent surfaces never contain advertisements.

11. Accessibility and responsive behavior

Target WCAG 2.2 AA.

  • Entra branding and custom CSS must preserve keyboard operation, visible focus, zoom/reflow, high-contrast behavior, provider-button names, and error associations.
  • Verbolus dialogs use Radix primitives with initial focus on the heading or safest action, Escape behavior where safe, focus return to the invoker, and no destructive action as default focus.
  • Merge summaries use real lists/tables with textual labels, not color alone.
  • Async auth/merge/deletion status uses a restrained role=status live region; errors receive focus at the summary and remain associated with fields.
  • Buttons use exact action labels (Keep this progress, Start fresh, Delete Verbolus account), not ambiguous Continue where consequences differ.
  • Support 320 CSS-pixel width, 200% zoom, light/dark themes, reduced motion, keyboard-only use, and screen readers.
  • Localize visible/authentication copy, accessible names, errors, dates, counts, and pluralization. Use Intl for the 30-day import and deletion dates.

12. Telemetry and supportability

Recommended events, all free of direct PII:

  • account_prompt_shown/dismissed/accepted with prompt reason;
  • auth_started/completed/canceled/failed with provider category and safe error code;
  • guest_import_previewed/kept/deferred/canceled with count buckets, not group names;
  • merge_started/completed/failed/reconciled with opaque operation correlation;
  • signin_method_add_started/completed/canceled/collision;
  • signin_method_removed;
  • reauth_started/completed/failed with action category;
  • signout_completed, account_switch_completed/canceled;
  • deletion_scheduled/canceled/started/completed;
  • recovery entry and completion category without email.

Do not measure passwords, provider tokens, authorization codes, email addresses, display names, group names, raw player IDs, issuer/subject, or merge source/target IDs in analytics. Protected operational logs may use a one-way/correlated internal identifier when necessary for support.

13. Backend and data implementation instructions

13.1 Contracts and services

  1. Keep HTTP endpoints thin. Put account resolution, sign-in-method policy, merge conflict rules, session policy, and deletion orchestration in testable services.
  2. Extend the current internal identity foundation rather than introducing a client-trusted identity route. The Next.js BFF validates OIDC and authenticates to /v1/internal/identity/* using the existing app-role/managed-identity boundary.
  3. The acting source player always comes from the signed browser cookie forwarded by the BFF, never a JSON playerId supplied by browser code.
  4. Replace any internal API contract that returns raw target player IDs to browser code with an opaque server-side transaction/operation ID. Raw IDs may remain between trusted BFF/backend components only.
  5. Add an account summary contract containing auth state, display name, safe sign-in-method summaries, deferred-import status, deletion status, and future entitlement summary.
  6. Add durable auth/account-operation records for guest import, account merge, identity reassignment, and deletion. Each has operation ID, type, source/target references, state, timestamps, version, error/retry metadata, and idempotency key.
  7. Make every mutating endpoint cancelable, idempotent where retried, CSRF-protected at the browser boundary, rate-limited, and represented in OpenAPI where public contracts apply.

13.2 Identity storage

  1. Continue using issuer + subject as the stable external-identity key.
  2. Add provider category, masked-display metadata, linked timestamp, last-used timestamp, and method status without storing unnecessary provider profile data.
  3. Enforce one external identity to one canonical account using conditional create/ETag semantics.
  4. Allow one player to own multiple external identities.
  5. Never store social-provider access to contacts/files or long-lived tokens unless a future feature separately justifies and secures them.
  6. Treat email as mutable display/recovery metadata, never as the identity lookup key.

13.3 Merge foundation gap to close

The current branch recomputes target aggregates from both players and leaves source play documents under the source user ID while marking the source profile as merged. Before releasing migration:

  • define canonical reads through a bounded alias set or physically migrate/recreate play documents;
  • ensure scorecard/history, duplicate-Daily rules, exports, deletion, group standings, and future recomputation see the same authoritative play set;
  • ensure a stale source cookie resolves safely to the target or is rotated;
  • add a reconciler for best-effort group/lookup writes;
  • never declare merge complete while source history is invisible to the canonical account.

Implement completedAt, the first-completion duplicate resolver, superseded-play provenance, and the renewable ordered root-pair operation leases from section 3a of doc/accounts-and-subscriptions-plan.md. The current aggregate recomputation concatenates source and target completions, so it will double-count a shared puzzleKey until it first constructs the deduplicated authoritative play set. Its current target ETag retry protects one player-document write but does not serialize two distinct merges or force the second merge to include aliases from the first; both behaviors must be closed before rollout.

13.4 Deletion

Deletion is a durable operation, not a chain of best-effort request writes. It must enumerate and reconcile canonical profile, aliases, plays, groups/ownership, standings, lookup records, auth methods/Entra objects, sessions, installation records, notifications, deferred imports, billing records subject to retention, and audit pseudonymization.

14. Next.js BFF and frontend implementation instructions

  1. Prefer Server Components and server-only modules for account state and auth orchestration. Keep provider tokens and internal app-role credentials out of client bundles.
  2. Suggested BFF routes/actions (exact naming may follow established conventions):
  3. GET /api/auth/start;
  4. GET /api/auth/callback;
  5. POST /api/auth/account-decision;
  6. POST /api/auth/link/start;
  7. POST /api/auth/unlink;
  8. POST /api/auth/sign-out;
  9. POST /api/auth/switch/start;
  10. POST /api/auth/reauth/start;
  11. status routes for opaque merge/deletion operation IDs.
  12. Use server-set HttpOnly cookies. Do not put OIDC tokens, source/target IDs, merge authorization, or provider identity in local storage or query parameters.
  13. Preserve only validated same-origin return paths.
  14. Add explicit loading, success, empty, expired, canceled, and recoverable error UI for every route.
  15. Use one account-state loader so header/menu, Settings, Support, and prompts do not disagree.
  16. Do not personalize from a shared Next.js cache. Account responses are private/no-store.
  17. Extend existing design language: narrow 600px account/settings column, bordered cards, restrained blue actions, destructive red only in the danger zone, light/dark support, and 44px targets.

15. Entra and provider configuration checklist

  1. Tenant-facing name is Verbolus.
  2. Configure logo, favicon, colors, Privacy URL, Terms URL, sign-in page text, and supported locales.
  3. Enable email with password and self-service password reset.
  4. Configure Google and validate production consent/redirect domains.
  5. Configure and prove personal Microsoft MSA end to end. Test Outlook.com/Hotmail and a personal Microsoft account that also belongs to an organization to catch account-choice ambiguity.
  6. Configure Facebook only when approved. Entra user-flow/provider configuration is the authoritative switch for whether its hosted button appears; an application feature flag alone cannot hide a provider after redirect. If staged rollout needs both variants, use a tested provider-specific flow/application arrangement rather than showing a dead button.
  7. Collect Display Name during sign-up with Verbolus-specific help text and 32-character-compatible validation.
  8. Minimize claims/scopes and verify the idp/identity-source information needed for friendly method labels.
  9. Register exact local/staging/production redirect and post-logout URIs. No wildcard redirect URIs.
  10. Test cancel, denial, bad state, reset, link, unlink, SSO reuse, account selection, sign-out, and provider outage behavior.
  11. Do not make a custom login domain a launch blocker; track it as a separate trust/branding enhancement.

16. Implementation phases

Each phase ends with executable checks and a deployable/rollback-safe state. Do not expose UI before its complete backend path is feature-flagged and safe.

Phase 0 — provider and UX proof

  • Prove hosted email/password, Google, personal Microsoft MSA, and optional Facebook.
  • Finalize branding, Display Name collection, password reset, callback claims, and provider labels.
  • Record screenshots and claim samples with secrets/tokens removed.
  • Resolve whether app-level linking can reuse one Entra customer object or will map multiple Entra subjects to one Verbolus account. The Verbolus model must support either.

Exit: all required provider flows work in a non-production environment; MSA is truly personal MSA.

Phase 1 — account/session read model

  • Implement verified session payload/rotation/expiry and account-state contract.
  • Preserve anonymous cookies and backward compatibility.
  • Add guest/verified/session-expired Account UI behind a feature flag.
  • Add server-only OIDC transaction storage and callback validation.
  • Implement the section 6.2.1 prepare/pause/commit protocol. The callback must be able to finish cryptographic authentication, redirect to /account/finish without minting a verified cookie, and resume from an opaque pending attempt after the player's decision.

Exit: sign-in resolves an identity without yet mutating guest data; negative auth tests pass.

Phase 2 — account creation and guest migration

  • Implement promotion, meaningful-data detection, merge preview, keep/start-fresh/cancel, deferred import, operation status, alias-aware reads, and reconciliation.
  • Implement explicit Display Name conflict choice.
  • Update scorecard/export/group behavior for aliases and duplicate Daily rules.

Exit: cookie-only users can create/sign into accounts without silent data loss.

Phase 3 — multiple sign-in methods

  • Implement safe method summaries, add/link, idempotent already-linked handling, last-method guard, remove, change password/email handoffs, and account-collision merge.
  • Add billing-aware canonical selection even if billing is not enabled yet; inactive/default state is sufficient for this phase.

Exit: every required provider can be added to an existing account and used for a later sign-in.

Phase 4 — sessions, sign-out, switch, recovery

  • Implement recent-auth policy and continuation.
  • Implement local-device sign-out and deliberate switch-account behavior.
  • Complete password/provider recovery copy and session-expiry UX.

Exit: shared-device and expired-session journeys do not leak or appear to lose account data.

Phase 5 — export, deletion, privacy, operations

  • Implement alias-complete export and durable verified-account deletion.
  • Implement subscription-aware scheduled deletion state even if subscription activation follows.
  • Update Privacy, Terms, support runbook, telemetry, and reconciliation alerts.

Exit: deletion/export cover canonical and merged data; Entra mappings cannot resurrect deleted data.

Phase 6 — controlled rollout

  • Target internal accounts/installations with existing feature flags.
  • Run provider and merge smoke tests in staging and production configuration without real user data.
  • Expand through small stable cohorts; monitor auth completion, merge failures, account collisions, recovery, session loops, and support contacts.
  • Keep a server-side kill switch that hides account entry points without invalidating existing users' ability to sign in/manage/delete their accounts.

17. Test and acceptance matrix

17.1 Backend unit tests

  • session sign/verify/expiry/rotation and legacy-cookie compatibility;
  • external-identity uniqueness and multi-method rules;
  • meaningful guest-data detection;
  • promote vs merge vs deferred import;
  • completed-over-in-progress, earliest-completedAt, legacy fallback, eligibility taint, and superseded-provenance duplicate resolution;
  • chronological deduplicated streak recomputation;
  • group/member/owner deduplication;
  • settings/display-name conflict rules;
  • canonical selection with zero/one/two active billing identities;
  • last-method removal rejection;
  • durable operation idempotency and state transitions;
  • ordered root-pair lease acquire/partial release/renew/expire/owner-only release and reciprocal merge-cycle prevention;
  • material preview-fingerprint change versus harmless count-only rebase;
  • deletion enumeration and retry behavior.

17.2 Backend integration/Cosmos tests

  • BFF app-role required for every internal identity endpoint;
  • acting player comes from signed cookie, not request body;
  • invalid/unsigned-forged cookies rejected according to rollout policy;
  • identity link race produces one owner;
  • merge retry after failure does not double-count;
  • two different sources racing into one target serialize, and the second recomputes from the target's full alias set;
  • reciprocal A → B and B → A merge attempts cannot create an alias cycle;
  • a live required lease returns merge_account_busy with Retry-After; an expired lease is safely taken over;
  • same-source/same-target retries converge while same-source/different-target is rejected;
  • a concurrent first merge that creates a new duplicate-play conflict forces the second preview to be reconfirmed;
  • alias-aware scorecard, export, and delete include source plays;
  • group owner/membership/standings reconciliation;
  • CSRF, authorization, rate limit, validation, and safe ProblemDetails negatives;
  • deleted Entra identity mapping cannot resolve old account.
  • callback prepare is non-mutating and leaves the original cookie unchanged;
  • a decision-required callback cannot access account-only endpoints before commit;
  • pending attempt is bound to source cookie/installation, one-time, expiring, CSRF-protected, and safe under replay;
  • verified authLevel is minted only after commit's safe checkpoint;
  • stale preview produces a refreshed decision instead of silently committing changed data.

17.3 Frontend component tests

  • guest and verified Account screens;
  • provider list, masking, add/remove/last-method states;
  • meaningful merge summaries and all three decisions;
  • Display Name conflict selection;
  • loading, canceled, expired, retrying, failed, and completed status;
  • reauth continuation;
  • sign-out and switch-account confirmation/cancellation;
  • deletion without/with subscription;
  • keyboard focus, live-region announcements, accessible names, and error association.

17.4 Playwright critical journeys

  1. New visitor plays, creates email/password account, chooses Keep, and retains score/streak/group.
  2. New visitor plays, creates Google account, chooses Start fresh, then imports within 30 days.
  3. Existing account signs in on a guest device and merges progress.
  4. Existing account chooses account-only, then later imports deferred progress.
  5. Email/password account adds Google and signs in with Google after signing out.
  6. Google account adds personal Microsoft MSA and signs in with Microsoft.
  7. Adding a provider already owned by another account produces explicit account merge.
  8. Remove a method; attempt to remove final method is blocked server-side and in UI.
  9. Forgot password returns to the intended Verbolus route.
  10. Expired session does not show an empty scorecard; reauthentication restores account.
  11. Switch account cancel keeps original session; successful switch does not merge accounts.
  12. Merge interrupted mid-operation resumes without duplicate stats.
  13. Two devices confirm merges into the same target together; both sources appear once and neither sees a raw 409.
  14. A concurrent merge changes which duplicate Daily is first; the affected finish screen refreshes and requests reconfirmation.
  15. Guest deletion and verified deletion remove all relevant data, including superseded duplicates.
  16. Active subscriber schedules deletion and can cancel it before the effective date.
  17. Provider outage/cancel/bad callback preserves current profile.

Run desktop and mobile viewports, keyboard-only navigation, automated accessibility checks, and a manual screen-reader pass. Test light/dark, 200% zoom, reduced motion, a long localized string set, and at least one non-English locale.

17.5 Required validation commands

Run focused tests first, then the repository checks relevant to all touched surfaces. Do not claim a check passed unless it ran successfully.

dotnet restore .\MiniGamesBackEnd\MiniGamesBackEnd.csproj
dotnet build .\MiniGamesBackEnd\MiniGamesBackEnd.csproj -c Release --no-restore
dotnet test -c Release --no-build

npm ci --prefix .\frontend\minigames
npm run lint --prefix .\frontend\minigames
npx --prefix .\frontend\minigames tsc --noEmit
npm run build --prefix .\frontend\minigames

terraform -chdir=tf fmt -check -recursive
terraform -chdir=tf init -backend=false
terraform -chdir=tf validate

18. Agent handoff instructions

18.1 Rules for every implementation agent

Before editing:

  1. Read repository AGENTS.md and the matching .github/instructions/*.instructions.md files.
  2. Read this document, doc/accounts-and-subscriptions-plan.md, and the relevant sections of doc/engagement-platform-plan.md.
  3. Inspect git status; the working branch contains active user work. Preserve it. Never reset, discard, reformat, or overwrite unrelated changes.
  4. Inspect the smallest owning implementation, neighboring tests, public contract, and Terraform configuration before proposing an abstraction.
  5. Implement one phase or one clearly bounded slice at a time. Feature-flag incomplete public UI.
  6. Add executable regression checks with each behavior change.
  7. Report assumptions, files changed, tests run, failures, security/privacy implications, and the next safe slice.

Do not deploy, run Terraform apply, mutate Entra/Stripe/Azure production resources, publish images, or create production secrets without explicit user approval and reviewed targets.

18.2 Work reserved for Opus/Sonnet-class agents

Assign security-sensitive or cross-boundary work to Opus/Sonnet:

  • OIDC/MSAL/BFF transaction and callback implementation;
  • verified-session cookie design, rotation, expiry, CSRF, and recent-auth policy;
  • Entra provider configuration design, especially personal Microsoft MSA validation;
  • external-identity/account data model and lookup uniqueness;
  • guest promotion, account merge, aliases/play ownership, conflict rules, durable operations, and reconciliation;
  • first-completion play deduplication, immutable completion timestamps, ordered root-pair merge leases, alias-cycle prevention, and material preview fingerprints;
  • account-to-account merge and billing-aware canonical selection;
  • password/email-method linking semantics;
  • durable export/deletion and Entra/Stripe coordination;
  • Terraform, managed identity, app roles, secrets, and rollout architecture;
  • threat model, API contracts, authorization negatives, and end-to-end test architecture.

Give one lead agent ownership of contracts and merge/session invariants. Do not let multiple agents invent competing identity models or edit the same central files concurrently.

Suggested lead prompt:

Implement Phase N of doc/accounts-identity-ux-implementation-plan.md on
feat/accounts-identity-foundation. Treat its locked decisions, state model, workflow, conflict
rules, security requirements, and acceptance tests as requirements. Read AGENTS.md and all
matching .github/instructions first. Preserve existing dirty work. Inspect the current foundation
before editing and make the smallest coherent, backward-compatible slice. Keep OIDC/provider
tokens server-side, keep acting player identity cookie-derived at the internal API boundary, and
do not trust browser-supplied player IDs. Add focused tests, run affected validation, review the
diff, and report any requirement that the current architecture cannot safely satisfy.

18.2.1 Immediate Opus/Sonnet handoff: callback completion seam

The current branch has the BFF-to-backend app-role client and internal link, merge-preview, and merge endpoints. The next lead-agent slice is specifically:

  1. Implement the versioned signed-cookie payload and authLevel parsing/policy with legacy cookie compatibility.
  2. Implement OIDC start/callback validation server-side.
  3. Add the non-mutating prepare and idempotent commit layer in section 6.2.1 around the current link/merge foundation.
  4. Add /account/finish as a server-loaded state screen. It must support:
  5. new identity + meaningful guest data: Keep / Start fresh / Cancel;
  6. existing identity + meaningful guest data: Add progress / Use account only / Cancel;
  7. display-name conflict choice;
  8. expired, stale-preview, processing, recoverable-failure, and completed states.
  9. Keep the original cookie active during the pause and mint authLevel=verified only after commit.
  10. Use an opaque attempt plus an HttpOnly pending cookie; no raw player IDs or provider identity in the browser.
  11. Add integration and Playwright coverage proving the pending state cannot read the target account or accidentally complete sign-in.

This slice owns the seam between “Entra proved who this is” and “Verbolus has safely decided which player profile this session represents.” Do not let the callback call the current mutating /link endpoint before a required user decision.

Suggested focused prompt:

Implement the callback-to-completion seam in section 6.2.1 of
doc/accounts-identity-ux-implementation-plan.md. The existing BFF app-role client and internal
identity endpoints are foundation, but /link currently mutates too early for Keep vs Start fresh.
Add a non-mutating prepare disposition and idempotent commit, a short-lived server-bound pending
attempt, the /account/finish decision states, and a versioned cookie whose authLevel becomes
verified only after commit reaches its safe checkpoint. Preserve legacy anonymous cookie player
IDs and all active user work. Keep tokens and raw identity/player IDs server-side. Add focused
negative/replay/stale-preview tests and run backend, frontend, and affected infrastructure checks.

18.3 Work suitable for Haiku-class agents

Use Haiku only after contracts and states for the slice are frozen. Give it one bounded leaf task at a time, for example:

  • implement one presentational Account card from an existing typed DTO;
  • add one dialog's copy/states using existing callbacks;
  • add Testing Library cases for an already-implemented component;
  • add provider icons/labels using approved assets and existing button primitives;
  • update Privacy/Terms/Support copy from approved wording;
  • add Storybook-like fixtures if the repository adopts such a pattern;
  • run and report a defined lint/typecheck/test command;
  • perform a focused accessibility checklist against one completed screen.

Do not assign Haiku independent decisions about auth protocols, cookies, merge direction, identity uniqueness, account deletion, billing, Terraform, secrets, provider configuration, or security error handling.

Suggested bounded prompt:

Implement only [named component/test/copy task] from
doc/accounts-identity-ux-implementation-plan.md. The DTO, callbacks, state names, and copy in the
task are fixed; do not redesign authentication or add dependencies. Read AGENTS.md and the
matching frontend/testing/accessibility instructions. Preserve unrelated changes. Add/update the
focused component tests, run [exact commands], and report the files and results.

18.4 Review gates between agents

After every slice, the lead Opus/Sonnet agent reviews:

  • identity source and authorization boundary;
  • idempotency and failure checkpoints;
  • account/guest data-loss possibilities;
  • information leakage and account enumeration;
  • session fixation/CSRF/open redirect risks;
  • accessibility and localization of visible states;
  • contract compatibility and rollback;
  • whether tests prove the negative paths, not only success.

No later agent should proceed from an unreviewed central contract or a failing focused test suite.

19. Definition of done for the account release

The account release is done only when:

  • guest play remains fully functional;
  • email/password, Google, and personal Microsoft MSA work end to end; Facebook behaves correctly if enabled and is absent if disabled;
  • a player can add every enabled method to one existing Verbolus account;
  • no method is auto-linked by email and the final method cannot be removed;
  • cookie-only progress can be kept, deferred/start-fresh, canceled, or merged without silent loss;
  • duplicate Daily results, groups, display names, settings, aliases, exports, and deletion follow the documented deterministic rules;
  • password change and recovery stay entirely within Entra/provider-hosted flows;
  • session expiry, sign-out, and switching accounts cannot expose another user's data or impersonate an empty/lost account;
  • verified-account export and deletion cover canonical and merged data;
  • all sensitive actions require recent authentication and CSRF protection;
  • Privacy/Terms/support documentation matches actual behavior;
  • accessibility, localization, security negatives, focused tests, builds, and provider smoke tests pass;
  • feature flags and rollback preserve existing account holders' ability to sign in, export, manage methods, and delete even if new account creation is paused.

20. Immediate account-management and discoverability handoff

Status: locked near-term UI design for the branch following the identity foundation. This section refines sections 4, 5, 6.13, and 6.18 for the current implementation. It does not reopen the identity or merge architecture.

20.1 Current implementation facts

  • /account already distinguishes guest, expired, and verified cookies and forwards the cookie server-side for player/settings reads.
  • The verified Account client already contains method removal, add-method, switch-account, and sign-out behavior. Those controls are currently coupled in one SignInMethods component, which makes a failed or empty methods result look like a missing account UI.
  • /settings currently has an Account heading only for deletion. Its deletion explanation says on this device, which is accurate for a guest profile but not for verified deletion across the canonical account's merge-alias closure.
  • The desktop menu is already right-aligned with align="end"; retain and regression-test it rather than opening another implementation item.
  • Header Account visibility is feature-flagged and fetched after hydration, so a rollout-targeted user can briefly open the menu before the link appears.
  • Auth telemetry and the local-password implementation are active work elsewhere. This section defines their UI integration points but must not create a second event vocabulary or password implementation.

20.2 Information architecture decision

Use one full manager and one summary:

  • /account is the identity and current-device session control center: status, connected methods, local password action, add/remove method, switch account, and sign out.
  • Settings > Account is a concise status and method summary with a clear link to /account, plus the existing destructive deletion action at the bottom. Do not duplicate link/unlink/switch and password transaction logic inside settings-form.tsx.
  • Keep the page and section names Account; do not rename Settings or create Security for this release.
  • Do not put a direct Sign out command in the global hamburger menu. Menu → Account → Sign out is two deliberate actions, keeps the navigation menu stable for guests, and leaves enough room to explain that the device becomes a new guest profile.

20.3 Settings Account section

settings/page.tsx derives a small server-side account view model from the signed cookie and fetchPlayerMe, using the same cookie-forwarding pattern as /account. Pass only renderable status, provider category, masked label, and method count to the client form; do not pass raw player IDs, issuer/subject pairs, or provider tokens merely to render a summary.

For this branch, extend the existing Account section in place at the bottom of the long Settings form. Put status and method summary at the top of that section and keep deletion at the bottom of the page and section, separated by spacing, a border, and a Danger zone subheading. A later Settings-index refactor may move the Account navigation row without moving destructive actions into the middle of an ordinary preferences form.

Guest state:

Account

Playing without an account
Your progress is saved in this browser. Create an account to keep it if you change devices.

[ Create account or sign in ]

────────────────────────
Danger zone
Delete the Verbolus data saved for this guest profile.
[ Delete my Verbolus data ]

Verified state:

Account

Signed in as Maya
Your progress is saved to your Verbolus account.

Sign-in methods
Google                  ma•••@gmail.com
Email & password        ju•••@example.com

[ Manage account ]

────────────────────────
Danger zone
Permanently delete your Verbolus account and its saved plays, streaks, groups, and settings.
[ Delete Verbolus account ]

Expired state:

  • say Your session expired. Sign in again to access your saved Verbolus account.;
  • provide Sign in again and a secondary Continue as a guest;
  • do not render verified methods or account deletion from stale data;
  • preserve the prior-account hint without displaying an email address.

Failure rules:

  • Cookie/session status and method-fetch status are independent. If the cookie is verified but the method read fails, keep Signed in and show Sign-in methods are temporarily unavailable. plus Manage account; do not silently render the guest card.
  • An empty method array for a verified account is an invariant/error state, not No methods connected. Show the same unavailable state and emit the existing operational diagnostic.
  • Use Create account or sign in, not only Sign in, for a guest because the Entra page owns both.

20.4 /account verified layout

Split the current client component into independent visual/behavioral regions so one failed read cannot hide unrelated actions:

  1. Status — Signed in as Maya and Your progress is saved to your Verbolus account.
  2. Sign-in methods — one row/card per returned method, with friendly provider and masked label.
  3. Add a sign-in method — one full-width secondary action after the list.
  4. This device — Switch account and Sign out on this device.
  5. Privacy and data — a normal link to the Settings Account danger zone; do not duplicate the deletion dialog on both pages in this slice.

Method-row rules:

  • Local row label: Email & password; show Change password only on this row.
  • Google, Microsoft, and Facebook rows remain visible as connected methods, but receive no provider-specific password/profile-management UI.
  • Keep existing Remove behavior when another method remains. The final method explains why Remove is unavailable.
  • Method-list loading/failure/empty-invariant states occupy the list region only. Add/switch/sign-out availability derives from verified session state, not from methods.length.
  • Place success/error notices directly below the Account heading in an announced status region. Query-string messages must be consumed or replaced after display so refresh does not repeat a stale success message.

20.5 Sign out on this device

Use an outline/secondary button, not destructive red: sign-out does not delete the account.

  1. Player selects Sign out on this device.
  2. Show a confirmation dialog:
Sign out on this device?

Your Verbolus account and saved progress will remain. This device will start with a new guest
profile. This won't sign you out of Google, Microsoft, or Facebook.

[ Cancel ] [ Sign out ]
  1. Cancel closes the dialog without changing cookies or navigation.
  2. Confirm disables both actions, labels the primary action Signing out…, and posts to the current BFF sign-out route.
  3. On success, replace the verified cookie with a fresh anonymous profile exactly once, clear pending auth cookies, redirect to /, and announce Signed out. You're now playing as a guest.
  4. On failure, remain signed in, restore the actions, and show We couldn't sign you out. Please try again. Never navigate optimistically before the response succeeds.
  5. Switch account remains separate and uses the provider account picker. Do not implement switching as sign-out followed by ordinary sign-in, because provider SSO may immediately select the same account.

20.6 Local password action

Follow section 6.13 and the active password-work branch. The UI contract is:

  • render Change password only when at least one connected method has category Local;
  • use an ordinary secondary action within the Local row, not a page-wide danger action;
  • explain that Microsoft hosts the credential flow before redirecting;
  • preserve /account as the validated return path;
  • cancellation leaves the Verbolus session and methods unchanged;
  • never show success solely because a normal OIDC callback succeeded;
  • never add password fields, Graph password proxying, or Directory.AccessAsUser.All as an incidental UI implementation detail.

Before merge, prove the exact Entra browser-delegated journey with the configured customer tenant: local method detection, SSPR enabled, hosted reset link visible, cancellation, completed reset, return routing, and subsequent sign-in with the new password. If the platform exposes only the hosted Forgot password? entry, retain the Change password user intent but show the instructional interstitial from section 6.13.

20.7 Account discovery and guest prompts

Do not add an account banner to a first-time home page. The first visit should still answer one question—what can I play?—and account creation remains optional.

Use this discovery ladder instead:

  1. Persistent, quiet: Account appears in the menu whenever AccountsUi is enabled; Settings always includes the Account section.
  2. Intentional: Scorecard and Groups may show a small guest status card because visiting those surfaces demonstrates interest in saved history/social continuity.
  3. Contextual: after a completed puzzle, a meaningful streak, or successful group activity, show one dismissible prompt at the next natural pause—not over the board.
  4. Required later: subscription checkout asks for sign-in only when the player elects to begin an account-bound purchase.

The first contextual prompt may appear after the first completed saved game or on the next home visit, but never on the untouched initial home page. Recommended copy:

Keep your progress across devices
Create an account or sign in to keep your saved games and future streaks if you change devices.

[ Create account or sign in ]  [ Not now ]

Dismissal and frequency follow section 5. Do not add a prompt based only on cookie age, page views, or an arbitrary timer. Verified users never see guest prompts.

20.8 Header feature-loading decision

The alignment bug is complete: retain align="end" and add/keep a regression assertion.

For the Account-link flash, accept the brief fail-closed omission during targeted rollout rather than blocking or delaying the entire navigation menu. Once Accounts UI is released to everyone, remove the conditional link gating and the flash disappears. If the flag must remain targeted for a long period, seed HeaderMenu with server-evaluated features from dynamic pages; do not make static content pages wait on the backend merely to render their navigation.

20.9 Telemetry integration boundary

Sonnet's active auth-telemetry work owns event names and shared properties. UI implementation in this section must call that existing contract rather than introducing parallel trackEvent names. It needs to distinguish these product states:

  • entry surface: menu Account, Settings Account, Account page, contextual prompt, or required action;
  • user intent: start sign-in, add method, change password, switch account, sign out, or delete;
  • terminal outcome: completed, canceled, recoverable failure, blocked, or abandoned/expired where the server can authoritatively determine it;
  • prompt reason and dismissal, using fixed low-cardinality values.

Security/operation outcomes belong on the authoritative BFF/backend path and correlate with existing request/dependency traces. Browser-only impressions and clicks remain subject to analytics consent. Never include email/masked email, display name, issuer, subject, player ID, cookie, authorization code, tokens, password data, free-form provider errors, or return URLs in event properties.

20.10 Accessibility and failure acceptance

  • Account status, method-load errors, password returns, unlink results, and sign-out results use appropriate role="status" or role="alert" live regions without stealing focus.
  • Dialogs have a visible title/description, initial focus on Cancel for deletion and sign-out, Escape support, focus containment, and trigger focus restoration.
  • Method rows and actions remain usable at 200% zoom and narrow mobile widths; masked labels wrap rather than forcing horizontal scrolling.
  • Loading labels use the typographic ellipsis consistently and buttons cannot submit twice.
  • Provider/category labels are localized display strings; internal category values are never shown as fallback copy to players.

20.11 Required focused tests

Settings component/server tests:

  • guest, verified, expired, method-read failure, and verified-empty-invariant renderings;
  • guest versus verified deletion wording and button labels;
  • only the summary DTO reaches the client component;
  • Manage account and Create account or sign in destinations preserve safe return behavior.

Account component tests:

  • all supported method categories render friendly labels and masked values;
  • Local alone receives Change password;
  • method failure does not hide add/switch/sign-out controls;
  • last-method Remove explanation and multi-method Remove behavior;
  • sign-out confirmation cancel/success/failure/double-submit and focus restoration;
  • switch and sign-out remain distinct operations.

Navigation/prompt tests:

  • desktop menu remains end-aligned and mobile/desktop Account visibility agrees after flags resolve;
  • first untouched home visit has no account banner;
  • eligible guest prompt render/dismiss/suppression and verified-user exclusion;
  • no PII appears in UI telemetry calls or rendered signed-out states.

20.12 Immediate Opus/Sonnet implementation order

  1. Preserve the already-landed menu alignment and sign-out route fixes; verify deployment before duplicating them.
  2. Introduce the server-derived Settings account view model and render guest/verified/expired/error summaries with correct deletion copy.
  3. Refactor /account into independent Status, Methods, and This device regions; fix explicit method loading/error/empty states.
  4. Wire the active local-password work into the Local row after its Entra acceptance tests pass.
  5. Add the sign-out confirmation and success/failure experience around the existing BFF route.
  6. Integrate the existing telemetry contract at the defined intent/outcome points without renaming or duplicating Sonnet's events.
  7. Add contextual guest prompting only after the management surfaces are stable; do not block the branch on a first-home banner.
  8. Run focused Vitest/Testing Library tests, then lint, TypeScript, build, mobile/desktop keyboard checks, and a real Entra local-account password smoke test.