# Website companion package and retention gates

This document records the integration contract between AutoShortsBot and the TrueTraceShorts website.

## Current branch status

Productive AutoShortsBot code lives on `strategy-refactor-v2`. `origin/main` is intentionally minimal at the moment and only contains a README.

## WebsiteCompanionPackage

AutoShortsBot now exposes a typed `WebsiteCompanionPackage` in:

```text
autoshorts/website_companion.py
```

It contains:

- `candidate_id`
- `version`
- `page_slug`
- `website_path`
- `page_payload_json`
- `video_url`
- `thumbnail_path`
- `redflag_markdown_path`
- `safety_summary`
- `seo_summary`
- `tool_relevance`
- `update_allowed=false`
- `video_sha256`
- `posting_pack_sha256`
- `website_payload_sha256`
- `review_package_path`
- `generator_command`
- `notes`

`update_allowed` remains false by design until a separate human approval/update step exists.

## WebsiteCompanionUpdateGate

The gate checks that a website update is bound to stable artifacts and safe payload content:

- candidate id exists
- version exists
- video hash exists
- posting pack hash exists
- website payload hash exists
- no raw comment text
- no external user text
- safety gate valid
- no real scam phone/domain/bank/card/brand data in website copy

The gate does not push to GitHub and does not publish anything.

## CLI commands

Read-only inspection:

```bash
python -m autoshorts.cli.website_companion_prepare <candidate_id>
```

Write website candidate JSON only, no markdown generation and no Git push:

```bash
python -m autoshorts.cli.website_companion_dry_run <candidate_id>
```

Export a package artifact:

```bash
python -m autoshorts.cli.website_companion_export <candidate_id> --output data/website_companion_packages/<candidate_id>.json
```

Optionally run the website generator during export:

```bash
python -m autoshorts.cli.website_companion_export <candidate_id> \
  --output data/website_companion_packages/<candidate_id>.json \
  --run-generator \
  --force
```

No command performs an automatic GitHub push.

## Video retention gates

`autoshorts.retention.evaluate_red_flag_video_gates()` adds explicit TrueTraceShorts gates:

1. One-Second Recognition Gate
   - first frame must identify the screen, danger, and stakes.
2. Open Loop Gate
   - first 2 seconds need a question/tension.
3. One Red Flag Gate
   - exactly one main red flag.
4. One Safer Move Gate
   - exactly one clear safer move.
5. Website Companion Value Gate
   - video must map to a guide question such as:
     - What do I do if I already clicked?
     - What do I check before acting?
     - What should I avoid?

## Required video structure

Scam Red Flag videos:

```text
0-2s: visible screen + hook
2-8s: why it feels normal
8-16s: the one red flag
16-30s: safer move
30-45s: memorable rule + website/help CTA
```

Recovery topics may run 45-75s when the viewer needs step-by-step help.

## CTA policy

Use the CTA that matches the video:

- Already clicked? Open the guide.
- Full checklist in the guide.
- Save this before you click.
- Send this to someone who clicks delivery links.
- Follow for one red flag before you click.

Platform copy:

- YouTube description: `Full checklist: /redflags/<slug>`
- TikTok/Instagram: `Full checklist in bio / guide link`
- Longform later: embed guide link in description