# AutoShorts → TrueTraceShorts website companion handoff

Use this when connecting a completed/review-ready AutoShorts/TrueTraceShorts review package to the static Astro website.

## AutoShorts bridge

AutoShortsBot contains:

```bash
python -m autoshorts.cli.export_website_companion \
  --review-package <post_candidate_version>/review_package_chatterbox.json \
  --companion-spec data/website_companion_specs/<candidate-id>.json \
  --website-root /home/agent/projects/TrueTraceShorts_WebSite \
  --run-generator \
  --force
```

The bridge writes a website candidate JSON and optionally invokes the website generator.

Visual metadata rule: every companion spec should include `visualBrief` and, when available, `screenImage` / `screenImageAlt`. The visual must show the suspicious screen directly (phone/laptop/invoice/login/popup/review/payment screen) rather than a generic cyber graphic. If no separate LLM/AI screen image exists, the website generator uses the extracted opening frame from the MP4 as both `thumbnail` and `screenImage`. Avoid labels like `Start frame` in the UI; use visitor language such as `Example screen` or no badge at all.

For ERF-018 specifically, the render script also exposes a controlled handoff flag so existing review packages can be exported without rerendering:

```bash
python scripts/render_erf018_fake_reviews.py \
  --website-companion-only \
  --run-website-generator \
  --force-website-companion
```

Use `--prepare-website-companion` after a fresh render when you want the render run itself to prepare the website candidate; add `--run-website-generator` only when the static site should actually be updated.

## Website generator called by the bridge

```bash
npm run generate:companion -- \
  --candidate data/candidates/<candidate-id>.json \
  --video <review mp4 path> \
  --force
```

Outputs:

```text
src/content/redflags/<slug>.md
public/redflags/thumbnails/<slug>-start.webp
```

## Why companion specs exist

Do not derive all website copy blindly from a voiceover/review package. The companion spec should contain calm, visitor-first guide fields:

- `visibleScreen`
- `redFlag`
- `whyItWorks`
- `saferMove`
- `ifAlreadyClicked[]`
- `checklist[]`
- SEO fields

This keeps the website useful for search/shared/direct visitors, not just a transcript of the short.

## Verification

1. Run AutoShorts bridge.
2. Run AutoShorts test:

```bash
python -m pytest tests/test_website_companion.py
```

3. In website repo:

```bash
npm run build
for path in / /redflags/ /redflags/<slug>/; do curl -s -o /dev/null -w "%{http_code} ${path}\n" "http://127.0.0.1:4321$path"; done
```

4. Browser-QA the generated companion page.

## Pitfall

If the AutoShorts repo remote uses HTTPS and no GitHub credentials are available, local commit may succeed but `git push origin strategy-refactor-v2` can fail with `could not read Username`. Report this honestly and leave the local commit hash.