# Dashboard one-button review-package bridge

Use this when extending the AutoShorts / TrueTraceShorts Dashboard from concept-gated production planning into a working review/upload/website control-plane flow.

## Durable pattern

The Dashboard may expose a **Generate review package** button, but only after the item is `concept_approved`.

Allowed sequence:

```text
Production Queue item
→ lock_next / approved_next
→ concept-proposed
→ explicit APPROVE_PRODUCTION / approve-generation
→ generate-review-package
→ prepared package import
→ ready_for_review / in_review
→ YouTube private-upload request / existing Jarvis uploader
→ Website companion payload / QA / commit prep
```

Hard blocker:

- `locked_next` or `concept_proposed` is not enough to render/package.
- `mark-started` and `generate-review-package` must return `409` until the concept is approved.
- Legacy “send to production” affordances may propose a concept, never bypass approval.

## Bridge implementation shape

Add a narrow agent endpoint, for example:

```http
POST /api/agent/production/{item_id}/generate-review-package
```

The endpoint should:

1. verify `ProductionQueueItem.status == concept_approved`;
2. call the existing lifecycle boundary (`mark_started`);
3. create a prepared package under `storage/incoming/<expected_package_id>/`;
4. write at minimum `video.mp4` and `manifest.json`;
5. include `queue_item_id`, package ID, script/hook, suggested YouTube/TikTok metadata, disclosure, and quality payload in the manifest;
6. run the real prepared-package importer/scan;
7. attach the exact imported `video_asset_id` by matching the import log folder/package ID, not “last imported video”;
8. call `mark-ready-for-review` only after import and quality gate pass;
9. return package/video IDs and next actions, without triggering upload or website push.

## Workflow-preview vs final renderer

A low-cost FFmpeg/Pillow preview package is acceptable only for internal control-plane tests and automated regression checks. For this user's creator approval flow, do not generate or send provisional/placeholder videos; approval should be based on a text/script concept package with hook rationale, storyboard beats, visual hook plan, Director plan, and social metadata. A preview video must not be used as the normal approval artifact and must not be represented as a final social Short.

For final TrueTraceShorts content, replace the preview generator behind the same endpoint with the proper Director-rendered executor:

- premium AI keyframes/styleframes;
- no PowerPoint/mockup-looking visual layer;
- Gianna/premium voice where available;
- forced/word-aligned readable captions;
- Director QA/contact frames;
- hash-bound review package.

The Dashboard button should remain the same; only the executor behind it changes.

## Quality payload gotcha

Prepared-package imports for Dashboard production items may reject or downgrade packages if `quality.overall != passed`. Even mechanical workflow preview packages need explicit quality fields when they are intended to exercise the active review flow:

```json
{
  "quality": {
    "visual_gate": "passed",
    "voice_gate": "passed",
    "hook_gate": "passed",
    "metadata_gate": "passed",
    "safety_gate": "passed",
    "package_integrity_gate": "passed",
    "overall": "passed",
    "checks": {
      "premium_ai_styleframes_used": true,
      "styleframes_text_free": true,
      "no_large_top_title": true,
      "no_unnecessary_lower_third_dim": true,
      "no_powerpoint_layout": true,
      "renderer_owned_text_listed": true
    }
  },
  "quality_report": {
    "overall": "passed",
    "mode": "workflow_preview",
    "block_public_posting_until_final_director_render": true
  }
}
```

For a real final package, these fields must be backed by real QA artifacts rather than asserted by the control-plane preview.

## End-to-end regression test

Add a test that exercises the full safe chain without calling the real provider:

```text
create locked queue item
→ concept-proposed returns APPROVE_PRODUCTION <id>
→ generate-review-package is blocked before approval
→ approve-generation
→ generate-review-package imports video and sets queue item in_review
→ read YouTube draft
→ prepare private upload snapshot
→ save-and-approve UploadRequest
→ execute existing Jarvis uploader in dry_run
→ prepare Website Companion payload
→ assert videoUrl is null and website_link_allowed is false for private upload IDs
```

This test proves the Dashboard can run from idea to private-upload/website-handoff while preserving approval gates and avoiding private YouTube link leakage.

## Pitfalls

- Do not create a “one button does everything including upload/site push” path. Package generation, private upload, and website update remain separate approval gates.
- Do not leak private YouTube IDs to public website payloads: `website_link_allowed=false` should produce `videoUrl=null` while retaining internal `youtube_video_id`/`video_url_internal` for later handoff.
- Do not leave fabricated or dry-run YouTube IDs as if they were real public posts. Use dry-run status/audits and clear wording.
- Do not claim the final premium video renderer is complete just because the review-package bridge works. The bridge validates the control plane; the final Director executor is a separate integration.