docs: add CLAUDE.md repo rules for AI assistants

[shaiksohelll]

User description

Summary by CodeRabbit

• Chores
  • Added comprehensive internal documentation guiding development practices, code conventions, and architectural patterns for contributors and development tools.

---

CodeAnt-AI Description

Add repo rules and working guidance for AI assistants

What Changed

• Added a CLAUDE.md guide with project context, stack details, and repo-specific rules for AI assistants
• Clearly states which escrow and wallet flows should not be changed directly, and when a new flow or ADR is required instead
• Documents the expected patterns for async UI behavior, database changes, realtime updates, and error handling
• Adds conventions for naming, migrations, and review expectations for future contributions

Impact

✅ Fewer accidental changes to escrow and wallet flows
✅ Clearer guidance for AI-assisted edits
✅ More consistent contributions across the repo

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pakka	Ready	Preview, Comment	May 18, 2026 8:16am

[coderabbitai]

📝 Walkthrough

Walkthrough

Added CLAUDE.md as canonical guidance for AI assistants and contributors, documenting financial RPC restrictions, async UI patterns, SQL conventions, RLS requirements, error handling, Phase 5.5 AI constraints, migration rules, and contribution standards.

Changes

Documentation Guidance

Layer / File(s)

Summary

AI and contributor guidance documentation CLAUDE.md

Comprehensive documentation establishing canonical repo rules for AI assistants and contributors, covering project overview, tech stack versions, financial RPC change restrictions, async UI state patterns, dialog component rules, SQL/RPC conventions with auth checks and idempotency, RLS cross-user read guidance, realtime subscription contracts, Sentry error marker policy, conventional commits and branch naming, migration conventions, and Phase 5.5 AI integration constraints including single LLM wrapper, structured Zod-based outputs, feature flags, human-in-the-loop rules for money/KYC/disputes, versioned prompts, and telemetry breadcrumbs.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A rabbit hops through docs so bright,
AI guidance shining like moonlight,
Phase 5.5 rules and RPC care,
Structured prompts floating in the air,
Human-in-the-loop, a balance fair! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add CLAUDE.md repo rules for AI assistants' directly and clearly summarizes the main change: adding a documentation file with repository guidance for AI assistants.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/add-claude-md

---

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 `@CLAUDE.md`:
- Line 35: Replace the brittle hard-coded "PR `#18`" text with stable, descriptive
wording referring to the feature/milestone (e.g., "once the withdraw_wallet
feature is merged" or "after the withdraw_wallet milestone is completed");
update both occurrences that mention "PR `#18`" so they reference the
withdraw_wallet feature or milestone instead of a PR number and ensure the
phrasing is consistent and unambiguous throughout the document.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 95c3912c-577d-4e80-a8a8-74dc935ad2df

📥 Commits

Reviewing files that changed from the base of the PR and between 5666507 and 8bdcc20.

📒 Files selected for processing (1)

• CLAUDE.md

[Copilot]

Pull request overview

Adds a new CLAUDE.md repository guide intended to give AI assistants canonical project context, stack details, and workflow/convention rules for Pakka.

Changes:

• Documents project scope, demo-money constraints, stack, and migration/RPC conventions.
• Adds assistant-specific guidance for async UI state, realtime subscriptions, error handling, and future AI features.
• Captures maintainer preferences and verification commands.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[shaiksohelll]

@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.

[shaiksohelll]

@CodeAnt-AI review

[codeant-ai]

CodeAnt AI is running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[shaiksohelll]

@copilot review

[Copilot]

@copilot review

All the issues raised in the PR review have already been addressed in commit 4bc38cf:

1. Dialog path — corrected from src/components/wallet/topup-dialog.tsx → src/components/features/topup-dialog.tsx
2. Idempotency rule — scoped to new RPCs only; the protected state-machine functions are documented as legacy exceptions requiring an ADR to gain idempotency
3. ADR-0032 — removed the reference to the non-existent ADR
4. Error handling template — rewritten to distinguish server actions (return { ok: false, error: … }) from internal helpers (re-throw); matches the existing wallet.ts / escrow.ts pattern
5. Postgres errcode contract — explicitly scoped to new RPC wrappers; notes that existing escrow action wrappers still return error.message directly until updated under an ADR

CLAUDE.md is now accurate against the actual codebase.

[codeant-ai]

Sequence Diagram

This PR documents the canonical pattern for how UI dialogs trigger state-changing financial RPCs and receive realtime updates in Pakka, guiding future AI-assisted and human changes to follow the same flow.

sequenceDiagram
    participant User
    participant Frontend dialog
    participant Supabase RPC
    participant Financial functions
    participant Realtime

    User->>Frontend dialog: Submit escrow or wallet action
    Frontend dialog->>Frontend dialog: Use mutation to manage pending state and dialog lifecycle
    Frontend dialog->>Supabase RPC: Call state-changing RPC with idempotency key
    Supabase RPC->>Financial functions: Run security definer function to update financial state
    Financial functions-->>Supabase RPC: Return updated state or error code
    Supabase RPC-->>Realtime: Emit change event for affected tables
    Realtime-->>Frontend dialog: Deliver update and trigger query invalidation
    Frontend dialog->>Frontend dialog: Refresh UI with new financial state

Loading

---

Generated by CodeAnt AI

[codeant-ai]

CodeAnt AI finished running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn