{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "vclaw error response",
  "description": "Stable error-code catalog for vclaw CLI JSON output. The TS source-of-truth is src/video/errors.ts ALL_ERROR_CODES.",
  "type": "object",
  "required": ["code", "message"],
  "properties": {
    "code": { "type": "string" },
    "message": { "type": "string" },
    "details": { "type": "object", "additionalProperties": true }
  },
  "codes": [
    { "code": "invalid_slug", "exitCode": 1, "description": "Slug is missing or fails isProjectSlug validation." },
    { "code": "project_not_found", "exitCode": 1, "description": "Referenced project slug has no workspace on disk." },
    { "code": "missing_required_flag", "exitCode": 1, "description": "A flag required by the subcommand was not provided." },
    { "code": "invalid_flag_value", "exitCode": 1, "description": "A flag was provided but its value is out of range, malformed, or otherwise invalid." },
    { "code": "unknown_subcommand", "exitCode": 1, "description": "The subcommand is not in the dispatch table." },
    { "code": "invalid_mode", "exitCode": 1, "description": "--mode value is not 'storyboard' or 'director'." },
    { "code": "invalid_aspect_ratio", "exitCode": 1, "description": "Aspect ratio is not 16:9 / 9:16 / 1:1." },
    { "code": "image_not_found", "exitCode": 1, "description": "Referenced image file (asset or reference) is not on disk." },
    { "code": "asset_not_found", "exitCode": 1, "description": "Referenced asset (image/video/audio) is not on disk." },
    { "code": "template_not_found", "exitCode": 1, "description": "Referenced template name is not registered." },
    { "code": "character_not_found", "exitCode": 1, "description": "Referenced character name is not in the project's characters/." },
    { "code": "duplicate_project", "exitCode": 1, "description": "vclaw video init on a slug whose workspace already exists." },
    { "code": "directory_not_writable", "exitCode": 1, "description": "Workspace root is not writable." },
    { "code": "invalid_role", "exitCode": 1, "description": "Reference (--ref or --gb-ref) uses a role that's not valid for the sheet's --type." },
    { "code": "invalid_audio_format", "exitCode": 1, "description": "Provided audio file format/container is not supported by the assemble pipeline." },
    { "code": "invalid_video_format", "exitCode": 1, "description": "Provided video file format/container is not supported by the assemble pipeline." },
    { "code": "unsupported_codec", "exitCode": 1, "description": "Audio/video stream uses a codec the assemble pipeline cannot process." },
    { "code": "provider_unreachable", "exitCode": 2, "description": "Provider HTTP / native transport returned a non-recoverable error." },
    { "code": "adapter_command_failed", "exitCode": 2, "description": "User-provided ..._ADAPTER command exited non-zero." },
    { "code": "env_var_missing", "exitCode": 2, "description": "Required env var (e.g. USEAPI_API_TOKEN) is not set for the chosen route." },
    { "code": "native_transport_failed", "exitCode": 2, "description": "native-veo / native-seedance / native-runway hit an internal error." },
    { "code": "schema_validation_failed", "exitCode": 2, "description": "Artifact failed its JSON-Schema validation." },
    { "code": "workspace_corrupt", "exitCode": 2, "description": "projects/<slug>/ has missing or malformed canonical files." },
    { "code": "unexpected_internal_error", "exitCode": 2, "description": "Catch-all for unanticipated exceptions; always a bug." },
    { "code": "tts_failed", "exitCode": 2, "description": "Text-to-speech narration generation failed (provider error or invalid output)." },
    { "code": "music_gen_failed", "exitCode": 2, "description": "Background music generation failed (provider error or invalid output)." },
    { "code": "soundtrack_no_backend", "exitCode": 2, "description": "No music backend is available/configured for soundtrack generation (set credentials for at least one, e.g. KIE_API_KEY)." },
    { "code": "pdf_parse_failed", "exitCode": 2, "description": "PDF slide extraction failed to parse or render the source document." },
    { "code": "ffmpeg_failed", "exitCode": 2, "description": "An FFmpeg subprocess exited non-zero during assemble." },
    { "code": "audio_sync_drift", "exitCode": 2, "description": "Narration/music audio drifted out of sync with video beyond tolerance during stitch." },
    { "code": "storyboard_approval_required", "exitCode": 3, "description": "Director-mode execute requires storyboard.md approval." },
    { "code": "storyboard_review_stale", "exitCode": 3, "description": "Director storyboard review state is 'stale'; re-run storyboard-review." },
    { "code": "execution_blocked_by_readiness", "exitCode": 3, "description": "readiness check reported blockers; resolve before plan/execute." },
    { "code": "spend_confirmation_required", "exitCode": 3, "description": "A paid-provider command was run directly without --dry-run; pass --confirm-spend to authorize the spend." }
  ]
}