.env.example

# Discord
DISCORD_BOT_TOKEN=
MOVIE_CHANNEL_ID=322822813549461535

# Anthropic
ANTHROPIC_API_KEY=
# Main (creative) model: the writer subagent, dialogue, storyboards, critiques.
ANTHROPIC_MODEL=claude-fable-5-1
# Orchestrator model for the Discord/web agent loop (tool routing, searches,
# status replies). When it differs from ANTHROPIC_MODEL, the loop runs
# two-tier: creative text tools move behind the delegate_writing tool, which
# spawns a writer subagent on ANTHROPIC_MODEL. Set it EQUAL to ANTHROPIC_MODEL
# to disable delegation and restore single-model behavior.
ANTHROPIC_AGENT_MODEL=claude-sonnet-5
# Output-token cap per writer-subagent request (thinking counts against it).
ANTHROPIC_WRITER_MAX_TOKENS=16000
# Short auxiliary passes: prompt enhancement, vision captioning, reference
# selection, PDF filename inference. Split out so the batch vision work can be
# moved to a cheaper model without touching the creative surface.
ANTHROPIC_ENHANCER_MODEL=claude-fable-5-1
# Per-turn output token cap. 4096 is too tight for routine multi-tool turns
# (narrative + create_beat + update_character) and causes silent tool-call
# truncation. 16000 leaves comfortable headroom; you only pay for tokens
# actually generated.
ANTHROPIC_MAX_TOKENS=16000

# Google Gemini ("Nano Banana" image generation). Optional — if unset,
# generate_image returns a friendly error and other tools work normally.
GEMINI_API_KEY=

# Vertex AI service account JSON file on the HOST. docker-compose bind-mounts
# this path to /secrets/alexa2.json inside the container. If you use Vertex,
# also set GOOGLE_APPLICATION_CREDENTIALS=/secrets/alexa2.json (and
# GEMINI_VERTEX_PROJECT) below. Leave unset for local dev without Vertex —
# defaults to /dev/null so the bind mount stays valid.
GOOGLE_APPLICATION_CREDENTIALS_HOST_PATH=
GOOGLE_APPLICATION_CREDENTIALS=
GEMINI_VERTEX_PROJECT=

# OpenAI (gpt-image-2). Optional — required for `provider: 'openai'` on
# generate_image / edit_image and for the web character/scene-sheet +
# storyboard "OpenAI" model option. If unset, those callers return a friendly
# error and Nano Banana keeps working normally.
OPENAI_API_KEY=
# Optional: per-request timeout in ms (default 600000 = 10 minutes).
OPENAI_IMAGE_TIMEOUT_MS=

# TheMovieDB (TMDB) v4 Read Access Token. Optional — if unset, the tmdb_*
# tools return a friendly error and other tools work normally.
TMDB_READ_ACCESS_TOKEN=

# fal.ai video generation. Optional — without FAL_KEY the "Generate video"
# button on a storyboard scene surfaces a friendly error and everything else
# keeps working. The default model is Kling 3 Pro (start frame + end frame +
# character "elements" from characters_in_scene + native audio synthesis,
# 3–15s). The SPA dialog lets you switch per-render to Veo 3.1 first-last-
# frame or Kling AI Avatar v2 Pro (image + audio → true lip-sync).
FAL_KEY=
# FAL_DEFAULT_VIDEO_MODEL=kling-3-pro
# FAL_STORAGE_LIFETIME_DAYS=7

# ElevenLabs TTS/voice cloning API. Optional — if unset, the ElevenLabs
# playground tab disables itself and /api/eleven/* endpoints return 503.
ELEVEN_LABS_KEY=

# Tavily web search API. Optional — if unset, the tavily_* tools return a
# friendly error and other tools work normally.
TAVILY_API_KEY=

# Semantic search (RAG). Set VOYAGE_API_KEY to enable; the bot uses Voyage
# for embeddings (Anthropic-recommended). ChromaDB runs as a docker-compose
# service and the bot reaches it automatically — no CHROMA_URL needed for
# either docker-compose mode or local dev (defaults to http://localhost:8599,
# which is what `docker compose up -d chroma` publishes on the host).
# If Chroma isn't running, screenplay_search returns a friendly fallback
# and the rest of the bot works normally.
VOYAGE_API_KEY=
# VOYAGE_MODEL=voyage-3         # change embedding model
# CHROMA_URL=                   # override only for non-default Chroma host
# CHROMA_PORT=8599              # host port published by the chroma service
# CHROMA_COLLECTION=screenplay  # override only if running multiple projects on one Chroma
# RAG_DEBOUNCE_MS=1000          # debounce window for live reindexing
# RAG_MESSAGE_WINDOW=5000       # most-recent N messages kept indexed per channel
# RAG_DEFAULT_K=8               # default top-k for screenplay_search
# RAG_PRUNE_EVERY_N=100         # run message-window prune every N inserts

# MongoDB
MONGO_URI=mongodb://mongo:27017
MONGO_DB=screenplay

# Optional
LOG_LEVEL=info
PDF_EXPORT_DIR=/data/exports

# Web server (PDF download fallback). The bot starts an Express server on WEB_PORT
# and posts a download link alongside the Discord PDF attachment. WEB_PUBLIC_BASE_URL
# is what the link uses; if unset the link defaults to http://localhost:${WEB_PORT}.
WEB_PORT=3000
WEB_PUBLIC_BASE_URL=

# Hocuspocus collaborative editing WebSocket server.
# 3001 is held by Windows IP Helper service in this WSL2 setup, so use 3010.
# HOCUSPOCUS_PUBLIC_URL is what the SPA's /api/info hands the browser; must be
# reachable from the browser (e.g. ws://localhost:3010 for local dev).
HOCUSPOCUS_PORT=3010
HOCUSPOCUS_PUBLIC_URL=ws://localhost:3010

# MCP server for command-line coding agents (Claude Code, Codex): they read the
# beats and dialogue and plan/store the Scenes tab. Streamable HTTP at
# http://localhost:${MCP_PORT}/mcp, NO auth — docker-compose publishes it on
# 127.0.0.1 only. MCP_PORT=0 turns it off. Requests are refused unless their
# Host header is one of MCP_ALLOWED_HOSTS (comma-separated; `*` = any).
#   claude mcp add --transport http screenplay http://localhost:3002/mcp
# MCP_PORT=3002
# MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]
# MCP_PUBLIC_URL=               # base URL agents are told to upload files to

# Permission system master switch. When set, the SPA login name matching this
# value (case-insensitive) is the admin: only they can create/rename/delete
# projects, see the Admin page, and grant per-project access — everyone else
# sees only the projects they've been granted (new signups start with none;
# a Discord multi-select posted after approval assigns them). Unset = legacy
# open mode: every session sees and edits every project.
# Before setting this on an existing deployment, run
#   docker compose exec bot node scripts/migrate-users.js
# so existing users are grandfathered with access to all current projects.
ADMIN_USERNAME=

# Deploy target for ./deploy.sh — user@host:/absolute/path on the production box
# where rsync will upload the source and where 'docker compose' will run.
# Only used by the deploy script; the bot itself ignores this.
SSH_PATH=

# ComfyUI video provider (Prompts tab → cut → Generate video → ComfyUI, and the
# Prompts-tab "Render beat" job). DEV ONLY for now: production leaves
# COMFYUI_URL unset, the UI and the agent say "ComfyUI rendering is disabled on
# this server", and the fal.ai path is unaffected. The bot spawns the comfy-mcp
# stdio server (COMFY_MCP_COMMAND, default `comfy-mcp` on PATH — the dev image
# installs it; locally `uv tool install comfy-mcp`) and comfy-cli talks to the
# ComfyUI that COMFYUI_URL names.
#   Local dev without docker: ComfyUI on this machine (or the Windows side of
#   WSL with mirrored networking) → COMFYUI_URL=http://127.0.0.1:8188 and
#   COMFY_BIN pointing at the uv tool's `comfy`.
#   Dev compose stack: docker-compose.dev.yml sets COMFYUI_URL itself (a socat
#   forward inside the container → the host bridge → the WSL host's
#   127.0.0.1:8188, i.e. the Windows ComfyUI) — nothing to add here.
# COMFYUI_URL=http://127.0.0.1:8188
# COMFY_MCP_COMMAND=comfy-mcp
# COMFY_BIN=/home/you/.local/share/uv/tools/comfy-mcp/bin/comfy
# COMFY_WORK_DIR=            # per-job scratch; defaults to <tmp>/screenplay-comfy
# COMFY_TEMPLATE_DIR=data/comfy/templates
# COMFY_POLL_INTERVAL_MS=4000   # job status poll (min 500)
# COMFY_JOB_TIMEOUT_MS=3600000  # give up on a render after this (min 10000)