# Modo Creator Verse — External Agent Skill

Modo Creator Verse is an AI-powered IP development platform. External AI agents can create and populate IP projects **manually** through the API — using their own LLM to generate content, then writing it directly via tools. **No platform AI credits consumed.**

---

## Authentication

### Bearer Token (Recommended)
Generate at `https://ip-ai.sainskerta.net/settings/api-tokens`.
```
Authorization: Bearer modo-xxxxxxxxxxxxxxxx
```
When using Bearer auth, `userId` is auto-resolved. You do NOT pass it.

### Login (Alternative)
```
POST https://ip-ai.sainskerta.net/api/auth/login
{ "email": "user@example.com", "password": "password" }
→ { "user": { "id": "user-uuid" } }
```

---

## API Endpoints

### Direct Tool Execution (RECOMMENDED for external agents)
```
POST https://ip-ai.sainskerta.net/api/tools/execute
Authorization: Bearer modo-xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "tool": "create_project",
  "args": { "title": "My IP", "medium_type": "anime-series", ... }
}
```

**Zero LLM usage. Zero credits. Just database operations.** Returns tool result directly.

### Agent Chat (Agentic mode)
```
POST https://ip-ai.sainskerta.net/api/agent/chat
Authorization: Bearer modo-xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "messages": [{ "role": "user", "content": "Create a full IP for ..." }]
}
```

Uses the MODO Engine (mesin AI MODO) as tool router. Uses credits for `generate_*` tools.

---

## Three Modes of Operation

### 🤖 Mode A: Agentic (Autopilot)
Endpoint: `/api/agent/chat`

Send a high-level instruction. The platform agent decides which tools to call. Uses **platform credits** for AI content.

```json
{
  "messages": [{ "role": "user", "content": "Create a cyberpunk anime IP called 'Neo-Katana' with 6 characters, hero's journey, full universe. Generate everything." }]
}
```

**Best for**: Quick prototyping, letting the platform handle everything.

### 📝 Mode B: Direct Step-by-Step (ZERO CREDITS)
Endpoint: `/api/tools/execute`

Call each tool directly with YOUR content. Your LLM generates, you write. **No AI, no credits.**

```json
{ "tool": "create_project", "args": { "title": "Neo-Katana", "medium_type": "anime-series", "main_genre": "sci-fi", "description": "A ronin in cyberpunk Tokyo discovers..." } }
```
Then:
```json
{ "tool": "create_character", "args": { "project_id": "<id>", "name": "Kaito", "role": "protagonist", "psychological": { "archetype": "The Hero", "mbti": "ISTP" } } }
```

**Best for**: Full control, own LLM, zero credits, maximum quality.

### 🔀 Mode C: Hybrid
Mix both endpoints! Use Mode B for content you generate, Mode A for platform AI:
- Mode B for characters (your LLM crafts detailed profiles)
- Mode A for `generate_story_all` (platform AI fills beats)
- Mode B for universe (your LLM builds the world)
- Mode A for `generate_scene_plots` (platform AI writes scenes)
- Mode B for universe (your LLM builds the world)
- Mode A for `generate_scene_plots` (platform AI distributes scenes)



## Complete Pipeline (17 Steps — STRICT ORDER)

⚠️ **ORDER MATTERS.** Each step depends on IDs from prior steps. Follow EXACTLY.

### ⚡ UPSERT Behavior (IMPORTANT)
ALL create tools are **idempotent**. If a record already exists:
- `create_story` → updates existing story (not duplicate)
- `create_story_version` → updates existing active version (not duplicate)
- `create_universe_formula` → updates existing formula (not duplicate)
- `create_moodboard` → updates existing active moodboard (not duplicate)
- `create_beats_batch` → upserts beats (ON CONFLICT DO UPDATE)

**Safe to re-run any step** — no duplicates will be created.

### 🛑 EXECUTION RULE (CRITICAL)
**DO NOT RUN STEPS IN PARALLEL.** Because each step depends on the `id` generated by the previous step, you MUST execute these steps sequentially, ONE BY ONE. Wait for the API response from Step N to get the necessary IDs before executing Step N+1. Doing them all at once will cause foreign key errors.

### Overview
```
Step  1: create_project            → Returns project_id
Step  2: create_character (×N)     → Returns character_id[] (5-10 characters)
Step  3: (optional) update_item    → Enrich each character with detail
Step  4: create_story              → Returns story_id (upserts)
Step  5: create_story_version      → Returns story_version_id (upserts)
Step  6: create_beats_batch        → Fills all structure beats (upserts)
Step  7: update_item (want/need)   → Update story_version with want_stages/need_stages
Step  8: create_universe_formula   → Returns universe_id (upserts, AFTER beats)
Step  9: create_moodboard          → Returns moodboard_id (upserts, AFTER universe)
Step 10: update_item (moodboard)   → Key actions per beat via moodboard_items
Step 11: create_scenes_batch       → Returns scene_ids
Step 12: update_item (scenes)      → Enrich scene plots
Step 13: create_scripts_batch      → Screenplay per scene
Step 14: create_shots_batch        → Shot list per scene
Step 15: update_item (prompts)     → Moodboard image prompts
Step 16: update_item (storyboard)  → Storyboard prompts per shot
Step 17: DONE
```

---

## STEP 1: create_project

```json
{
  "title": "string (REQUIRED)",
  "description": "string — logline/premise (1-3 sentences)",
  "medium_type": "feature-film | short-film | tv-series | limited-series | web-series | anime-series | documentary | commercial | music-video",
  "duration": "string — e.g. '24min' for anime, '90min' for film",
  "target_scenes": "number — total target scene count",
  "episode_count": "number — for series formats",
  "main_genre": "action | adventure | animation | comedy | crime | documentary | drama | family | fantasy | horror | mystery | romance | sci-fi | thriller | war | western | musical | sports | slice-of-life | supernatural",
  "sub_genre": "string",
  "theme": "string — core thematic question",
  "tone": "Serious | Humorous | Suspenseful | Emotional | Dark | Lighthearted",
  "core_conflict": "string — central dramatic conflict",
  "story_structure": "hero-journey | save-the-cat | dan-harmon | three-act | freytag | custom",
  "protagonist_name": "string"
}
```

**Returns**: `{ project_id: "uuid" }`

---

## STEP 2: create_character (×5-10)

Call ONCE per character. Create protagonist first, then antagonist, then supporting cast.

```json
{
  "project_id": "uuid (REQUIRED)",
  "name": "string (REQUIRED)",
  "role": "protagonist | antagonist | deuteragonist | tritagonist | love_interest | mentor | sidekick | foil | supporting",
  "age": "string",
  "cast_reference": "string — real actor reference for visual",
  "traits": "string — comma-separated personality traits",

  "physiological": {
    "gender": "Male/Female/Non-binary",
    "height": "e.g. '175cm'",
    "weight": "e.g. '70kg'",
    "ethnicity": "string",
    "bodyType": "Slim | Athletic | Average | Heavy",
    "facialFeatures": "Detailed face description",
    "hairColor": "string",
    "hairStyle": "string",
    "eyeColor": "string",
    "skinTone": "string",
    "distinctiveMarks": "Scars, tattoos, cybernetics, etc.",
    "clothingStyle": "Typical outfit description",
    "voiceType": "Deep | Soft | Raspy | Melodic | Mechanical",
    "physicalCondition": "Healthy | Disabled | Cybernetic | Supernatural"
  },

  "psychological": {
    "archetype": "The Innocent | The Orphan | The Hero | The Caregiver | The Explorer | The Rebel | The Lover | The Creator | The Jester | The Sage | The Magician | The Ruler",
    "mbti": "e.g. INTJ, ENFP",
    "motivation": "What drives them (2-3 sentences)",
    "fears": "Deepest fears",
    "desires": "Core desires",
    "needs": "Internal needs (often unconscious)",
    "alterEgo": "Hidden self or mask they wear",
    "traumatic": "Past trauma that shaped them",
    "personalityType": "Brief personality summary"
  },

  "emotional": {
    "logos": "How they use logic/reason",
    "ethos": "Their moral code/ethics",
    "pathos": "How they connect emotionally",
    "tone": "Emotional default tone",
    "style": "Communication style",
    "mode": "Emotional regulation mode"
  },

  "family": {
    "spouse": "Partner description or 'None'",
    "children": "Children description or 'None'",
    "parents": "Parents description"
  },

  "sociocultural": {
    "affiliation": "Groups, organizations, factions",
    "groupRelationshipLevel": "Loner | Leader | Follower | Outcast",
    "cultureTradition": "Cultural background",
    "language": "Languages spoken",
    "tribe": "Clan/faction/tribe",
    "economicClass": "Rich | Middle | Poor | Outcast"
  },

  "core_beliefs": {
    "faith": "Religious or spiritual beliefs",
    "religionSpirituality": "Detailed spiritual worldview",
    "trustworthy": "How trustworthy they are",
    "willingness": "Willingness to change/grow",
    "vulnerability": "What makes them vulnerable",
    "commitments": "What they're committed to",
    "integrity": "Moral compass description"
  },

  "educational": {
    "graduate": "Education background",
    "achievement": "Key achievements",
    "fellowship": "Mentorship/fellowship"
  },

  "swot_analysis": {
    "strength": "Character strengths (2-3 items)",
    "weakness": "Fatal flaws (2-3 items)",
    "opportunity": "Growth opportunities",
    "threat": "What threatens them"
  }
}
```

**Returns**: `{ character_id: "uuid" }`

---

## STEP 3: Enrich Characters (Optional)

Use `update_item` to add deeper detail:
```json
{
  "table": "characters",
  "id": "character-uuid",
  "updates": {
    "physiological": { "facialFeatures": "..." },
    "psychological": { "motivation": "..." }
  }
}
```

---

## STEP 4: create_story (upserts)

Parent story record. One per project. If story exists, updates it.

```json
{
  "project_id": "uuid (REQUIRED)",
  "premise": "string (REQUIRED) — 1 sentence hook",
  "synopsis": "string (REQUIRED) — 2-3 paragraph summary",
  "global_synopsis": "string — IP-level synopsis for pitching",
  "genre": "string",
  "tone": "string",
  "theme": "string",
  "structure": "string — hero-journey | save-the-cat | dan-harmon | three-act | freytag"
}
```

**Returns**: `{ story_id: "uuid", action: "created_new" | "updated_existing" }`

---

## STEP 5: create_story_version (upserts — BEFORE beats!)

Creates or updates the story version. If active version exists, UPDATES it (no duplicate). **MUST exist BEFORE creating beats.**

```json
{
  "story_id": "uuid (REQUIRED)",
  "project_id": "uuid (REQUIRED)",
  "version_name": "string (REQUIRED) — e.g. 'Episode 1: The Beginning'",
  "episode_number": 1,
  "structure": "hero-journey | save-the-cat | dan-harmon | three-act | freytag (REQUIRED)",
  "premise": "string (REQUIRED) — episode premise",
  "synopsis": "string (REQUIRED) — episode synopsis",
  "genre": "string",
  "tone": "string",
  "theme": "string",
  "conflict": "string — episode's central conflict",
  "ending_type": "happy | sad | bitter_sweet | ambiguous | cliffhanger | twisted",
  "character_ids": ["char-uuid-1", "char-uuid-2", "...all character IDs"]
}
```

**Returns**: `{ version_id: "uuid", action: "created_new" | "updated_existing" }`

---

## STEP 6: create_beats_batch (THE CORE STEP — upserts)

Creates or updates ALL story beats for a version. Uses ON CONFLICT DO UPDATE — safe to re-run.

⚠️ **CRITICAL: Beat keys must be the EXACT labels below. Case-sensitive. No variations.**

### Hero's Journey — 12 beats
```json
{
  "story_version_id": "uuid",
  "beats": [
    { "beat_key": "ordinaryWorld", "beat_content": "[20-80 words: Hero in normal life]", "tension_level": 1 },
    { "beat_key": "callToAdventure", "beat_content": "[20-80 words: Inciting incident]", "tension_level": 2 },
    { "beat_key": "refusalOfCall", "beat_content": "[20-80 words: Hero's resistance]", "tension_level": 1 },
    { "beat_key": "meetingMentor", "beat_content": "[20-80 words: Guide provides wisdom]", "tension_level": 2 },
    { "beat_key": "crossingThreshold", "beat_content": "[20-80 words: Hero commits]", "tension_level": 2 },
    { "beat_key": "testsAlliesEnemies", "beat_content": "[20-80 words: New world challenges]", "tension_level": 2 },
    { "beat_key": "approachCave", "beat_content": "[20-80 words: Approaching danger]", "tension_level": 2 },
    { "beat_key": "ordeal", "beat_content": "[20-80 words: Central crisis]", "tension_level": 3 },
    { "beat_key": "reward", "beat_content": "[20-80 words: Hero gains prize]", "tension_level": 2 },
    { "beat_key": "roadBack", "beat_content": "[20-80 words: Recommitment]", "tension_level": 2 },
    { "beat_key": "resurrection", "beat_content": "[20-80 words: Final test]", "tension_level": 3 },
    { "beat_key": "returnElixir", "beat_content": "[20-80 words: Hero returns changed]", "tension_level": 2 }
  ]
}
```

### Save the Cat — 15 beats
```json
{
  "story_version_id": "uuid",
  "beats": [
    { "beat_key": "openingImage", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "themeStated", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "setup", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "catalyst", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "debate", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "breakIntoTwo", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "bStory", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "funAndGames", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "midpoint", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "badGuysCloseIn", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "allIsLost", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "darkNightOfTheSoul", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "breakIntoThree", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "finale", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "finalImage", "beat_content": "...", "tension_level": 1 }
  ]
}
```

### Dan Harmon Story Circle — 8 beats
```json
{
  "story_version_id": "uuid",
  "beats": [
    { "beat_key": "you", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "need", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "go", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "search", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "find", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "take", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "return", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "change", "beat_content": "...", "tension_level": 1 }
  ]
}
```

### Three Act Structure — 8 beats
```json
{
  "story_version_id": "uuid",
  "beats": [
    { "beat_key": "setup", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "incitingIncident", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "plotPoint1", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "risingAction", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "midpoint", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "plotPoint2", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "climax", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "resolution", "beat_content": "...", "tension_level": 1 }
  ]
}
```

### Freytag's Pyramid — 5 beats
```json
{
  "story_version_id": "uuid",
  "beats": [
    { "beat_key": "exposition", "beat_content": "...", "tension_level": 1 },
    { "beat_key": "risingAction", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "climax", "beat_content": "...", "tension_level": 3 },
    { "beat_key": "fallingAction", "beat_content": "...", "tension_level": 2 },
    { "beat_key": "denouement", "beat_content": "...", "tension_level": 1 }
  ]
}
```

**Tension Levels**: 1 = 🌿 Calm, 2 = 📈 Rising, 3 = 🔥 Intense

**Returns**: `{ beat_ids: ["uuid", ...] }`

---

## STEP 7: Want/Need Matrix (update_item)

Update story_version with character motivation journey:
```json
{
  "table": "story_versions",
  "id": "story-version-uuid",
  "updates": {
    "want_stages": {
      "menginginkan": "What the protagonist initially wants externally",
      "memastikan": "How they commit to pursuing it",
      "mengejar": "How they actively chase it",
      "tercapai": true
    },
    "need_stages": {
      "membutuhkan": "What they internally need (unconscious at first)",
      "menemukan": "How they discover the truth",
      "menerima": "How they accept the change",
      "terpenuhi": true
    },
    "ending_rasa": "Pahit-manis | Puas | Gelisah | Muram | Tenang | Reflektif"
  }
}
```

---

## STEP 8: create_universe_formula (upserts, AFTER beats)

World-building formula. ALL 16 fields should have 2-5 sentences. If exists, updates it.

Fields go **MICRO → MACRO** (personal space → world scale):

```json
{
  "project_id": "uuid (REQUIRED)",
  "universe_name": "string (REQUIRED)",
  "period": "string — time period/era",
  "room_cave": "Most intimate space: protagonist's room/hideout.",
  "house_castle": "Home/castle/base. Architecture, condition.",
  "family_inner_circle": "Family dynamics, inner circle, secrets.",
  "working_office_school": "Workplace/school. Daily routine, power structures.",
  "neighborhood_environment": "Immediate neighborhood. Streets, dangers.",
  "private_interior": "Private spaces and sanctuaries.",
  "rules_of_work": "Rules governing work. Guilds, contracts.",
  "town_district_city": "The city/town. Districts, landmarks.",
  "kingdom_tribe_communal": "Broader community. Clan structures.",
  "country": "The nation. Borders, territories, rivals.",
  "government_system": "Power structure. Democracy, tyranny, etc.",
  "environment_landscape": "Natural landscape. Geography, climate.",
  "society_and_system": "Social hierarchy. Classes, mobility.",
  "sociopolitic_economy": "Political economy. Currency, trade.",
  "sociocultural_system": "Culture, traditions, art, taboos."
}
```

**Returns**: `{ universe_formula_id: "uuid", action: "created_new" | "updated_existing" }`

---

## STEP 9: create_moodboard (upserts, AFTER universe)

Creates or updates the moodboard. One per project.

```json
{
  "project_id": "uuid (REQUIRED)",
  "story_version_id": "uuid",
  "art_style": "cinematic | realistic | anime | ghibli | disney | watercolor | oil-painting | comic | noir | cyberpunk | fantasy-art",
  "version_name": "string — e.g. 'Version 1'"
}
```

**Returns**: `{ moodboard_id: "uuid", action: "created_new" | "updated_existing" }`

---

## STEP 10: Key Actions per Beat (update_item)

Populate key actions for each beat. Each beat should have 5-7 **visually dramatic moments**.

Use `update_item` on `moodboard_items` table:
```json
{
  "table": "moodboard_items",
  "id": "item-uuid",
  "updates": {
    "key_action_description": "Visual description of dramatic moment (1-2 sentences)",
    "characters_involved": ["char-uuid-1", "char-uuid-2"],
    "universe_level": "room_cave | house_castle | town_district_city | etc."
  }
}
```

Each moodboard_item record has these fields:
- `beat_key`: "ordinaryWorld" (camelCase)
- `beat_label`: "Ordinary World" (display label)
- `beat_index`: 1-based order
- `key_action_index`: 1 to N (action within beat)
- `key_action_description`: Visual moment description
- `characters_involved`: Array of character UUIDs
- `universe_level`: Which universe level this takes place in
- `prompt`: Image generation prompt (English, detailed)
- `negative_prompt`: What to avoid in image
- `status`: "empty" | "has_description" | "has_prompt" | "has_image"

---

## STEP 11: create_scenes_batch

Create scene plots distributed across beats. Uses existing active story_version automatically.

```json
{
  "project_id": "uuid (REQUIRED)",
  "story_version_id": "uuid (optional — auto-resolves active version)",
  "scenes": [
    {
      "scene_number": 1,
      "title": "string (REQUIRED) — scene title",
      "synopsis": "string (REQUIRED) — 3-5 sentences what happens",
      "emotional_beat": "string — emotional tone",
      "beat_name": "string (REQUIRED) — beat key in camelCase (e.g. 'ordinaryWorld')",
      "location": "string — INT./EXT. LOCATION - TIME",
      "time_of_day": "day | night | dawn | dusk",
      "characters_present": ["Character Name 1", "Character Name 2"]
    }
  ]
}
```

**Scene count guide** (24min anime):
- Calm beats (🌿): 1-2 scenes
- Rising beats (📈): 2-3 scenes
- Intense beats (🔥): 3-4 scenes
- Total: ~24-30 scenes per episode

**Returns**: `{ scene_ids: ["uuid", ...] }`

---

## STEP 12: Enrich Scenes (update_item)

```json
{
  "table": "scene_plots",
  "id": "scene-uuid",
  "updates": {
    "scene_description": "Full detailed scene description...",
    "emotional_beat": "The emotional arc of this scene...",
    "tension_level": 2
  }
}
```

---

## STEP 13: create_scripts_batch

Screenplays per scene. Use proper screenplay format.

```json
{
  "scripts": [
    {
      "scene_id": "uuid (REQUIRED)",
      "script_content": "INT. KAITO'S APARTMENT - NIGHT\n\nRain beats against windows...\n\nKAITO\n(muttering)\nAnother night alone.\n..."
    }
  ]
}
```

**Screenplay format**: Scene heading → Action lines (present tense) → CHARACTER NAME (caps) → (parenthetical) → Dialogue

**Returns**: `{ count: N }`

---

## STEP 14: create_shots_batch

Shot list per scene. 3-8 shots per scene.

```json
{
  "shots": [
    {
      "scene_id": "uuid (REQUIRED)",
      "shot_number": 1,
      "camera_type": "establishing | wide | full | medium | medium-close-up | close-up | extreme-close-up | pov | over-shoulder | two-shot (REQUIRED)",
      "camera_angle": "eye-level | low-angle | high-angle | dutch | birds-eye | worms-eye",
      "camera_movement": "static | pan | tilt | dolly | tracking | crane | handheld | zoom | steadicam",
      "duration": 5,
      "framing": "What's in frame",
      "action": "string (REQUIRED) — What happens",
      "blocking": "Character positions/movements",
      "audio": "Sound effects, music, dialogue",
      "notes": "Director's notes"
    }
  ]
}
```

**Returns**: `{ count: N }`

---

## STEP 15-16: Image Prompts (update_item)

### Moodboard prompts (Step 15)
```json
{
  "table": "moodboard_items",
  "id": "item-uuid",
  "updates": {
    "prompt": "Detailed English prompt: 'Cyberpunk ronin in neon-lit rain, katana glowing blue, cinematic lighting, 8K'",
    "negative_prompt": "blurry, low quality, distorted, text, watermark",
    "status": "has_prompt"
  }
}
```

### Storyboard prompts (Step 16)
```json
{
  "table": "scene_plots",
  "id": "scene-uuid",
  "updates": {
    "image_prompt": "Detailed shot-specific prompt...",
    "negative_prompt": "blurry, low quality..."
  }
}
```

---

## CRUD Tools Reference

### update_item
```json
{
  "table": "projects | characters | story_versions | beat_snapshots | scene_plots | scene_shots | moodboards | moodboard_items | universe_formulas",
  "id": "uuid",
  "updates": { "field": "value" }
}
```

### soft_delete / restore_item
```json
{ "table": "string", "id": "uuid" }
```

### Query Tools
| Tool | Returns |
|------|---------|
| `list_projects` | All user projects |
| `get_project_summary` | Full project with characters, versions, counts |
| `get_credit_balance` | Credit balance |

---

## Quality Checklists

### Character Quality
- [ ] All 7 dimensions filled (physiological, psychological, emotional, family, sociocultural, core_beliefs, SWOT)
- [ ] MBTI + Jungian archetype assigned
- [ ] Protagonist/antagonist have contrasting archetypes
- [ ] Each character has unique voice and motivation
- [ ] SWOT creates dramatic tension between characters

### Story Quality
- [ ] Premise: Single powerful sentence
- [ ] Synopsis: 2-3 paragraphs (beginning/middle/end)
- [ ] Every beat: 20-80 words of specific story content
- [ ] Tension arc: Calm → Rising → Intense → Resolution
- [ ] Want vs Need: External desire vs internal growth
- [ ] Ending type matches thematic resolution

### Universe Quality
- [ ] All 16 fields filled with 2-5 sentences each
- [ ] Micro→macro progression coherent
- [ ] World rules internally consistent
- [ ] Setting creates conflict opportunities

---

## DB Schema Quick Reference

### scene_plots (actual columns)
`story_version_id`, `beat_key`, `scene_number`, `scene_title`, `scene_description`, `scene_location`, `scene_time`, `characters_present` (text[]), `emotional_beat`, `tension_level`, `image_prompt`, `negative_prompt`

### scene_shots (actual columns)
`scene_plot_id`, `shot_number`, `shot_type`, `shot_size`, `shot_angle`, `shot_description`, `duration_seconds`, `camera_movement`, `audio_notes`, `visual_notes`, `dialogue`, `action`

### moodboard_items (actual columns)
`moodboard_id`, `beat_key`, `beat_label`, `beat_content`, `beat_index`, `key_action_index`, `key_action_description`, `characters_involved`, `universe_level`, `prompt`, `negative_prompt`, `image_url`, `status`

---

## Error Codes
| Status | Meaning |
|--------|---------|
| 400 | Bad request / missing parameters |
| 401 | Unauthorized / invalid token |
| 402 | Insufficient credits (only for generate_* tools — manual create tools are FREE) |
| 403 | Permission denied |
| 404 | Resource not found |
| 500 | Server error |

---

## Reference: All Dropdown/Enum Options

*These are the exact string values you should use when filling out fields that require specific options.* 

### 🧍 CHARACTER OPTIONS

### Character Role

**Values:** `protagonist` | `antagonist` | `deuteragonist` | `mentor` | `love-interest` | `sidekick` | `rival` | `comic-relief` | `support` | `background`

- `protagonist` - Protagonist (Main Hero)
- `antagonist` - Antagonist (Main Villain)
- `deuteragonist` - Deuteragonist (Secondary Lead)
- `mentor` - Mentor
- `love-interest` - Love Interest
- `sidekick` - Sidekick
- `rival` - Rival
- `comic-relief` - Comic Relief
- `support` - Supporting Character
- `background` - Background Character

### Gender

**Values:** `male` | `female` | `non-binary`

- `male` - Male
- `female` - Female
- `non-binary` - Non-Binary

### Age Range

**Values:** `child` | `teen` | `young-adult` | `adult` | `middle-aged` | `senior`

- `child` - Child (5-12)
- `teen` - Teen (13-17)
- `young-adult` - Young Adult (18-25)
- `adult` - Adult (26-40)
- `middle-aged` - Middle Aged (41-55)
- `senior` - Senior (56+)

### Ethnicity

**Values:** `asian-east` | `asian-southeast` | `asian-south` | `middle-eastern` | `african` | `caucasian` | `latino` | `mixed` | `fantasy`

- `asian-east` - East Asian
- `asian-southeast` - Southeast Asian
- `asian-south` - South Asian
- `middle-eastern` - Middle Eastern
- `african` - African
- `caucasian` - Caucasian
- `latino` - Latino/Hispanic
- `mixed` - Mixed
- `fantasy` - Fantasy Race

### Skin Tone

**Values:** `very-fair` | `fair` | `light` | `medium` | `tan` | `olive` | `brown` | `dark-brown` | `dark`

- `very-fair` - Very Fair
- `fair` - Fair
- `light` - Light
- `medium` - Medium
- `tan` - Tan
- `olive` - Olive
- `brown` - Brown
- `dark-brown` - Dark Brown
- `dark` - Dark

### Body Type

**Values:** `slim` | `athletic` | `average` | `muscular` | `curvy` | `plus-size` | `petite` | `tall`

- `slim` - Slim
- `athletic` - Athletic
- `average` - Average
- `muscular` - Muscular
- `curvy` - Curvy
- `plus-size` - Plus Size
- `petite` - Petite
- `tall` - Tall

### Archetype (Psychological)

**Values:** `the-innocent` | `the-orphan` | `the-hero` | `the-caregiver` | `the-explorer` | `the-rebel` | `the-lover` | `the-creator` | `the-jester` | `the-sage` | `the-magician` | `the-ruler`

- `the-innocent` - The Innocent
- `the-orphan` - The Orphan
- `the-hero` - The Hero
- `the-caregiver` - The Caregiver
- `the-explorer` - The Explorer
- `the-rebel` - The Rebel
- `the-lover` - The Lover
- `the-creator` - The Creator
- `the-jester` - The Jester
- `the-sage` - The Sage
- `the-magician` - The Magician
- `the-ruler` - The Ruler

### 📖 STORY OPTIONS

### Medium Type

**Values:** `feature-film` | `short-film` | `tv-series` | `limited-series` | `web-series` | `anime-series` | `documentary` | `commercial` | `music-video`

- `feature-film` - Feature Film
- `short-film` - Short Film
- `tv-series` - TV Series (Episode)
- `limited-series` - Limited Series (Episode)
- `web-series` - Web Series (Episode)
- `anime-series` - Anime Series (Episode)
- `documentary` - Documentary
- `commercial` - Commercial/Ad
- `music-video` - Music Video

### Genre

**Values:** `action` | `adventure` | `animation` | `comedy` | `crime` | `documentary` | `drama` | `family` | `fantasy` | `horror` | `mystery` | `romance` | `sci-fi` | `thriller` | `war` | `western` | `musical` | `sports` | `slice-of-life` | `supernatural`

- `action` - Action
- `adventure` - Adventure
- `animation` - Animation
- `comedy` - Comedy
- `crime` - Crime
- `documentary` - Documentary
- `drama` - Drama
- `family` - Family
- `fantasy` - Fantasy
- `horror` - Horror
- `mystery` - Mystery
- `romance` - Romance
- `sci-fi` - Sci-Fi
- `thriller` - Thriller
- `war` - War
- `western` - Western
- `musical` - Musical
- `sports` - Sports
- `slice-of-life` - Slice of Life
- `supernatural` - Supernatural

### Tone

**Values:** `light-hearted` | `dramatic` | `dark` | `comedic` | `suspenseful` | `romantic` | `action-packed` | `inspirational` | `melancholic` | `satirical`

- `light-hearted` - Light-Hearted
- `dramatic` - Dramatic
- `dark` - Dark
- `comedic` - Comedic
- `suspenseful` - Suspenseful
- `romantic` - Romantic
- `action-packed` - Action-Packed
- `inspirational` - Inspirational
- `melancholic` - Melancholic
- `satirical` - Satirical

### Story Structure

**Values:** `hero-journey` | `save-the-cat` | `dan-harmon` | `three-act` | `freytag` | `custom`

- `hero-journey` - Hero's Journey
- `save-the-cat` - Save the Cat
- `dan-harmon` - Dan Harmon Story Circle
- `three-act` - Three Act Structure
- `freytag` - Freytag's Pyramid
- `custom` - Custom Structure

### Core Conflict

**Values:** `person-vs-person` | `person-vs-self` | `person-vs-society` | `person-vs-nature` | `person-vs-technology` | `person-vs-supernatural` | `person-vs-fate`

- `person-vs-person` - Person vs Person
- `person-vs-self` - Person vs Self
- `person-vs-society` - Person vs Society
- `person-vs-nature` - Person vs Nature
- `person-vs-technology` - Person vs Technology
- `person-vs-supernatural` - Person vs Supernatural
- `person-vs-fate` - Person vs Fate/Destiny

### Theme

**Values:** `love` | `family` | `friendship` | `revenge` | `redemption` | `justice` | `power` | `identity` | `survival` | `sacrifice` | `hope` | `loss` | `coming-of-age` | `good-vs-evil`

- `love` - Love & Relationships
- `family` - Family
- `friendship` - Friendship
- `revenge` - Revenge
- `redemption` - Redemption
- `justice` - Justice
- `power` - Power & Corruption
- `identity` - Identity & Self-Discovery
- `survival` - Survival
- `sacrifice` - Sacrifice
- `hope` - Hope
- `loss` - Loss & Grief
- `coming-of-age` - Coming of Age
- `good-vs-evil` - Good vs Evil

### 🌌 UNIVERSE OPTIONS

### Setting Era

**Values:** `prehistoric` | `ancient` | `medieval` | `renaissance` | `colonial` | `industrial` | `victorian` | `early-modern` | `modern` | `contemporary` | `near-future` | `far-future` | `post-apocalyptic` | `alternate-history`

- `prehistoric` - Prehistoric
- `ancient` - Ancient (before 500 AD)
- `medieval` - Medieval (500-1500)
- `renaissance` - Renaissance (1400-1600)
- `colonial` - Colonial Era
- `industrial` - Industrial Revolution
- `victorian` - Victorian Era
- `early-modern` - Early Modern (1900-1950)
- `modern` - Modern (1950-2000)
- `contemporary` - Contemporary (2000-Present)
- `near-future` - Near Future (2030-2100)
- `far-future` - Far Future (2100+)
- `post-apocalyptic` - Post-Apocalyptic
- `alternate-history` - Alternate History

### Setting Location

**Values:** `urban-city` | `suburban` | `rural` | `village` | `island` | `mountain` | `forest` | `desert` | `ocean` | `arctic` | `jungle` | `space-station` | `spaceship` | `alien-planet` | `underground` | `underwater` | `fantasy-realm`

- `urban-city` - Urban City
- `suburban` - Suburban
- `rural` - Rural
- `village` - Village
- `island` - Island
- `mountain` - Mountain
- `forest` - Forest
- `desert` - Desert
- `ocean` - Ocean/Sea
- `arctic` - Arctic/Polar
- `jungle` - Jungle
- `space-station` - Space Station
- `spaceship` - Spaceship
- `alien-planet` - Alien Planet
- `underground` - Underground
- `underwater` - Underwater
- `fantasy-realm` - Fantasy Realm

### World Type

**Values:** `real-world` | `alternate-earth` | `high-fantasy` | `low-fantasy` | `urban-fantasy` | `sci-fi-hard` | `sci-fi-soft` | `cyberpunk` | `steampunk` | `dieselpunk` | `dystopia` | `utopia` | `supernatural`

- `real-world` - Real World
- `alternate-earth` - Alternate Earth
- `high-fantasy` - High Fantasy
- `low-fantasy` - Low Fantasy
- `urban-fantasy` - Urban Fantasy
- `sci-fi-hard` - Hard Sci-Fi
- `sci-fi-soft` - Soft Sci-Fi
- `cyberpunk` - Cyberpunk
- `steampunk` - Steampunk
- `dieselpunk` - Dieselpunk
- `dystopia` - Dystopia
- `utopia` - Utopia
- `supernatural` - Supernatural

### Technology Level

**Values:** `primitive` | `medieval` | `early-industrial` | `modern` | `near-future` | `advanced` | `post-singularity` | `mixed`

- `primitive` - Primitive
- `medieval` - Medieval
- `early-industrial` - Early Industrial
- `modern` - Modern
- `near-future` - Near Future
- `advanced` - Advanced
- `post-singularity` - Post-Singularity
- `mixed` - Mixed/Anachronistic

### Magic System

**Values:** `none` | `soft` | `hard` | `elemental` | `divine` | `chi-ki` | `psychic` | `alchemy` | `technology-magic`

- `none` - No Magic
- `soft` - Soft Magic (Undefined Rules)
- `hard` - Hard Magic (Defined Rules)
- `elemental` - Elemental Magic
- `divine` - Divine/Religious Magic
- `chi-ki` - Chi/Ki/Life Force
- `psychic` - Psychic Powers
- `alchemy` - Alchemy
- `technology-magic` - Technology as Magic

### 🎨 MOODBOARD OPTIONS

### Art Style (Main Moodboard)

**Values:** `realistic` | `semi-realistic` | `anime` | `cartoon` | `3d-render` | `pixel-art` | `watercolor` | `oil-painting` | `comic-book` | `minimalist` | `noir` | `retro` | `cyberpunk` | `steampunk`

- `realistic` - Realistic
- `semi-realistic` - Semi-Realistic
- `anime` - Anime
- `cartoon` - Cartoon
- `3d-render` - 3D Render
- `pixel-art` - Pixel Art
- `watercolor` - Watercolor
- `oil-painting` - Oil Painting
- `comic-book` - Comic Book
- `minimalist` - Minimalist
- `noir` - Noir
- `retro` - Retro
- `cyberpunk` - Cyberpunk
- `steampunk` - Steampunk

### Color Palette

**Values:** `vibrant` | `pastel` | `muted` | `monochrome` | `warm` | `cool` | `earth` | `neon` | `dark` | `high-contrast`

- `vibrant` - Vibrant
- `pastel` - Pastel
- `muted` - Muted
- `monochrome` - Monochrome
- `warm` - Warm Tones
- `cool` - Cool Tones
- `earth` - Earth Tones
- `neon` - Neon
- `dark` - Dark
- `high-contrast` - High Contrast

### Lighting

**Values:** `natural` | `studio` | `dramatic` | `soft` | `golden-hour` | `blue-hour` | `neon` | `candlelight` | `moonlight` | `high-key` | `low-key`

- `natural` - Natural Light
- `studio` - Studio Lighting
- `dramatic` - Dramatic
- `soft` - Soft
- `golden-hour` - Golden Hour
- `blue-hour` - Blue Hour
- `neon` - Neon Lights
- `candlelight` - Candlelight
- `moonlight` - Moonlight
- `high-key` - High Key
- `low-key` - Low Key

### Camera Angle

**Values:** `eye-level` | `low-angle` | `high-angle` | `birds-eye` | `worms-eye` | `dutch-angle` | `over-shoulder` | `close-up` | `extreme-close-up` | `wide-shot` | `establishing`

- `eye-level` - Eye Level
- `low-angle` - Low Angle
- `high-angle` - High Angle
- `birds-eye` - Bird's Eye View
- `worms-eye` - Worm's Eye View
- `dutch-angle` - Dutch Angle
- `over-shoulder` - Over the Shoulder
- `close-up` - Close-Up
- `extreme-close-up` - Extreme Close-Up
- `wide-shot` - Wide Shot
- `establishing` - Establishing Shot

---

## 🚀 Appendix: Full Pipeline Example (TypeScript / Node.js)

For external agents connecting directly, here is a functional example of how you chain the API calls step-by-step. Let this script be your knowledge base on how to orchestrate a Full IP Pipeline correctly.

```typescript
/**
 * Example: Modo Creator Verse - End-to-End Pipeline
 * Run this snippet in your agent's execution environment.
 */

async function callTool(toolName: string, args: any, auth: string) {
    const res = await fetch('https://ip-ai.sainskerta.net/api/tools/execute', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Authorization': auth },
        body: JSON.stringify({ tool: toolName, args })
    });
    return await res.json();
}

async function runPipeline() {
    const AUTH = "Bearer modo-xxxxxxxxxxxxxxxx";

    // 1. Create Project
    console.log("1. Creating Project...");
    const proj = await callTool("create_project", {
        title: "Cyberpunk Ronin",
        description: "A rogue samurai in Neo-Tokyo",
        medium_type: "anime-series",
        main_genre: "sci-fi"
    }, AUTH);
    const projectId = proj.id;

    // 2. Create Characters
    console.log("2. Creating Characters...");
    const char1 = await callTool("create_character", {
        project_id: projectId,
        name: "Ren",
        role: "protagonist",
        psychological: { archetype: "the-rebel" }
    }, AUTH);

    // 3. Create Story 
    console.log("3. Creating Story...");
    const story = await callTool("create_story", {
        project_id: projectId,
        premise: "Ren must hack the mainframe to save his sister.",
        synopsis: "In 2099 Neo-Tokyo, a lone cyber-ronin...",
        structure: "hero-journey"
    }, AUTH);

    // 4. Create Story Version (Episode)
    console.log("4. Creating Story Version...");
    const version = await callTool("create_story_version", {
        project_id: projectId,
        story_id: story.story_id,
        version_name: "Episode 1: The Awakening",
        structure: "hero-journey",
        premise: "Ren discovers his sister is missing.",
        synopsis: "The episode begins with an explosion..."
    }, AUTH);
    const versionId = version.version_id;

    // 5. Generate Beats (CRITICAL: MUST MATCH EXACT CAMELCASE KEYS)
    console.log("5. Generating Beats...");
    await callTool("create_beats_batch", {
        story_version_id: versionId,
        beats: [
            { beat_key: "ordinaryWorld", beat_content: "Ren in his slum apartment", tension_level: 1 },
            { beat_key: "callToAdventure", beat_content: "He gets a mysterious text", tension_level: 2 }
            // ... complete all beats based on chosen structure ...
        ]
    }, AUTH);

    // 6. Create Universe Formula
    console.log("6. Building Universe...");
    await callTool("create_universe_formula", {
        project_id: projectId,
        universe_name: "Neo-Tokyo 2099",
        room_cave: "A tiny 2x2 capsule room filled with cables."
        // ... fill other 15 fields ...
    }, AUTH);

    // 7. Generate Scene Plots Distributed Over Beats
    console.log("7. Generating Scene Plots...");
    await callTool("create_scenes_batch", {
        project_id: projectId,
        story_version_id: versionId, // Optional, but recommended
        scenes: [
            {
                scene_number: 1,
                title: "Waking up",
                synopsis: "Ren wakes up slowly in cold sweat.",
                location: "INT. REN'S CAPSULE - MORNING",
                beat_name: "ordinaryWorld", // Match exact camelCase
                characters_present: [char1.character_id]
            }
        ]
    }, AUTH);

    console.log("✅ Pipeline Completed Successfully!");
}
```

*Modo Creator Verse v2.0 — https://ip-ai.sainskerta.net*