From 2950178e9fe7cf36c880e397a08b5a0f95174a3b Mon Sep 17 00:00:00 2001
From: Brian Cho <khu.ac.kr@khu.ac.kr>
Date: Wed, 27 May 2026 21:58:20 +0200
Subject: [PATCH] Document no-ledger account empty state

---
 docs/api-examples.md           | 24 ++++++++++++++++++++++++
 tests/test_docs_public_urls.py |  4 ++++
 2 files changed, 28 insertions(+)

diff --git a/docs/api-examples.md b/docs/api-examples.md
index 0b6e9e8..8c72fc6 100644
--- a/docs/api-examples.md
+++ b/docs/api-examples.md
@@ -312,6 +312,30 @@ For `treasury:` and `reserve:` accounts, `github_login` is `null` and
 `transfer_status` explains that direct MRWK wallet transfers are only available
 for registered `mrwk1` addresses.
 
+Valid account identifiers that have no ledger rows still return HTTP 200 with
+`exists: false`, zero balances, and empty accepted-work fields. The public HTML
+account page mirrors that empty state with "no ledger activity" and no
+transactions:
+
+```json
+{
+  "account": "github:mw-smoke-no-ledger-20260527",
+  "ledger_address": "github:mw-smoke-no-ledger-20260527",
+  "github_login": "mw-smoke-no-ledger-20260527",
+  "exists": false,
+  "balance_mrwk": "0",
+  "transfer_status": "Claim GitHub balances from /me after linking a registered mrwk1 wallet.",
+  "accepted_work": {
+    "accepted_awards": 0,
+    "accepted_mrwk": "0",
+    "latest_ledger_sequence": null,
+    "latest_submission_url": null,
+    "latest_proof_hash": null,
+    "latest_proof_url": null
+  }
+}
+```
+
 Read the proof-backed accepted-work list for a single account:
 
 ```bash
diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py
index c7f1366..f1f4582 100644
--- a/tests/test_docs_public_urls.py
+++ b/tests/test_docs_public_urls.py
@@ -82,6 +82,10 @@ def test_api_examples_document_account_response_shape() -> None:
     assert '"github_login": "tatelyman"' in examples
     assert '"exists": true' in examples
     assert '"balance_mrwk": "395"' in examples
+    assert '"account": "github:mw-smoke-no-ledger-20260527"' in examples
+    assert '"exists": false' in examples
+    assert '"accepted_awards": 0' in examples
+    assert "no ledger activity" in examples
     assert "Claim GitHub balances from /me" in examples
     assert "treasury:" in examples
     assert "registered `mrwk1` addresses" in examples