docs: add runtime route documentation and AGENTS.md rule

backend/tests/e2e/test_auth_flow.py

@@ -11,15 +11,14 @@ import uvicorn
 from app import app
 from v1.auth.dependencies import get_auth_service
 from v1.auth.schemas import (
-    AuthResendCodeResponse,
-    AuthSignupStartResponse,
-    AuthTokenResponse,
     AuthUser,
-    LoginRequest,
-    RefreshRequest,
-    SignupResendRequest,
-    SignupStartRequest,
-    SignupVerifyRequest,
+    SessionCreateRequest,
+    SessionRefreshRequest,
+    SessionResponse,
+    VerificationCreateRequest,
+    VerificationCreateResponse,
+    VerificationResendRequest,
+    VerificationVerifyRequest,
 )
 from v1.auth.service import AuthService
 
@@ -28,13 +27,15 @@ class FakeE2EAuthService(AuthService):
     def __init__(self) -> None:
         self._user = AuthUser(id="user-1", email="user@example.com")
 
-    async def signup_start(
-        self, request: SignupStartRequest
-    ) -> AuthSignupStartResponse:
-        return AuthSignupStartResponse(email=request.email)
+    async def create_verification(
+        self, request: VerificationCreateRequest
+    ) -> VerificationCreateResponse:
+        return VerificationCreateResponse(email=request.email)
 
-    async def signup_verify(self, request: SignupVerifyRequest) -> AuthTokenResponse:
-        return AuthTokenResponse(
+    async def verify_verification(
+        self, request: VerificationVerifyRequest
+    ) -> SessionResponse:
+        return SessionResponse(
             access_token="access-1",
             refresh_token="refresh-1",
             expires_in=3600,
@@ -42,13 +43,11 @@ class FakeE2EAuthService(AuthService):
             user=self._user,
         )
 
-    async def signup_resend(
-        self, request: SignupResendRequest
-    ) -> AuthResendCodeResponse:
-        return AuthResendCodeResponse()
+    async def resend_verification(self, request: VerificationResendRequest) -> None:
+        return None
 
-    async def login(self, request: LoginRequest) -> AuthTokenResponse:
-        return AuthTokenResponse(
+    async def create_session(self, request: SessionCreateRequest) -> SessionResponse:
+        return SessionResponse(
             access_token="access-2",
             refresh_token="refresh-2",
             expires_in=3600,
@@ -56,8 +55,8 @@ class FakeE2EAuthService(AuthService):
             user=self._user,
         )
 
-    async def refresh(self, request: RefreshRequest) -> AuthTokenResponse:
-        return AuthTokenResponse(
+    async def refresh_session(self, request: SessionRefreshRequest) -> SessionResponse:
+        return SessionResponse(
             access_token="access-3",
             refresh_token="refresh-3",
             expires_in=3600,
@@ -65,7 +64,7 @@ class FakeE2EAuthService(AuthService):
             user=self._user,
         )
 
-    async def logout(self, refresh_token: str | None) -> None:
+    async def delete_session(self, refresh_token: str | None) -> None:
         return None
 
 
@@ -106,8 +105,8 @@ def test_auth_flow_e2e() -> None:
                 base_url=f"http://{host}:{port}"
             )
             try:
-                signup = request_context.post(
-                    "/api/v1/auth/signup/start",
+                verification = request_context.post(
+                    "/api/v1/auth/verifications",
                     data=json.dumps(
                         {
                             "username": "demo",
@@ -117,10 +116,10 @@ def test_auth_flow_e2e() -> None:
                     ),
                     headers={"Content-Type": "application/json"},
                 )
-                assert signup.status == 202
+                assert verification.status == 202
 
                 verify = request_context.post(
-                    "/api/v1/auth/signup/verify",
+                    "/api/v1/auth/verifications/verify",
                     data=json.dumps(
                         {
                             "email": "user@example.com",
@@ -133,7 +132,7 @@ def test_auth_flow_e2e() -> None:
                 assert verify.json()["access_token"] == "access-1"
 
                 login = request_context.post(
-                    "/api/v1/auth/login",
+                    "/api/v1/auth/sessions",
                     data=json.dumps(
                         {"email": "user@example.com", "password": "secret123"}
                     ),
@@ -143,15 +142,15 @@ def test_auth_flow_e2e() -> None:
                 assert login.json()["access_token"] == "access-2"
 
                 refresh = request_context.post(
-                    "/api/v1/auth/refresh",
+                    "/api/v1/auth/sessions/refresh",
                     data=json.dumps({"refresh_token": "refresh-2"}),
                     headers={"Content-Type": "application/json"},
                 )
                 assert refresh.status == 200
                 assert refresh.json()["access_token"] == "access-3"
 
-                logout = request_context.post(
-                    "/api/v1/auth/logout",
+                logout = request_context.delete(
+                    "/api/v1/auth/sessions",
                     data=json.dumps({"refresh_token": "refresh-3"}),
                     headers={"Content-Type": "application/json"},
                 )