Refs #426: Document no-ledger account empty state

[INDICUMA]

Bounty #426

Summary

• Document the public empty-state contract for valid account identifiers with no ledger rows.
• Add an API example showing HTTP 200, exists: false, zero balance, and empty accepted-work fields.
• Guard the docs example with tests/test_docs_public_urls.py.

Evidence

• Live unauthenticated checks at 2026-05-27 showed:
  • GET https://api.mrwk.ltclab.site/api/v1/accounts/github:mw-smoke-no-ledger-20260527 -> HTTP 200 JSON with exists=false, balance_mrwk="0", and accepted-work zero/null fields.
  • GET https://api.mrwk.ltclab.site/api/v1/accounts/github:mw-smoke-no-ledger-20260527/accepted-work -> HTTP 200 JSON with summary zero and accepted_work=[].
  • GET https://mrwk.ltclab.site/accounts/github:mw-smoke-no-ledger-20260527 -> HTTP 200 HTML showing 0 MRWK, "This account has no ledger activity yet.", "No proof-backed accepted work for this account yet.", and "No ledger entries yet."
• Current code already exposes this behavior through account_api_context, account_accepted_work_context, and account_page_context in app/accounts.py.
• The prior public API/MCP examples bounty round is closed; MRWK bounty: documentation updates and improvements #426 is the current open documentation bounty.

Validation

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv312/bin/python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_account_response_shape -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv312/bin/python -m pytest tests/test_docs_public_urls.py -q -> 23 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv312/bin/python scripts/docs_smoke.py -> docs smoke ok
• .venv312/bin/python -m ruff check tests/test_docs_public_urls.py -> passed
• git diff --check -> clean

No private keys, seed material, cookies, OAuth state, access tokens, signatures, secrets, price claims, liquidity claims, exchange claims, bridge promises, off-ramp promises, or fabricated payout claims are included.

Summary by CodeRabbit

Release Notes

• Documentation
  • Clarified API behavior: valid account identifiers return HTTP 200 status even when accounts have no ledger entries, zero balances, or transaction history. Added example response demonstrating this state.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1b13aecc-08c1-4473-8c69-e4850ecf9176

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and 2950178.

📒 Files selected for processing (2)

• docs/api-examples.md
• tests/test_docs_public_urls.py

---

📝 Walkthrough

Walkthrough

Documentation clarifying the API response for valid account identifiers with no ledger entries was added to docs/api-examples.md with exists: false, zero balances, and null accepted-work fields. Test assertions were added to validate the documented example account and expected field values.

Changes

Account empty response documentation

Layer / File(s)	Summary
Account empty response documentation and validation docs/api-examples.md, tests/test_docs_public_urls.py	New "no ledger rows" example added to the Accounts/Wallets API section, showing HTTP 200 response with exists: false, zero balances, and empty accepted_work fields. Test assertions validate the specific account identifier (github:mw-smoke-no-ledger-20260527), field values (exists is false, accepted_awards is 0), and "no ledger activity" text in the documentation.

Possibly related PRs

• ramimbo/mergework#306: Both PRs update docs/api-examples.md and its tests around the /api/v1/accounts/.../accepted-work JSON response shape—this PR documents the empty accepted-work state for accounts with no ledger rows, while the retrieved PR originally added the accepted-work endpoint.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Refs #426: Document no-ledger account empty state' is concrete and directly names the changed surface (documentation of account empty state behavior).
Description check	✅ Passed	The description covers all required sections: Summary, Evidence with live validation checks, Test Evidence checklist with passing results, and bounty reference. Non-critical out-of-scope section is absent but does not affect the substantive content.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR documents no-ledger account API responses without investment, price, cash-out, or security claims. MRWK described appropriately as native to ledger.
Bounty Pr Focus	✅ Passed	PR diff matches stated files (docs/api-examples.md +24, tests/test_docs_public_urls.py +4), includes test evidence and live endpoint validation, and maintains focused scope without unrelated changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Juanpablo24-06]

Reviewed the doc-only change against the live account API and the local docs checks. The new empty-account example matches the current public response shape for github:mw-smoke-no-ledger-20260527: the account endpoint returns HTTP 200 with exists=false, balance_mrwk="0", zero/null accepted-work summary fields, and the accepted-work endpoint returns an empty list with the same zero summary.

Local validation on this PR branch:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./.venv/bin/python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_account_response_shape -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• ./.venv/bin/python -m ruff check tests/test_docs_public_urls.py docs/api-examples.md -> All checks passed

This looks like a narrow, accurate #426 docs addition to me.

[adliebe]

Reviewed PR #538 at current head 2950178e9fe7cf36c880e397a08b5a0f95174a3b as non-author adliebe.

I do not see a blocker. This is a docs/test-only change, so I checked it against the implemented account surfaces and live public behavior rather than only reading the Markdown.

Evidence:

• Inspected docs/api-examples.md and tests/test_docs_public_urls.py; the new example documents the no-ledger account as exists=false, balance_mrwk="0", accepted_awards=0, accepted_mrwk="0", and no latest proof fields.
• Inspected app/accounts.py and app/templates/account.html; the API, accepted-work endpoint, and HTML page use the empty accepted-work helpers, so a valid GitHub account with no ledger row keeps the stable zero/empty shape while the page shows the no-ledger empty state.
• Live public readback for github:mw-smoke-no-ledger-20260527 returned account API exists=false, balance_mrwk="0", accepted-work summary accepted_awards=0 / accepted_mrwk="0", zero accepted-work rows, and HTML HTTP 200 with the no-ledger text.

Validation:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ..\mergework\.venv\Scripts\python.exe -m pytest tests/test_docs_public_urls.py::test_api_examples_document_account_response_shape tests/test_account_routes.py::test_registered_account_routes_preserve_api_and_page_shapes tests/test_api_mcp.py::test_account_api_rejects_empty_account_path tests/test_api_mcp.py::test_account_api_keeps_schema_when_accepted_work_proof_is_malformed -q passed, 4 tests.
• ..\mergework\.venv\Scripts\python.exe scripts\docs_smoke.py passed.
• ..\mergework\.venv\Scripts\ruff.exe check tests\test_docs_public_urls.py tests\test_account_routes.py tests\test_api_mcp.py app\accounts.py passed.
• ..\mergework\.venv\Scripts\ruff.exe format --check tests\test_docs_public_urls.py tests\test_account_routes.py tests\test_api_mcp.py app\accounts.py passed.
• git diff --check origin/main...HEAD passed.

Verdict: approved. The docs now describe the actual empty-account behavior without adding payout, wallet-secret, off-ramp, liquidity, or private-account claims.

[weilixiong]

APPROVED — Clean docs-only change documenting no-ledger account empty state. +28/-0, new JSON example + test assertions. Refs #426.

[weilixiong]

APPROVED — Clean docs-only change documenting no-ledger account empty state. +28/-0, straightforward explanation. No code changes.

[tinyopsstudio]

Reviewed PR #538 at 2950178e9fe7cf36c880e397a08b5a0f95174a3b for the no-ledger account empty-state documentation contract.

Evidence checked:

• inspected docs/api-examples.md, tests/test_docs_public_urls.py, app/accounts.py, and app/serializers.py;
• confirmed the new docs example matches account_api_context() for a valid github: account with no Account row: exists=false, balance_mrwk="0", GitHub transfer status, and the stable empty accepted-work summary;
• confirmed account_accepted_work_context() returns the same zero summary plus accepted_work=[] for that no-ledger account;
• confirmed account_page_context() uses the safe accepted-work helpers and the HTML route renders the no-ledger / no accepted-work empty state instead of requiring a ledger row.

Validation:

• focused account/docs tests: tests/test_docs_public_urls.py::test_api_examples_document_account_response_shape, tests/test_account_routes.py::test_registered_account_routes_preserve_api_and_page_shapes, and tests/test_api_mcp.py::test_account_api_keeps_schema_when_accepted_work_proof_is_malformed -> 3 passed
• ad hoc TestClient probe for github:mw-smoke-no-ledger-20260527: account API 200, accepted-work API 200, HTML page 200, exists=false, zero balance, empty accepted-work rows, and expected empty-state page text
• scripts/docs_smoke.py -> docs smoke ok
• tests/test_docs_public_urls.py -q -> 23 passed
• full test suite -> 414 passed
• Ruff check on docs/api-examples.md, tests/test_docs_public_urls.py, app/accounts.py, and app/serializers.py -> passed
• Ruff format check on the Python files -> 3 files already formatted
• git diff --check origin/main...HEAD -> clean

Assessment: no blocker found in this docs/test slice. The change is narrow, matches the implemented public account behavior, and avoids adding price, liquidity, exchange, bridge, off-ramp, private-key, or fabricated payout claims.