Add Single Word

This skill adds individual Arabic words to the flashcard system on demand.

Workflow

•Check for duplicates → Search existing cards
•Lookup translation → Use WebSearch if needed
•Fetch decks → Get available decks
•Suggest deck → Recommend based on word type
•Confirm → Ask user before adding
•Add via API → Create the card

API Configuration

•Base URL: https://learn.rocksbythesea.uk
•API Token: Get from .env.local (API_TOKEN)
•All API requests must include the header: -H "Authorization: Bearer $API_TOKEN"

Step 1: Check for Duplicates

Search all cards to see if the word already exists:

bash

# Get all deck IDs, then check each deck's cards for the word
for id in $(curl -s -H "Authorization: Bearer $API_TOKEN" https://learn.rocksbythesea.uk/api/decks | jq -r '.[].id'); do
  curl -s -H "Authorization: Bearer $API_TOKEN" "https://learn.rocksbythesea.uk/api/decks/$id/cards" | jq -r --arg word "WORD" '.[] | select(.front | contains($word)) | "\(.front) -> \(.back) (deck: \(.deck_id))"'
done

This uses jq to:

•Extract deck IDs
•Search card fronts for the word
•Output matches with translation and deck info

If found, inform the user:

code

"كلب" already exists in deck "Nouns (الأسماء)" with translation "dog"

Step 2: Lookup Translation (if needed)

If the user only provides the Arabic word without translation:

•Use WebSearch to find the English translation
•Present the translation to the user for confirmation

Example search: "Arabic word كلب meaning English translation"

Step 3: Fetch Available Decks

bash

curl -s -H "Authorization: Bearer $API_TOKEN" https://learn.rocksbythesea.uk/api/decks

List the decks with their card counts to help decide placement.

Step 4: Suggest Appropriate Deck

Based on the word type, suggest a deck:

Word Type	Suggested Deck
Noun (person, place, thing)	Nouns (الأسماء)
Adjective (descriptive)	Adjectives (صفات)
Verb (action)	Verbs (الأفعال) - create if needed
Conjunction, preposition	Arabic Basics
Phrase	Phrases - create if needed
Unknown/mixed	Arabic Basics or create new

Step 5: Confirm with User

Present the word and ask for confirmation:

code

Word: كتاب
Translation: book
Suggested deck: Nouns (الأسماء) (ID: 6)

Add this word? Or choose a different deck:
1. Nouns (الأسماء)
2. Adjectives (صفات)
3. Arabic Basics
4. Create new deck...

Step 6: Add via API

bash

curl -X POST "https://learn.rocksbythesea.uk/api/decks/{deck_id}/cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '[{"front": "كتاب", "back": "book"}]'

Step 7: Confirm Success

code

✓ Added "كتاب" (book) to deck "Nouns (الأسماء)"

Examples

Example 1: User provides word only

code

User: add the word مطبخ

1. Check duplicates → Not found
2. WebSearch "مطبخ Arabic meaning" → kitchen
3. Fetch decks → [Arabic Basics, Adjectives, Nouns]
4. Suggest: Nouns (it's a place/thing)
5. Confirm: "Add مطبخ (kitchen) to Nouns?"
6. User confirms → Add via API
7. Report: "✓ Added مطبخ (kitchen) to Nouns"

Example 2: User provides word and translation

code

User: add يكتب - to write

1. Check duplicates → Not found
2. Translation provided: "to write"
3. Fetch decks → [Arabic Basics, Adjectives, Nouns]
4. Suggest: Need "Verbs" deck (doesn't exist)
5. Confirm: "Add يكتب (to write) to new deck 'Verbs (الأفعال)'?"
6. User confirms → Create deck, add card
7. Report: "✓ Created deck 'Verbs' and added يكتب (to write)"

Example 3: Word already exists

code

User: add كلب

1. Check duplicates → Found in Nouns deck
2. Report: "كلب already exists in 'Nouns (الأسماء)' as 'dog'"
3. Ask: "Would you like to add it to a different deck anyway?"

Moving Cards Between Decks

The API doesn't support changing a card's deck_id directly. To move a card:

•Delete the card from the original deck:

bash

curl -X DELETE "https://learn.rocksbythesea.uk/api/cards/{card_id}" \
  -H "Authorization: Bearer $API_TOKEN"

•Recreate it in the new deck:

bash

curl -X POST "https://learn.rocksbythesea.uk/api/decks/{new_deck_id}/cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '[{"front": "...", "back": "...", "notes": "..."}]'

Note: This resets the card's FSRS scheduling data (reviews, stability, etc.)

Notes

•Always check for duplicates first to avoid redundant cards
•Preserve Arabic diacritics (tashkeel) if provided
•If user provides notes or context, include in the notes field
•Use WebSearch for translations when needed
•API Base URL: https://learn.rocksbythesea.uk
•Always include API key header in all requests