# Website companion payload contract

TrueTraceShorts uses the website as the calm detail layer behind each short.

```text
Video = fast red flag
Website = what to do next, already-clicked help, checklist, tool relevance, SEO
```

## Source of truth

AutoShortsBot prepares a candidate JSON payload. The website generator converts it into:

- `src/content/redflags/<slug>.md`
- `public/redflags/thumbnails/<slug>-start.webp` when a video file is provided and no thumbnail is already set

The generator must be run explicitly. It must not publish, push to GitHub, or call platform APIs.

## Required payload fields

```json
{
  "id": "erf-022-fake-captcha",
  "slug": "fake-captcha",
  "title": "Fake CAPTCHA scam: why you should not click Allow",
  "shortTitle": "Fake CAPTCHA",
  "hook": "A CAPTCHA should prove you are human — not ask for notification access.",
  "category": "Browser & Permission Red Flags",
  "riskLevel": "high",
  "visibleScreen": "Fake CAPTCHA page with a browser notification permission popup.",
  "redFlag": "The page mixes a human-check with a notification permission request.",
  "whyItWorks": "It borrows a normal CAPTCHA pattern and moves the real request into the browser permission popup.",
  "saferMove": "Click Block, close the tab, and remove the site from notification settings if you already allowed it.",
  "ifAlreadyClicked": ["Close the tab.", "Do not allow notifications.", "Remove suspicious notification permissions."],
  "checklist": ["Does it ask for browser permission?", "Is the page pressuring you to click Allow?"],
  "checklistDetails": [{ "title": "Check the permission popup", "why": "A CAPTCHA does not need notification access.", "safer": "Choose Block and close the tab." }],
  "videoUrl": "https://www.youtube.com/shorts/...",
  "thumbnail": "/redflags/thumbnails/fake-captcha-start.webp",
  "screenImage": "/redflags/thumbnails/fake-captcha-start.webp",
  "screenImageAlt": "Fake CAPTCHA page asking for notification permission.",
  "visualBrief": "Direct phone/browser view of the suspicious permission request.",
  "related": ["fake-support-popup"],
  "toolRelevance": "Browser notification settings help only after the safer move.",
  "affiliateCategory": "browser-safety",
  "seoTitle": "Fake CAPTCHA scam: what to do before you click Allow",
  "metaDescription": "Learn why fake CAPTCHA pages ask for notification access and what to do before clicking Allow.",
  "socialTitle": "Fake CAPTCHA: don’t click Allow",
  "body": "Calm companion-page body copy.",
  "faq": [{ "question": "What should I do if I clicked Allow?", "answer": "Remove the site from browser notification settings and do not click alerts from it." }],
  "lastUpdated": "2026-06-05"
}
```

## Contract fields

- `id`: stable AutoShorts candidate id.
- `slug`: public website route slug.
- `title`, `shortTitle`, `hook`: human-facing guide title and short-card copy.
- `category`: visitor-visible category. Keep category names consistent with content entries.
- `riskLevel`: `low`, `medium`, or `high`.
- `visibleScreen`: what the viewer sees, in plain English.
- `redFlag`: the one suspicious pattern.
- `whyItWorks`: why this can feel normal.
- `saferMove`: the one safer move.
- `ifAlreadyClicked[]`: recovery-oriented steps used in detail page and FAQ fallback.
- `checklist[]`: short checklist fallback.
- `checklistDetails[]`: preferred printable checklist model: `title`, optional `why`, optional `safer`.
- `videoUrl`: YouTube/short URL after upload. This URL is allowed by the safety gate.
- `thumbnail`, `screenImage`, `screenImageAlt`, `visualBrief`: direct screen visual metadata.
- `related[]`: other guide slugs.
- `toolRelevance`: calm explanation of which tool category helps after the safe move.
- `affiliateCategory`: optional future monetization category; no automatic product recommendation.
- `seoTitle`, `metaDescription`, `socialTitle`: search/share copy.
- `body`: calm page body, not a transcript dump.
- `faq[]`: optional FAQ objects with `question` and `answer`; otherwise page fallback creates FAQ from existing fields.
- `lastUpdated`: ISO date.

## Safety rules

Candidate content must not contain:

- real scam URLs or domains
- real phone numbers
- card-like or bank/IBAN-like data
- real brand names/logos in scam examples
- raw comments, raw user messages, or private user text
- operational scam templates

The generator currently excludes `videoUrl` and `source` from example-text scanning, then blocks URL, domain, phone, card, bank-like, and common-brand patterns in the remaining candidate payload.

## Approval rule

AutoShortsBot may prepare/export this payload after an approved or upload-ready review package. It must not automatically push website changes to GitHub. Git push/deploy remains a separate human-approved action.