Document REST proof response shape

[Lucas-FManager]

Bounty #229

What changed:

• Documented the public REST GET /api/v1/proofs/<proof_hash> response shape in docs/api-examples.md.
• Clarified that the REST proof endpoint returns the stored public proof payload directly, unlike the MCP get_proof JSON-RPC result.content[0].text envelope.
• Added docs regression coverage so the REST proof example stays present and includes the key proof/payment fields.

Evidence:

• Compared the example against the live unauthenticated endpoint:
  GET https://api.mrwk.ltclab.site/api/v1/proofs/530f141494aef2af05e3a9a97ef4ec39e026ac721b47914c4dcb404eb3bb256a
• The live response includes kind, ledger_sequence, ledger_hash, submission_url, to_account, and verifier_result directly at the top level.
• Cross-checked the handler in app/main.py::api_proof(), which loads proof.public_json, adds ledger_hash/ledger_sequence, and returns the object directly.

Verification:

• uv run --python 3.12 --extra dev python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_rest_proof_response_shape -q -> 1 passed
• uv run --python 3.12 --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 14 passed
• uv run --python 3.12 --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --python 3.12 --extra dev ruff check docs/api-examples.md tests/test_docs_public_urls.py -> all checks passed
• uv run --python 3.12 --extra dev ruff format --check --preview docs/api-examples.md tests/test_docs_public_urls.py -> 2 files already formatted
• uv run --python 3.12 --extra dev python -m pytest -q -> 206 passed, 2 warnings
• git diff --check -> clean

No private keys, wallet secrets, real signatures, payout credentials, deployment values, private vulnerability details, or MRWK price claims are included.

[weilixiong]

Review ✅ APPROVED

LOW — REST proof response docs. Clear example. MW #229 + #219.

[MolhamHamwi]

No blockers found on current head 1533f5f.

Evidence checked:

• Inspected docs/api-examples.md and confirmed the new REST proof example documents the direct /api/v1/proofs/<proof_hash> payload, not the MCP result.content[0].text envelope.
• Compared the documented fields against the public proof route behavior in app/main.py (api_get_proof) and the ledger proof serialization shape (ProofRecord.to_public_dict()).
• Inspected tests/test_docs_public_urls.py and verified it covers the route string, direct REST wording, core proof fields, submission URL, and verifier metadata.
• Ran pytest tests/test_docs_public_urls.py -q (14 passed), ruff check docs/api-examples.md tests/test_docs_public_urls.py, ruff format --check --preview docs/api-examples.md tests/test_docs_public_urls.py, and git diff --check origin/main...HEAD.

No secrets, wallet/private-key material, payout credentials, private deployment values, private vulnerability details, or MRWK price claims were reviewed or disclosed.

[wangedmund77-cmyk]

No blockers from my review.

Evidence checked:

• Inspected docs/api-examples.md and tests/test_docs_public_urls.py; the REST proof example correctly distinguishes the direct REST proof payload from the MCP JSON-RPC envelope.
• Ran uv run --extra dev pytest tests/test_docs_public_urls.py -q on PR branch pr-258: 14 passed.
• Ran uv run --extra dev python scripts/docs_smoke.py: docs smoke ok.
• Ran uv run --extra dev ruff check tests/test_docs_public_urls.py: all checks passed.

This should help API users avoid mixing up /api/v1/proofs/<proof_hash> with MCP get_proof response wrapping.

[ramimbo]

Closing this stale API-docs PR to clear the filled #229 queue. #229 was filled and closed, no fresh public API examples round was opened, and this remaining docs work is not accepted in this pass.