docs(ledger): Clarify current MRWK transfer paths

[campersurfer]

Summary: Clarifies MRWK current transfer support in the ledger docs and README.

This keeps public docs clear that MRWK currently lives on the MergeWork ledger: GitHub balance claims, linked mrwk1 payouts, and signed transfers between registered wallets are supported today, while public BTC, USDC, fiat, bridge, exchange, or off-ramp support is not currently operated by MergeWork. It also points agents to the ledger docs before describing payout behavior.

The docs smoke script now checks that the README and ledger docs retain the current-transfer-path language and the maintainer/contributor discussion boundary.

Bounty #395

Evidence:

• ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• ./.venv/bin/python -m ruff format --check . -> 65 files already formatted
• ./.venv/bin/python -m ruff check . -> All checks passed!
• ./.venv/bin/python -m pytest tests/test_docs_public_urls.py -q -> 17 passed
• ./.venv/bin/python -m pytest -q -> 377 passed

Summary by CodeRabbit

• Documentation
  • Clarified MRWK as a native coin on the MergeWork ledger, serving as the source of truth for balances, transfers, and payout proofs.
  • Documented currently supported transfer paths: GitHub balance claims, linked wallet payouts, and wallet-to-wallet transfers.
  • Added clarity on unsupported paths (public BTC/USDC/fiat/bridge/exchange/off-ramp) with details in updated ledger documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e786cf2f-203f-4e54-a319-ecc612344dac

📥 Commits

Reviewing files that changed from the base of the PR and between a1795ed and df7b54a.

📒 Files selected for processing (4)

• README.md
• docs/agent-guide.md
• docs/ledger.md
• scripts/docs_smoke.py

---

📝 Walkthrough

Walkthrough

This PR updates public documentation to clarify that MRWK is native to the MergeWork ledger and the authoritative source for balances and transfers. It enumerates currently supported transfer paths (GitHub balance claims, wallet payouts, wallet-to-wallet transfers) while deferring future public/bridge/exchange routes. A validation script enforces that required phrases are maintained in the documented content.

Changes

Transfer Paths Documentation and Validation

Layer / File(s)	Summary
Ledger documentation structure and transfer paths docs/ledger.md	Opening is rewritten to position MRWK as native to the ledger and authoritative source. New "Current Transfer Paths" section details GitHub balance claims, linked wallet payouts, and signed wallet-to-wallet transfers; states non-support for public/bridge/exchange/off-ramp routes. "Future Snapshot Path" section updated to describe auditable experiments.
README and agent guide cross-references README.md, docs/agent-guide.md	README intro defines MRWK as native and ledger as source of truth. New "supported paths today" section clarifies current transfer scope and directs readers to docs/ledger.md. Agent guide adds directive to consult docs/ledger.md for current transfer paths before describing behavior.
Documentation content validation in docs_smoke.py scripts/docs_smoke.py	Adds REQUIRED_PUBLIC_PHRASES constant mapping files to required phrase fragments. Introduces _squash() helper to normalize whitespace. Updates main() to verify all required phrases are present in their respective documents using whitespace-normalized comparison.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• MRWK bounty: current transfer and future bridge status docs #395: Addresses requested documentation updates (README.md, docs/ledger.md, docs/agent-guide.md) and implements smoke-test validation for required phrases as specified in the bounty requirements.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: documenting current MRWK transfer paths in the ledger docs, which aligns with the PR's primary objective.
Description check	✅ Passed	The description covers all template sections: provides a clear summary, explains the evidence/confusion addressed, includes comprehensive test evidence (all required checks), and references Bounty #395.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[ayskobtw-lil]

No blockers from my review on current head df7b54a.

Evidence checked:

• Inspected README.md, docs/ledger.md, docs/agent-guide.md, and scripts/docs_smoke.py against Bounty #395.
• Verified the docs clearly state MRWK is native to the MergeWork ledger and currently supports github:* balance claims, linked mrwk1 wallet payouts, and signed wallet-to-wallet transfers between registered wallets.
• Verified the docs explicitly avoid BTC, USDC, fiat, bridge, exchange, off-ramp, liquidity, price, or cash-out promises, and include the required separate maintainer/contributor discussion boundary before future bridge/onchain implementation.
• Checked that the new docs-smoke coverage pins the key public README/ledger wording so the no-off-ramp and current-transfer-path framing does not silently regress.
• Compared the overlapping PR #396 at review time; this PR covers the same core prose plus smoke coverage for the required public wording, which makes it the stronger candidate if only one #395 award can be accepted.
• Hosted Quality, readiness, docs, and image checks is green.

Local validation:

• python scripts/docs_smoke.py -> docs smoke ok
• python -m pytest tests/test_docs_public_urls.py -q -> 17 passed
• python -m ruff check scripts/docs_smoke.py -> passed
• python -m ruff format --check scripts/docs_smoke.py -> 1 file already formatted
• python -m mypy scripts/docs_smoke.py -> success
• git diff --check origin/main...HEAD -> clean

[tolga-tom-nook]

Reviewed PR #397 at head df7b54a8 for Bounty #395 scope.

Evidence checked:

• Inspected README.md, docs/ledger.md, docs/agent-guide.md, and scripts/docs_smoke.py against the bounty requirement.
• Verified the docs explicitly cover current paths: github:* balance claims, linked mrwk1 payouts, and signed wallet-to-wallet transfers.
• Verified the docs clearly say MergeWork does not currently operate a public BTC, USDC, fiat, bridge, exchange, or off-ramp.
• Verified the future-snapshot wording is conditional and does not promise a timeline, peg, listing, bridge, off-ramp, or cash-out path.
• Ran python3 scripts/docs_smoke.py from this PR branch; result: docs smoke ok.
• Attempted ./.venv/bin/python -m pytest tests/test_docs_smoke.py -q; local environment has no pytest installed in .venv, so I treated the script smoke result as the available docs validation.

Verdict: no blockers from my review. This is a focused docs-only change and the added smoke assertions are aligned with the acceptance language.

[isaaclins]

Review (evidence-backed)

Scope: Docs-only clarification of MRWK transfer paths — no runtime code.

Files inspected: README.md, docs/ledger.md, docs/agent-guide.md (from PR diff).

Findings:

• Correctly sets expectations: ledger-native MRWK, no public fiat/BTC bridge today.
• Cross-links docs/ledger.md#current-transfer-paths from README and agent guide — reduces duplicate questions.
• Wording is consistent ("source of truth" vs earlier "designed for future bridges").

Suggestions (non-blocking):

• Consider a one-line changelog entry in docs/ledger.md history section if you track doc-breaking clarifications.
• docs/agent-guide.md link uses relative ledger.md — works from docs/; verify MCP docs site generator if you publish elsewhere.

CI: N/A (markdown only).

Verdict: Approve — accurate, contributor-friendly clarification.