docs: Add dispute chat documentation

[AndreaDiazCorreia]

Adds documentation for the dispute chat feature, explaining how users and admins communicate through encrypted Gift Wrap messages (NIP-59) during dispute resolution.

The documentation covers:

• Message format for users and admins
• Gift Wrap protocol structure (RUMOR, SEAL, Gift Wrap layers)
• Message flow and encryption process
• Privacy features

Also fixes typos in dispute.md.

Summary by CodeRabbit

• Documentation
  • Added a Dispute Chat guide covering messaging workflow, encryption layers, sending/receiving steps, JSON examples, privacy features, and a message flow diagram.
  • Updated site navigation to include Dispute Chat.
  • Corrected typos and improved grammar on the Dispute page for clarity.

[coderabbitai]

Walkthrough

Added a new "Dispute Chat" documentation page and linked it in src/SUMMARY.md; minor grammar and typo fixes applied to src/dispute.md. No code, APIs, exported entities, or runtime behavior were changed.

Changes

Cohort / File(s)	Summary of Changes
Docs: Navigation update src/SUMMARY.md	Inserted a new “Dispute Chat” entry into the SUMMARY list; subsequent entries shifted to accommodate the new link.
Docs: Dispute page fixes src/dispute.md	Fixed typos and small grammar issues (e.g., “A user”, “Mostro sends an addressable event”, “trade participant”); semantic content unchanged.
Docs: Dispute Chat feature src/dispute_chat.md	Added a new doc describing the Dispute Chat using Gift Wrap (NIP-59): send-dm action, RUMOR→SEAL→Gift Wrap layering, JSON examples, subscription/decryption flow, and privacy properties.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User
  participant UC as User Client
  participant GW as Gift Wrap (RUMOR→SEAL→WRAP)
  participant R as Relay
  participant AC as Admin Client
  participant A as Admin

  U->>UC: Compose DM (text_message)
  UC->>GW: Build RUMOR (kind 1)
  GW->>GW: Encrypt RUMOR → SEAL (kind 13)
  GW->>GW: Wrap SEAL → Gift Wrap (kind 1059)
  UC->>R: Publish Gift Wrap (p-tag=recipient)
  Note over R: Stores and relays kind 1059

  AC->>R: Subscribe kind 1059 (matching p-tag)
  R-->>AC: Deliver Gift Wrap
  AC->>GW: Unwrap Gift Wrap → SEAL
  GW->>GW: Decrypt SEAL → RUMOR
  AC->>A: Display plaintext message

Loading

sequenceDiagram
  autonumber
  participant A as Admin
  participant AC as Admin Client
  participant GW as Gift Wrap (RUMOR→SEAL→WRAP)
  participant R as Relay
  participant UC as User Client
  participant U as User

  A->>AC: Compose DM (text_message)
  AC->>GW: Build RUMOR (kind 1)
  GW->>GW: Encrypt RUMOR → SEAL (kind 13)
  GW->>GW: Wrap SEAL → Gift Wrap (kind 1059)
  AC->>R: Publish Gift Wrap (p-tag=recipient)

  UC->>R: Subscribe kind 1059 (matching p-tag)
  R-->>UC: Deliver Gift Wrap
  UC->>GW: Unwrap → SEAL → RUMOR
  UC->>U: Display plaintext message

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Fix json syntax #22 — Edits overlap on src/dispute.md (related whitespace/JSON/formatting changes), likely relevant to the same documentation area.

Poem

A nibble of notes in a neatly wrapped chat,
I hop through the layers—rumor, seal, wrap!
Burrowed in bytes where the secrets stay flat,
Relays whisper softly: tap-tap-tap.
With tidy docs and carrots to match,
Disputes now ping with a gift-wrapped dispatch. 🥕✨

Pre-merge checks and finishing touches

✅ 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 dispute chat documentation" is fully related to the main change in the changeset. The primary addition in this PR is the new src/dispute_chat.md file that documents the dispute chat feature using Gift Wrap (NIP-59), which the title accurately captures. The title is concise, uses a clear conventional format (docs: prefix for documentation changes), and is specific enough that a teammate scanning the repository history would immediately understand that the PR adds documentation for the dispute chat feature. Secondary changes like the typo fixes in dispute.md and the SUMMARY.md entry addition do not diminish the clarity and accuracy of the title.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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: 0

🧹 Nitpick comments (2)

src/dispute.md (1)

131-148: Polish the sentence about notifying participants.

Consider tightening the grammar: use “Mostro’d sends” (or “Mostro sends” if that’s what you meant) and “other than”/“different from” to keep the prose clear.

Apply this tweak:

-Then mostrod send messages to each trade participant, the buyer and seller for them to know the pubkey of the admin who took the dispute, that way the client can start listening events from that specific pubkey, by default clients should discard any messages received from any pubkey different than Mostro node or dispute solver, the message looks like this:
+Then Mostro sends messages to each trade participant—the buyer and the seller—so they know the admin’s pubkey. That way, clients can start listening for events from that specific pubkey. By default, clients should discard any messages received from pubkeys other than the Mostro node or the dispute solver. The message looks like this:

src/dispute_chat.md (1)

114-132: Add a language hint to the flow diagram fence.

markdownlint (MD040) flags this block because the fence lacks a language. Tag it as text (or another suitable label) to silence the linter and help renderers.

You can edit it like:

-```
+```text
 User writes message

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dda77a8 and 778d8ab.

📒 Files selected for processing (3)

• src/SUMMARY.md (1 hunks)
• src/dispute.md (3 hunks)
• src/dispute_chat.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-08-17T08:44:22.667Z

Learnt from: arkanoider
PR: MostroP2P/protocol#19
File: src/restore_session.md:51-69
Timestamp: 2025-08-17T08:44:22.667Z
Learning: In the MostroP2P protocol, orders can have a "dispute" status in the orders array while simultaneously having detailed dispute information in the disputes array. This is normal behavior - the order status reflects the current state while the disputes array contains specific dispute metadata for the same trade_index.

Applied to files:

• src/dispute.md

🪛 LanguageTool

src/dispute.md

[style] ~131-~131: Did you mean ‘different from’? ‘Different than’ is often considered colloquial style.
Context: ...ages received from any pubkey different than Mostro node or dispute solver, the mess...

(DIFFERENT_THAN)

🪛 markdownlint-cli2 (0.18.1)

src/dispute_chat.md

114-114: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 778d8ab and 89a66c7.

📒 Files selected for processing (1)

• src/dispute_chat.md (1 hunks)

🔇 Additional comments (1)

src/dispute_chat.md (1)

1-48: Strong documentation of messaging interface and Gift Wrap setup.

The visible sections clearly explain the user/admin messaging workflow, the action format, and JSON payload structure. The NIP-59 reference and p-tag subscription mechanism are accurately described. The JSON examples are well-structured and consistent.