diff --git a/docs/agent-guide.md b/docs/agent-guide.md
index 68776ccd..5ee9a8ab 100644
--- a/docs/agent-guide.md
+++ b/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
 
diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py
index 0871c020..d392a178 100644
--- a/scripts/docs_smoke.py
+++ b/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",
diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py
index c7f13666..05c3defa 100644
--- a/tests/test_docs_public_urls.py
+++ b/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")