docs: document pay-bond-invoice action and waiting-taker-bond status

[grunch]

Summary

• Add src/pay_bond_invoice.md documenting Action::PayBondInvoice (wire name pay-bond-invoice) — payload shape (same as pay-invoice), direction, trigger, expected client behaviour, per-take-direction follow-up flow, the waiting-taker-bond sub-state with in/out transitions, failure modes, and backwards compatibility notes.
• Call out the optional bond step in take_buy.md and take_sell.md, with a prominent warning for the seller-as-taker case — the one flow where a single user pays two hold invoices in sequence on the same order (pay-bond-invoice then pay-invoice).
• Add a pay-bond-invoice entry to message_suggestions_for_actions.md worded to make the bond-vs-escrow distinction explicit.
• Stub upcoming bond-related tags in the Mostro instance status event (other_events.md) so client devs can anticipate the bond enabled/disabled parser change.
• Wire the new page into SUMMARY.md.

Context

Companion to the anti-abuse bond rollout in MostroP2P/mostro (parent issue #711). Phase 1.5 introduces the Action::PayBondInvoice and Status::WaitingTakerBond enum variants in mostro-core; without these docs, clients that only know about pay-invoice would silently ignore the new action and takes would time out with no useful error to the user.

Naming note: the action is pay-bond-invoice, not add-bond-invoice — this matches pay-invoice's direction (Mostro → user). Earlier working notes used AddBondInvoice; the canonical name is PayBondInvoice / pay-bond-invoice.

Test plan

• Render the book locally (mdbook serve / just serve) and verify the new page is reachable from the sidebar between "Take range buy order" and "Seller pays hold invoice".
• Confirm internal links resolve: pay_bond_invoice.md ↔ take_buy.md, take_sell.md, other_events.md, admin_settle_order.md, admin_cancel_order.md, order_event.md.
• Skim the seller-as-taker callout in take_buy.md for clarity — this is the most error-prone path for client implementers.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Documented anti-abuse bond feature: users may pay a separate Lightning hold invoice during take operations when bonds are enabled.
  • Clarified order status representation and client behavior during bond payment.
  • Updated take-buy and take-sell flow documentation to include optional bond payment steps.
  • Added specifications for bond-related messages, failure modes, and backward-compatibility guidance.

[coderabbitai]

Walkthrough

This PR adds comprehensive documentation for Mostro's anti-abuse bond payment system. It introduces a new pay-bond-invoice action with full specification, integrates bonds into the take-buy and take-sell flows, clarifies order-state semantics during bond payment, documents failure modes and client expectations, and establishes instance capability advertisement for bond-enabled nodes.

Changes

Anti-abuse Bond Feature Documentation

Layer / File(s)	Summary
Bond Concept & Specification src/pay_bond_invoice.md	New document defining pay-bond-invoice as an independent Lightning hold invoice, trigger timing after take, DM message structure with waiting-taker-bond status, client behavior expectations, follow-up flow transitions, status echoes, failure modes, and backward-compatibility handling for older clients.
Order State & Status Semantics src/order_event.md, src/other_events.md	Clarifies that pending orders may be matched during bond payment, remain takeable with "first bond wins" rule, require UI to not hide orders during user-initiated take; documents upcoming bond capability tags in instance status event and client preparation for bond handling.
Trade Flow Integration src/take_buy.md, src/take_sell.md	Adds optional bond step describing pay-bond-invoice → bond-accepted → pay-invoice/add-invoice sequence, interim pending/waiting-taker-bond states, and client expectations for treating two sequential invoices as separate payment steps.
Error Handling & Client Messaging src/cancel.md, src/message_suggestions_for_actions.md	Documents bond-race cancellation when multiple takers compete to lock a bond, directs clear user notification instead of silent retry; adds suggested message text for pay-bond-invoice action explaining bond security requirement and expiration consequences.
Documentation Navigation src/SUMMARY.md	Adds "Pay bond invoice" entry linking to new specification document.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A bond holds steady, a Lightning embrace,
Two invoices dance in their payment-flow race—
First lock takes the prize, while the others all fail,
Takers pay bonds with clear UI's tale! 💚⚡

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly reflects the main additions in the changeset: a new pay-bond-invoice action and waiting-taker-bond status, both core subjects documented across multiple new and modified files.
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
• Commit unit tests in branch docs/pay-bond-invoice-action

---

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]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/other_events.md`:
- Line 206: The documentation currently presents `waiting-taker-bond` as a
public order status; change the text to state explicitly that
`waiting-taker-bond` is a daemon-internal/DM-payload state (e.g., echoed in
SmallOrder.status for internal use) and not part of the public NIP-69 wire
status, which should remain `pending`; also clarify that `pay-bond-invoice` is
an internal action tied to that DM payload and that clients must still treat
missing bond tags as "behaviour unknown" and surface a clear error if they
receive a `pay-bond-invoice` for a take they cannot handle.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c80f0b85-c036-4814-a379-b577a926157e

📥 Commits

Reviewing files that changed from the base of the PR and between 09454ff and 7a52b3d.

📒 Files selected for processing (8)

• src/SUMMARY.md
• src/cancel.md
• src/message_suggestions_for_actions.md
• src/order_event.md
• src/other_events.md
• src/pay_bond_invoice.md
• src/take_buy.md
• src/take_sell.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify waiting-taker-bond as daemon-internal, not public wire status.

Line 206 currently reads like waiting-taker-bond is a regular order status. To avoid client parser mistakes, call it out explicitly as DM-payload/internal state (e.g., SmallOrder.status echo), while public NIP-69 stays pending.

Suggested wording

-Clients that take orders on a node advertising `bond` `enabled` should be prepared to handle the [`pay-bond-invoice`](./pay_bond_invoice.md) action and the `waiting-taker-bond` order status. Until this tag is finalized and shipped, clients should treat the absence of bond tags as "behaviour unknown" and surface a clear error if the node sends `pay-bond-invoice` to a take they cannot handle.
+Clients that take orders on a node advertising `bond` `enabled` should be prepared to handle the [`pay-bond-invoice`](./pay_bond_invoice.md) action and the daemon-internal `waiting-taker-bond` state echoed in DM payloads (the public NIP-69 status remains `pending`). Until this tag is finalized and shipped, clients should treat the absence of bond tags as "behaviour unknown" and surface a clear error if the node sends `pay-bond-invoice` to a take they cannot handle.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

Clients that take orders on a node advertising `bond` `enabled` should be prepared to handle the [`pay-bond-invoice`](./pay_bond_invoice.md) action and the `waiting-taker-bond` order status. Until this tag is finalized and shipped, clients should treat the absence of bond tags as "behaviour unknown" and surface a clear error if the node sends `pay-bond-invoice` to a take they cannot handle.

Clients that take orders on a node advertising `bond` `enabled` should be prepared to handle the [`pay-bond-invoice`](./pay_bond_invoice.md) action and the daemon-internal `waiting-taker-bond` state echoed in DM payloads (the public NIP-69 status remains `pending`). Until this tag is finalized and shipped, clients should treat the absence of bond tags as "behaviour unknown" and surface a clear error if the node sends `pay-bond-invoice` to a take they cannot handle.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/other_events.md` at line 206, The documentation currently presents
`waiting-taker-bond` as a public order status; change the text to state
explicitly that `waiting-taker-bond` is a daemon-internal/DM-payload state
(e.g., echoed in SmallOrder.status for internal use) and not part of the public
NIP-69 wire status, which should remain `pending`; also clarify that
`pay-bond-invoice` is an internal action tied to that DM payload and that
clients must still treat missing bond tags as "behaviour unknown" and surface a
clear error if they receive a `pay-bond-invoice` for a take they cannot handle.