Add agent instructions for journeys, including cross-platform runs

[jvsena42]

Problem or use case

journeys/ holds 30 specs across six suites, but AGENTS.md does not mention them anywhere — an agent working in this repo has no way to learn they exist, when to run one, or that porting a feature should carry its journeys with it. There is no top-level journeys/README.md either; each suite documents its own preconditions, so nothing describes the format or the runner in one place.

bitkit-ios has now ported 28 of the 30 (synonymdev/bitkit-ios#691) and added that documentation on its side. That makes the missing Android half more costly than it was: the specs are deliberately kept diffable between the two repos, so a behaviour meant to match can be checked by running the same file on both platforms — but only one side currently tells an agent so.

Proposed solution

Mirror what iOS added:

1. A Journeys section in AGENTS.md — where they live, that they are agent-evaluated and non-deterministic so they belong on a manual workflow rather than a blocking CI gate, and the rule that porting a feature to or from iOS carries its journeys with it.
2. A top-level journeys/README.md — the XML format and evaluation rules, how to run one, identifier conventions, and a table of the suites.
3. Cross-platform guidance — the iOS equivalents of the Android commands (xcodebuildmcp simulator snapshot-ui for android layout, and so on) so an Android agent can run the same spec on iOS, plus what to do when the two disagree: record an intentional platform difference on both sides, or report a divergence as the bug it is. Never rewrite a journey to match whatever the app currently does — that turns a failing test into a description of the bug.

Findings from the iOS side worth carrying over into that section:

• adb shell input text drops characters — it lost 54 of a 397-character invoice. adb shell cmd clipboard is not implemented on the emulator image. The reliable route for an address or invoice is a URI, which also skips the recipient screen:

  adb shell am start -a android.intent.action.VIEW -d "lightning:<invoice>" to.bitkit.dev

• Nothing in this repo mentions the android CLI. AGENTS.md documents raw adb under "Device Debugging (adb)", and android-cli appears nowhere — it is a user-level agent skill (~/.claude/skills/android-cli) that the repo does not provision; .claude/plugins carries only blocktank-api. So an agent here has no android layout in its vocabulary unless the person running it happens to have that skill installed. Worth deciding whether to document the commands directly in AGENTS.md alongside the existing adb section, or to add the skill to the .claude/plugins marketplace so it comes with the repo.
• If you do lean on that skill, note its reference docs are wrong on one point: android layout emits hyphenated JSON keys (resource-id, content-desc), not the camelCase references/interact.md documents. A runner filtering on the camelCase names finds nothing.
• The identifier vocabulary really is shared: Settings agrees on Tab-general, Tab-security, Tab-advanced, NavigationBack, HeaderMenu, CurrenciesSettings, UnitSettings, WidgetsSettings and QuickpaySettings. Two rows that disagreed turned out to be an iOS bug (Language and Transaction Speed were addressable only as a shared Value), now fixed. One is still unreconciled and worth a decision: BackgroundPaymentSettings here vs NotificationsSettings on iOS.
• The send amount screen emits both AvailableAmount and available_balance; iOS only has the former. Worth settling on one.
• deeplinks is the one suite not ported — iOS registers the bitkit scheme but has no bitkit://screen/... router, so those journeys have no iOS counterpart yet.

Alternatives considered

Leaving the documentation on the iOS side only. That holds while one person carries changes both ways, but the shared-spec property is the whole point, and it stops being reliable as soon as an agent working in this repo does not know the journeys exist.

Additional context

• iOS PR: test: port Android journeys to iOS bitkit-ios#691 — the ported suites, the AGENTS.md Journeys section and journeys/README.md are all on that branch and can be copied from directly.
• While testing the cross-platform section, a Lightning payment was driven end to end between the two: an invoice generated on the iOS simulator, paid from the Android emulator over the staging regtest backend (1 000 sats, balances confirmed on both sides). That round trip is the sharpest single check that the two builds agree, and is a candidate for a shared journey of its own.