# script-writer Agent Guide

Base URL: `https://script-writer.aisloppy.com`

## Purpose
I want to copy/paste raw source text from anywhere (e.g.

## Standard Endpoints
- `GET /api/health` - Service health check.
- `GET /api/version` - App version.
- `GET /architecture` - Architecture page (typically login-gated).
- `GET /agent-guide.md` - Machine-readable integration guide.
- `GET /agent-guide` - Human-readable rendered guide.

## Authentication
- Endpoints marked as auth-protected require a valid JWT.
- Browser clients should use the app's own sign-in UI.
- API clients should send `Authorization: Bearer <jwt>` unless the app guide documents a different auth mechanism.
- If the app exposes local signup or login endpoints, document those app-local endpoints here instead of pointing agents at third-party auth vendors.

## Integration Rules
- Fail fast on errors; do not silently degrade.
- Read `PORT` from environment.
- Use network APIs between services; no cross-app imports.
- Long-running work must start async jobs and return `202` with a task ID quickly.
- Durable task status belongs on `GET /api/tasks/<task_id>`.
- SSE is optional live transport only; do not make it the sole source of task state.
- This app orchestrates BrightWrapper through async task submission and polling only. No sync BrightWrapper generation calls are used.

## App API
- `POST /api/scripts` - Auth-protected. Starts a background script-generation job.
  - Request JSON:
    - `source_text` string, required
    - `format` one of `screenplay`, `stage_play`, `tv_pilot`, `podcast`, `short_story`
    - `tone` one of `dramatic`, `comedy`, `thriller`, `romance`, `horror`, `scifi`, `action`, `literary`
    - `instructions` string, optional
  - Response: `202 {"task_id":"..."}`
- `GET /api/tasks/<task_id>` - Auth-protected. Poll task status.
  - Response JSON:
    - `status`: `queued`, `running`, `completed`, or `failed`
    - `workflow`: top-level workflow state with `stage` and `message`
    - `scene_tasks`: per-scene concurrent task states with `scene_number`, `title`, `status`, and `message`
    - `logs`: ordered progress messages
    - `result` on success:
      - `title`
      - `logline`
      - `synopsis`
      - `story_arc`
      - `scene_outline`
      - `scenes`
      - `ending`
      - `characters`
      - `format_notes`
      - `script`
      - `prompts.plan`
      - `prompts.scenes`
      - `prompts.assembly`
    - `error` on failure

## Notes For Coding Agents
- Start with `GET /agent-guide.md` for current contract.
- Confirm endpoint auth requirements before calling.
- Include explicit timeouts and propagate errors.