docs(auth): clarify google connect conflict behavior and triage

[cursor]

Summary

• update auth and API docs with the verified POST /api/auth/google/connect request/response contract
• document explicit ownership-conflict behavior (409 CONFLICT) when a Google account is already attached to another Compass user
• add manual-testing coverage for connect-conflict regression checks
• add sync/websocket triage guidance for connect-later conflict incidents

Docs updated

• docs/backend/api-documentation.md
• docs/features/password-auth-flow.md
• docs/features/google-sync-and-websocket-flow.md
• docs/manual-testing/auth-testing.md

Codepaths covered

• Backend connect endpoint and route wiring:
  • packages/backend/src/auth/auth.routes.config.ts
  • packages/backend/src/auth/controllers/auth.controller.ts
• Google connect ownership guard and persistence behavior:
  • 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.express.handler.ts
• Web connect flow entrypoint:
  • packages/web/src/auth/hooks/oauth/useConnectGoogle.ts
  • packages/web/src/common/apis/auth.api.ts

Knowledge gaps addressed

• previously under-documented conflict payload/status for in-session Google connect
• missing operator guidance for distinguishing ownership conflict from OAuth transport failures
• missing manual QA scenario to verify that conflict handling preserves active Compass session/data

  

---

Note

Low Risk
Low risk because this PR only updates documentation and manual test runbooks; no runtime code paths are modified. Risk is limited to potential doc drift/miscommunication about the POST /api/auth/google/connect conflict behavior.

Overview
Docs-only update that formalizes the POST /api/auth/google/connect contract by adding a concrete request example and explicitly documenting the 409 CONFLICT response payload for Google-account ownership conflicts.

Adds operator/triage guidance explaining that conflicts should have no side effects (no credential persistence, no sync metadata restart, no import websocket lifecycle), and extends the auth manual-testing runbook with a new connect-conflict scenario plus an updated regression checklist to cover this case.

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