docs: add TRADE_EXECUTION.md spec

[mostronatorcoder]

Spec for TRADE EXECUTION based on v1 code analysis.

Summary by CodeRabbit

• Documentation
  • Updated navigation routes, order states, and take order flow documentation with enhanced cross-references to a newly added comprehensive trade execution specification.
  • Added detailed trade execution reference documentation covering lightning invoice payment flows, screen interactions, state transitions, role-specific user behaviors, and error, timeout, and dispute handling scenarios.

[grunch]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

Added a comprehensive new specification document TRADE_EXECUTION.md that details Lightning invoice payment flows, screen behavior, and state machine mappings for Mostro Mobile v1 trade execution. Updated cross-references across four existing specification documents to point to the new resource, consolidating execution-related documentation in one location.

Changes

Cohort / File(s)	Summary
Documentation Index & Trade Execution Specification README.md, TRADE_EXECUTION.md	Added new TRADE_EXECUTION.md specification documenting Lightning invoice payment flows (PayLightningInvoiceScreen, AddLightningInvoiceScreen, TradeDetailScreen), routes (/pay_invoice/:orderId, /add_invoice/:orderId, /trade_detail/:orderId), state machine mappings, and execution behaviors. Updated README index to include new specification.
Cross-Reference Updates NAVIGATION_ROUTES.md, ORDER_STATES.md, TAKE_ORDER.md	Updated route descriptions and cross-reference sections to link to new TRADE_EXECUTION.md specification. Localized text and table headers to English ("Cross References" / "Reference/Document"). Added informational blocks explaining post-redirect screen behavior and execution state handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• New features from v1-reference #16: Updates order state/action model and documents OrderState/MostroFSM mappings that are now centralized in the new TRADE_EXECUTION.md specification.
• docs: HOME & NAVIGATION specs #20: Directly modifies NAVIGATION_ROUTES.md and adjusts cross-references for trade-related routes, overlapping with this PR's scope.
• docs: add comprehensive order states specification #11: Introduces the comprehensive ORDER_STATES.md specification that is now cross-referenced by the new TRADE_EXECUTION.md document.

Poem

🐰 A spec for trades, so neat and clear,
Cross-references make the path appear,
From orders placed to invoices paid,
One document, no more afraid! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add TRADE_EXECUTION.md spec' directly and clearly describes the main change—adding a new specification document for trade execution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/trade-execution-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

.specify/v1-reference/TRADE_EXECUTION.md (1)

192-192: Consider simplifying "prior to" for conciseness.

The phrase "prior to" could be replaced with "before" for brevity.

📝 Suggested wording

-| `release`, `purchase-completed`, `hold-invoice-payment-settled` | `success` / `settled-hold-invoice` | Completion path prior to rating. |
+| `release`, `purchase-completed`, `hold-invoice-payment-settled` | `success` / `settled-hold-invoice` | Completion path before rating. |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.specify/v1-reference/TRADE_EXECUTION.md at line 192, Replace the phrase
"prior to" with "before" in the table cell that reads "Completion path prior to
rating." — locate the row containing the event names `release`,
`purchase-completed`, `hold-invoice-payment-settled` and update the description
to "Completion path before rating." to make the wording more concise.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.specify/v1-reference/TRADE_EXECUTION.md:
- Line 192: Replace the phrase "prior to" with "before" in the table cell that
reads "Completion path prior to rating." — locate the row containing the event
names `release`, `purchase-completed`, `hold-invoice-payment-settled` and update
the description to "Completion path before rating." to make the wording more
concise.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8b24aec6-87f3-4da0-aa6a-862ad1daec76

📥 Commits

Reviewing files that changed from the base of the PR and between e993097 and f68c2ae.

📒 Files selected for processing (5)

• .specify/v1-reference/NAVIGATION_ROUTES.md
• .specify/v1-reference/ORDER_STATES.md
• .specify/v1-reference/README.md
• .specify/v1-reference/TAKE_ORDER.md
• .specify/v1-reference/TRADE_EXECUTION.md