# Completeness adds (Codex review §Completeness Gaps): major entrypoints + ref paths
# that the per-subsystem fan-out missed. Grouped here for one clean diff; build_topology
# merges by node type regardless of source file.
subsystem: completeness

entrypoints:
  - id: run_overnight_cli
    file: recoil/pipeline/cli/run_overnight.py
    symbol: main
    invoke: "python3 recoil/pipeline/cli/run_overnight.py <project> <ep> [...]"
    kind: cli
    summary: >
      Autonomous overnight production entry over EpisodeRunner — the unattended sibling of
      generate.py. Loops episode batches without an interactive operator.
    capabilities: [orchestration]
    produces: [persisted_scene, ops_log]
    reduced_tier: always
    risk_level: high

  - id: dispatch_cli
    file: recoil/pipeline/tools/dispatch_cli.py
    symbol: main
    invoke: "python3 recoil/pipeline/tools/dispatch_cli.py --project <p> --model <m> [--shot|--shots|--start-frame ...] [--ref-video --audio-url --generate-audio]"
    kind: cli
    summary: >
      Major manual/test generation entry over dispatch()/StepRunner — single-shot i2v, r2v_multi,
      keyframe, talking-shot, ad-hoc refs. The hand-dispatch path that bypasses plan loading.
    capabilities: [dispatch_entry_point, worksurface_execution]
    produces: [video_take_mp4, receipts_jsonl]
    reduced_tier: always
    risk_level: high

  - id: generate_composite_sheet_cli
    file: recoil/pipeline/tools/generate_composite_sheet.py
    symbol: main
    invoke: "python3 recoil/pipeline/tools/generate_composite_sheet.py --project <p> --entity <id> ..."
    kind: cli
    summary: >
      THE writer for the composite-sheet ref system (sheets/sheet_v1.png) that the video path
      consumes via resolve_sheet_asset (the bundle sheet route). Without a generated sheet,
      use_composite_sheets silently falls back to the two-pass angle path.
    capabilities: [ref_resolution]
    produces: [composite_sheets]
    risk_level: medium

  - id: breakdown_gate_cli
    file: recoil/pipeline/tools/breakdown_gate_cli.py
    symbol: main
    invoke: "python3 recoil/pipeline/tools/breakdown_gate_cli.py --project <p> --episode <n>"
    kind: cli
    summary: >
      Gate over the mention_ledger (Gate-A breakdown readiness) — the breakdown counterpart to
      the extractor; ratifies the per-episode scene mention ledger before board/r2v consume it.
    capabilities: [output_layout]
    produces: [mention_ledger]
    risk_level: medium

routes:
  - id: board_artifact_video_injection_route
    capability: ref_resolution
    surface: video
    entry: recoil/pipeline/_lib/dispatch_payload.py::_collect_reference_images
    resolves_via: recoil/pipeline/_lib/dispatch_payload.py::_resolve_board_artifact
    ref_kind: board_plate
    gated_by: board_gated
    fallback_route: null
    risk_level: medium    # the approved board image is appended as the FINAL board_1 ref on the video payload (board→video bridge)

  - id: keyframe_lookbundle_route
    capability: ref_resolution
    surface: keyframe
    entry: recoil/execution/step_runner.py::StepRunner.execute_keyframe
    resolves_via: recoil/execution/step_runner.py::StepRunner._resolve_look_bundle
    ref_kind: look_bundle
    gated_by: null
    fallback_route: null
    risk_level: medium    # keyframe gen compiles a budgeted LookBundle (bound Look + Identities) → KeyframeRefBundle; a 3rd ref-resolution surface beyond board+video

artifacts:
  - id: board_review_comments_json
    path: "{project}/prep/ep_NNN/storyboards/board_comments.json"
    written_by: [board_comments_api]
    read_by: [board_review_surface]
    schema: "human board-review comments keyed by board/panel — distinct from the auto-reroll lineage sidecar"
    risk_level: medium

flags:
  - id: board_gated
    defined: recoil/pipeline/_lib/dispatch_payload.py::board_gated
    default: false
    gates_routes: [board_artifact_video_injection_route]
    summary: >
      PayloadContext.board_gated — when true AND a board_ref_path is present, the approved board
      image is appended to the video payload as the final board_1 ref (dispatch_payload.py:1265,2252).
    risk_level: medium
