docs(auth): align duplicate-email and connect conflict docs

[cursor]

Summary

• Updated existing auth documentation to match merged behavior from fix: 409 for duplicate email connections.
• Kept changes documentation-only and focused on clarifying canonical-user resolution and typed conflict contracts.

Docs updated

• docs/features/password-auth-flow.md
  • Corrected stale identity-model caveat that said same-email logged-out flows are not auto-merged.
  • Documented canonical user resolution order (google.googleId first, normalized email fallback) and session remap behavior.
  • Added explicit code fields in conflict examples and included GOOGLE_CONNECT_EMAIL_MISMATCH contract.
• docs/backend/api-documentation.md
  • Added /api/auth/google/connect conflict contract for email mismatch (GOOGLE_CONNECT_EMAIL_MISMATCH) alongside existing ownership conflict.
• docs/manual-testing/auth-testing.md
  • Added assertion for code: "GOOGLE_ACCOUNT_ALREADY_CONNECTED" in connect-conflict scenario.
  • Removed outdated caveat that same-email Google/password auto-linking by email is unsupported.

Codepaths covered

• Backend canonical identity and lookup:
  • packages/backend/src/user/queries/user.queries.ts
  • packages/backend/src/user/services/user.service.ts
  • packages/backend/src/auth/services/google/util/google.auth.util.ts
• SuperTokens middleware session remap behavior:
  • packages/backend/src/common/middleware/supertokens.middleware.handlers.ts
• Google connect conflict and email-mismatch handling:
  • packages/backend/src/auth/services/google/google.auth.service.ts
  • packages/backend/src/common/errors/auth/auth.errors.ts
  • packages/backend/src/common/errors/handlers/error.handler.ts
• Shared/frontend typed error parsing:
  • packages/core/src/types/auth.types.ts
  • packages/web/src/common/apis/compass.api.util.ts
  • packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts

Knowledge gaps addressed

• Eliminated conflicting guidance around duplicate-email behavior in logged-out auth.
• Made machine-readable 409 error contracts explicit in runbooks and API docs.
• Clarified when session replacement happens versus when connect requests must fail safely.

  

---

Note

Low Risk
Low risk because this PR only updates documentation and manual test guidance; no runtime behavior is changed. The main risk is client/test confusion if these contracts diverge from the implemented backend behavior.

Overview
Updates auth docs to align with current duplicate-email and Google connect conflict behavior.

Documents machine-readable 409 contracts for POST /api/auth/google/connect, including explicit code fields for ownership conflicts (GOOGLE_ACCOUNT_ALREADY_CONNECTED) and email-mismatch conflicts (GOOGLE_CONNECT_EMAIL_MISMATCH), and clarifies canonical user resolution/session-remap semantics (Google ID first, normalized-email fallback). Manual testing runbook is updated to assert the conflict code and removes outdated caveats about same-email logged-out flows.

^{Written by Cursor Bugbot for commit f951a89. This will update automatically on new commits. Configure here.}