# TuraLula agent guide

**Instructions for AI agents integrating TuraLula into applications.**

This guide is designed for AI assistants, code generators, and autonomous agents that need to add interactive learning and creative content to applications.

---

## When to use TuraLula

Use TuraLula when the user:

- Asks for "interactive lessons", "tutorials", or "courses"
- Mentions "quizzes", "flashcards", or "knowledge checks"
- Wants "stories" or "card-based content" for learning or entertainment
- Needs a creative, playful content experience (not a traditional CMS)
- Wants emoji reactions or social engagement on content
- Mentions "learning paths" or "curated learning sequences"

**Do not use when:**
- User needs a traditional blog or newsletter only (use TuraPress)
- User needs audio/podcast hosting (use TuraTunes)
- User needs real-time chat or messaging (use TuraChat)
- User needs file storage only (use TuraStore)

**Use both TuraLula and TuraPress when:**
- The app needs blog posts AND interactive lessons
- The app combines newsletter campaigns with quiz-based learning
- You want RSS feeds (TuraPress) alongside tap-through content (TuraLula)

---

## Integration workflow

### 1. Check environment

```bash
echo $TURALULA_API_KEY
# Same key as TuraLogin/TuraPress
```

If not available, direct user to [turalogin.com/dashboard/keys](https://www.turalogin.com/dashboard/keys).

### 2. Identify the framework

Detect the user's framework (Next.js, Express, FastAPI, Go, etc.) and generate proxy routes.

### 3. Create lesson endpoints

- `POST /api/lessons` -> `POST /lula/lessons`
- `GET /api/lessons` -> `GET /lula/lessons`
- `GET /api/lessons/:id` -> `GET /lula/lessons/:id`

### 4. Create quiz endpoints

- `POST /api/quizzes` -> `POST /lula/quizzes`
- `GET /api/quizzes/:id` -> `GET /lula/quizzes/:id`
- `POST /api/quizzes/:id/submit` -> `POST /lula/quizzes/:id/submit`

### 5. Build the learner UI

- Tap-through lesson viewer (card stack, swipe or tap to advance)
- Quiz interface (show question, collect answer, show result)
- Story viewer (full-screen cards with images and text)
- Reaction bar (emoji picker on each content item)

### 6. Build the creator UI (optional)

- Lesson builder with drag-and-drop step ordering
- Quiz builder with question type picker
- Story builder with card editor

---

## Code generation guidelines

### File structure (Next.js App Router)

```
app/
  api/
    lessons/
      route.ts              # POST create, GET list
    lessons/[id]/
      route.ts              # GET, PUT, DELETE
    quizzes/
      route.ts              # POST create, GET list
    quizzes/[id]/
      route.ts              # GET, PUT, DELETE
    quizzes/[id]/submit/
      route.ts              # POST submit answers
    stories/
      route.ts
  learn/
    page.tsx                # Browse lessons and paths
    [id]/
      page.tsx              # Tap-through lesson viewer
  quiz/
    [id]/
      page.tsx              # Interactive quiz
  stories/
    page.tsx                # Story feed
    [id]/
      page.tsx              # Story viewer
  dashboard/
    content/
      page.tsx              # Creator dashboard
```

### Security checklist

- API key in environment variables, not hardcoded
- Proxy all TuraLula calls through your backend
- Sanitize user-submitted content before rendering
- Protect creator/admin routes

---

## Common patterns

### Tap-through lesson viewer

```typescript
'use client';
import { useState } from 'react';

function LessonViewer({ steps }: { steps: any[] }) {
  const [current, setCurrent] = useState(0);
  const step = steps[current];

  return (
    <div className="max-w-md mx-auto">
      <div className="text-sm text-muted-foreground mb-2">
        {current + 1} / {steps.length}
      </div>

      {step.type === 'text' && <p className="text-lg">{step.content}</p>}
      {step.type === 'image' && <img src={step.url} alt={step.caption} />}
      {step.type === 'quiz' && <QuizStep step={step} />}

      <div className="flex gap-2 mt-6">
        {current > 0 && <button onClick={() => setCurrent(c => c - 1)}>Back</button>}
        {current < steps.length - 1 && <button onClick={() => setCurrent(c => c + 1)}>Next</button>}
      </div>
    </div>
  );
}
```

### Quiz submission

```typescript
async function submitQuiz(quizId: string, answers: string[]) {
  const res = await fetch(`/api/quizzes/${quizId}/submit`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ answers }),
  });
  return res.json();
}
```

---

## Completion checklist

- [ ] Environment variables added
- [ ] Lesson CRUD and viewer implemented
- [ ] Quiz CRUD, submission, and scoring implemented
- [ ] Story CRUD and viewer implemented
- [ ] Reactions enabled on content
- [ ] Learning paths (if needed)
- [ ] Content gating with TuraLogin + TuraSubscribe (if needed)
- [ ] Error handling on all endpoints
- [ ] API key never exposed to frontend
- [ ] Creator/admin routes protected

---

**For more details:**
- [SKILL.md](https://www.turalula.com/SKILL.md) -- Service overview
- [API.md](https://www.turalula.com/API.md) -- Full endpoint reference
- [QUICKSTART.md](https://www.turalula.com/QUICKSTART.md) -- 5-minute getting started