TRR BACKEND: Production smoke run playbook for pipeline CLI

[therealityreport]

Goal: Provide a repeatable, low-risk "operator runbook" for running the pipeline in prod/staging.

TODO

• Add docs/runbooks/pipeline_smoke_run.md (or similar)
• Document prerequisites:
  • required env vars (Supabase, AWS/S3 bucket, TMDb creds)
  • role/permissions needed (service_role)
• Document safe smoke commands:
  • --dry-run mode — clarify whether it still writes pipeline.* tracking rows (it should), only skipping domain mutations
  • --skip-s3 mode — critical: document that this breaks resume/skip for Stage 1 because Stage 1 hydration depends on manifests as the source of truth
  • sample run targeting a single show by --tmdb-id / --show-id
• Document resume + manifest interaction:
  • If you run with --skip-s3, you cannot safely resume and skip Stage 1 later
  • Recommendation: staging can use --skip-s3; production runs should not if you want resumability/audit trail
• Document "what success looks like":
  • expected pipeline rows in pipeline.runs + pipeline.run_stages
  • SQL checklist:

    SELECT * FROM pipeline.runs ORDER BY created_at DESC LIMIT 5;
    SELECT * FROM pipeline.run_stages WHERE run_id = '<id>' ORDER BY stage_order;

  • how to verify S3 manifest exists (when not --skip-s3):

    aws s3 ls s3://$AWS_S3_BUCKET/pipeline_runs/<run_id>/01_collect/manifest.json

• Failure handling checklist:
  • how to resume (--resume) and when to use --force
  • common failure points (TMDb rate limits, missing AWS creds, etc.)

Acceptance

• New contributor/operator can follow the doc end-to-end and verify a run without guessing
• Operator can verify S3 manifest exists (when not --skip-s3)