docs: add dispute system spec

[grunch]

Summary by CodeRabbit

• Documentation
  • Added comprehensive specification for the dispute system, detailing the complete creation flow, chat interactions with administrators, read/unread status management, and lifecycle including initiation, assignment, resolution, and auto-closure workflows.
  • Updated cross-references throughout related documentation to clarify dispute system integration points with orders, trades, and peer-to-peer messaging.

[coderabbitai]

Walkthrough

Adds a comprehensive specification document for the dispute system and updates related reference documents with cross-references. The new specification details dispute routes, UI components, messaging pipeline, state transitions, and lifecycle management. Existing specifications receive targeted updates to direct readers to the new dispute system documentation.

Changes

Cohort / File(s)	Summary
Dispute System Specification \.specify/v1-reference/DISPUTE_SYSTEM.md	New comprehensive specification document detailing dispute feature v1 behavior: route mappings, UI components (DisputesList, DisputeChatScreen), state lifecycle mapping, messaging pipeline with Sembast event store and shared-key encryption, read/unread status handling, and admin interaction flows.
Documentation Cross-References \.specify/v1-reference/README.md, \.specify/v1-reference/NAVIGATION_ROUTES.md, \.specify/v1-reference/ORDER_STATUS_HANDLING.md, \.specify/v1-reference/P2P_CHAT_SYSTEM.md, \.specify/v1-reference/TRADE_EXECUTION.md	Updated existing specification files to add or replace cross-references pointing to DISPUTE_SYSTEM.md and clarified dispute flow behavior including /dispute_details/:id routing, admin shared-key chat behavior, and state transition details.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• New features from v1-reference #16: Modifies dispute lifecycle specifications and admin state handling (admin-took-dispute, admin chat integration) which are documented in the new DISPUTE_SYSTEM.md.
• Dispute is only available on fiatsent or active #14: Constrains dispute action availability to active/fiat-sent order states, which aligns with the dispute filing constraints now documented in DISPUTE_SYSTEM.md.
• docs: add TRADE_EXECUTION.md spec #23: Updates TRADE_EXECUTION.md with dispute flow details and routing changes that are cross-referenced in the new specification.

Poem

🐰 A rabbit hops through docs so neat,
New dispute specs make knowledge complete!
Cross-references bound, the system's so clear,
Admin shared keys and chat flow sincere! 🎓

🚥 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 dispute system spec' accurately reflects the main change: adding a new comprehensive DISPUTE_SYSTEM.md specification file with dispute-related documentation.
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/dispute-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/DISPUTE_SYSTEM.md (1)

199-208: Minor style consideration: "Cross-references" vs "Cross references".

The document uses "Cross references" in the section header, while other parts of the documentation use "cross-reference" with a hyphen. Consider using "Cross-references" for consistency, though both are acceptable.

The cross-reference table is complete and properly bidirectional with the referenced specifications.

🤖 Prompt for AI Agents

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

In @.specify/v1-reference/DISPUTE_SYSTEM.md around lines 199 - 208, The section
header "## 8) Cross references" is inconsistent with the project's hyphenated
style; update that header to "## 8) Cross-references" (adjust the exact string
"## 8) Cross references" in the DISPUTE_SYSTEM.md file) to match the rest of the
docs, and scan nearby headings for the same "cross-reference"/"cross references"
variants to ensure consistent hyphenation across the specification.

🤖 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/DISPUTE_SYSTEM.md:
- Around line 199-208: The section header "## 8) Cross references" is
inconsistent with the project's hyphenated style; update that header to "## 8)
Cross-references" (adjust the exact string "## 8) Cross references" in the
DISPUTE_SYSTEM.md file) to match the rest of the docs, and scan nearby headings
for the same "cross-reference"/"cross references" variants to ensure consistent
hyphenation across the specification.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bbb7094e-d63b-4e2b-9a0a-098d6016241d

📥 Commits

Reviewing files that changed from the base of the PR and between 35e679e and 83b9304.

📒 Files selected for processing (6)

• .specify/v1-reference/DISPUTE_SYSTEM.md
• .specify/v1-reference/NAVIGATION_ROUTES.md
• .specify/v1-reference/ORDER_STATUS_HANDLING.md
• .specify/v1-reference/P2P_CHAT_SYSTEM.md
• .specify/v1-reference/README.md
• .specify/v1-reference/TRADE_EXECUTION.md