# Website companion handoff

`autoshorts.website_companion` bridges an approved/review-ready AutoShorts package into the TrueTraceShorts website pipeline.

The typed package/update-gate model and retention gates are documented in `docs/website_companion_package_and_retention_gates.md`.

It writes a website candidate JSON and can optionally invoke the website repo generator, which creates the Markdown companion page and extracts a real opening-frame visual asset from the MP4.

Visual handoff rule: each companion spec should include a `visualBrief` for the page image / first frame. The visual must show the scam screen directly — phone, laptop, invoice, login, popup, review section, payment request — not an abstract cybersecurity mood shot. If a separate AI/LLM image is generated, pass it as `screenImage`; otherwise the website generator uses the extracted opening frame.

## Example: ERF-018 Fake Reviews

```bash
python -m autoshorts.cli.export_website_companion \
  --review-package data/post_candidates/everyday-red-flags-fake-reviews/chatterbox_gianna_clone_premium_v1_readable_silent_2line_clean_ai/review_package_chatterbox.json \
  --companion-spec data/website_companion_specs/erf-018-fake-reviews.json \
  --website-root /home/agent/projects/TrueTraceShorts_WebSite \
  --run-generator \
  --force
```

## Side effects

The bridge performs no platform API calls and does not publish anything.

Allowed local side effects:

- write/update `data/candidates/<candidate-id>.json` in the website repo;
- run the website `npm run generate:companion` command when `--run-generator` is passed;
- write/update the website Markdown companion page and extracted opening-frame visual through that generator.

## Companion specs

Specs live under:

```text
data/website_companion_specs/
```

They intentionally contain the human-readable guide fields instead of trying to derive everything from a render package. This keeps web copy calm, useful, and safe instead of scraping meaning from a voiceover script.