Refs #426: Document auth session flow

docs/agent-guide.md

@@ -110,6 +110,10 @@ curl -s -X POST "$API_HOST/api/v1/wallets/register" \
 
 GitHub link and claim endpoints require GitHub OAuth plus a wallet signature.
 The browser flow starts at `https://mrwk.ltclab.site/auth/github/login?next=/me`.
+Check the current session with `GET /api/v1/auth/me`; unauthenticated callers
+receive `{"authenticated": false, "github_login": null}`. End a browser session
+with `POST /auth/logout`, which redirects to `/` and clears the MergeWork auth cookies.
+Do not use `GET /auth/logout` for logout side effects.
 
 ## Wallet Payloads
 

scripts/docs_smoke.py

@@ -44,6 +44,9 @@
     "docs/agent-guide.md": [
         ("Public reads such as `GET /api/v1/bounties/{id}/attempts` do not require login"),
         ("creating or releasing an attempt requires the GitHub-authenticated browser session"),
+        "Check the current session with `GET /api/v1/auth/me`",
+        "clears the MergeWork auth cookies",
+        "Do not use `GET /auth/logout` for logout side effects.",
     ],
     "docs/bounty-rules.md": [
         "## Submission Evidence Templates",

tests/test_docs_public_urls.py

@@ -113,6 +113,18 @@ def test_api_examples_document_auth_me_response_shape() -> None:
     assert "Unauthenticated requests return" in examples
 
 
+def test_agent_guide_documents_auth_session_flow() -> None:
+    guide = Path("docs/agent-guide.md").read_text(encoding="utf-8")
+
+    assert "https://mrwk.ltclab.site/auth/github/login?next=/me" in guide
+    assert "GET /api/v1/auth/me" in guide
+    assert '{"authenticated": false, "github_login": null}' in guide
+    assert "POST /auth/logout" in guide
+    assert "redirects to `/`" in guide
+    assert "clears the MergeWork auth cookies" in guide
+    assert "Do not use `GET /auth/logout` for logout side effects." in guide
+
+
 def test_api_examples_document_bounty_list_response_shape() -> None:
     examples = Path("docs/api-examples.md").read_text(encoding="utf-8")