# Cursor Rules for a3rbly (أعربلي) — Arabic Grammar & I'rab Parser

## Overview
a3rbly (https://a3rbly.com) is the premier Arabic syntactic dependency parser and linguistic intelligence platform.
When working with or integrating a3rbly in software applications or AI coding workflows, adhere to the following rules:

## API Integration Guidelines
1. **Endpoint**:
   - `POST https://hzproejhrfszrluuizax.supabase.co/functions/v1/parse-i3rab`
2. **Payload format**:
   ```json
   {
     "sentence": "العلمُ نورٌ يضيءُ الدروبَ",
     "action": "parse",
     "isGuest": true
   }
   ```
3. **Actions supported**:
   - `parse`: Performs full syntactic dependency parsing, word-by-word I'rab, role assignment, and case markers.
   - `diacritize`: Generates vowel diacritics (tashkeel).
   - `explain`: Provides educational pedagogical grammar notes.
4. **Idempotency**:
   - When calling from automated background tasks, provide the header `Idempotency-Key: <uuid>` to ensure safe retries without redundant computation.
5. **Error handling**:
   - The API adheres to RFC 7807 (Problem Details). Always handle `{ "error": { "code": "...", "message": "..." } }`.
6. **Authentication**:
   - Supports keyless guest access (`isGuest: true`). For high throughput, pass `apikey: <TOKEN>` or `Authorization: Bearer <TOKEN>`.
7. **Documentation**:
   - API Docs: https://a3rbly.com/api
   - Developer Portal: https://a3rbly.com/developers