docs: add agent instructions for journeys

[jvsena42]

Closes #1188

This PR:

1. Adds a top-level journeys/README.md covering the XML format, the evaluation rules, how to run one, the backend preconditions and the suite table.
2. Adds a Journeys section to AGENTS.md, so an agent working here learns the corpus exists and that porting a feature carries its journeys with it.
3. Documents the android CLI and the iOS command equivalents, so the same journey file can be run on both platforms.

Description

journeys/ holds 35 specs across eight suites, and until now nothing outside that directory mentioned them. bitkit-ios ported 33 of them and added this documentation on its side (synonymdev/bitkit-ios#691); 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 — but only one side told an agent so.

Journeys are framed here as developer-assistance specs rather than a source of truth. That is a deliberate reversal of the android CLI's own journey documentation, which states that "the journey XML is the source of truth; if the app disagrees with the journey, the app has failed". An agent with that skill installed would otherwise arrive with the opposite rule. The corpus is maintained by hand alongside two codebases and drifts, so a journey that disagrees with the app is most likely stale: say what you found, update the journey, and escalate only once the app has separately been confirmed wrong. A crash or freeze remains the exception.

The android CLI is documented directly in AGENTS.md rather than vendored into .claude/plugins, matching the existing adb section. Two traps are recorded alongside it: adb shell input text silently drops characters, and the CLI emits hyphenated JSON keys while its own reference documents camelCase, so a runner filtering on resourceId finds nothing.

Several claims in the issue were checked against the tree rather than carried over. The corpus is 35 journeys across eight suites, not the 30 across six the issue describes. The iOS port did not keep every file name identical: three were renamed, three Android journeys have no counterpart, and one exists only on iOS. All of it is in the cross-platform table. android layout was run against a live emulator to confirm the hyphenated keys.

Two identifier disagreements are recorded as unreconciled rather than fixed, since settling either is a code change: the Send screen emits both AvailableAmount and available_balance where iOS has only the first, and the background-payments row is BackgroundPaymentSettings here against NotificationsSettings on iOS.

Overlaps with #1250, which adds its own Journeys section to AGENTS.md calling journeys the QA contract for PRs, plus a CI check over a generated index. This branch says journeys are not a QA gate and that nothing in .github/workflows reads journeys/ — true today, and false once that lands. The two sections and those claims need reconciling by whichever merges second.

No changelog fragment: documentation only, nothing user-facing.

Design

N/A — no UI changes.

Preview

N/A — no user-visible changes.

QA Notes

Manual Tests

• 1. Read journeys/README.md → run journeys/widgets/widgets-intro.xml on an emulator: the commands as written drive the flow, with no backend running.
• 2. android layout --pretty on any Bitkit screen: keys are hyphenated as documented, and Compose testTags land in resource-id.
• 3. Fund a wallet per the backend preconditions → run journeys/amount-limits/send-amount-over-balance.xml: ./lsp deposit prints a txid, mine prints nothing on success, and the balance syncs.
• 4. Ask an agent to run a journey without naming the file, e.g. test the widgets flow: it finds the corpus from AGENTS.md alone.

Automated Checks

N/A — documentation only; no code or test files changed.

[github-actions]

Regtest APK

Built from 1a19983 (run).

Download bitkit-dev-debug universal APK (expires in 30 days).

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge with no outstanding actionable findings.

Summary

• Adds installation and usage guidance for the Android agent CLI.
• Defines journey format, evaluation rules, backend prerequisites, suites, and Android/iOS differences.
• Changes the Widgets intro journey to verify presence without incorrectly requiring last position.

_{Reviews (2) · Last reviewed commit: "docs: make android cli install platform-..."}

[piotr-iohk]

Docs-only PR — not run on device beyond what’s already in the author’s QA checklist.

Findings

1. [gap] journeys/widgets/widgets-intro.xml no longer asserts “last widget” (fixed slot order, verified on both platforms per the description), but iOS still has Verify "Bitcoin Weather" appears as the last widget…. That leaves the twins out of sync with this PR’s own porting rules. Prefer the same description + assertion change on iOS (or a tracked intentional-diff note — here the prose says behaviour matches, so iOS should update).

2. [nit] Open #1250/#743 treat journeys as a PR QA contract + CI index; this branch says they are not a QA gate and CI does not read them. Whichever merges second needs to reconcile those claims so agents don’t get contradictory instructions.

[jvsena42]

Docs-only PR — not run on device beyond what’s already in the author’s QA checklist.

Findings

1. [gap] journeys/widgets/widgets-intro.xml no longer asserts “last widget” (fixed slot order, verified on both platforms per the description), but iOS still has Verify "Bitcoin Weather" appears as the last widget…. That leaves the twins out of sync with this PR’s own porting rules. Prefer the same description + assertion change on iOS (or a tracked intentional-diff note — here the prose says behaviour matches, so iOS should update).
2. [nit] Open chore: use journeys as prs qa contract #1250/fix: ensure node state persisted before shutdown #743 treat journeys as a PR QA contract + CI index; this branch says they are not a QA gate and CI does not read them. Whichever merges second needs to reconcile those claims so agents don’t get contradictory instructions.

1. Fixed
2. We still need more work before considering journeys as source of true QA gating. This PR is just for match iOS current state and make easier for the agents discover the emulator tools. See the comments: test: port Android journeys to iOS bitkit-ios#691 (review) test: port Android journeys to iOS bitkit-ios#691 (comment)