# TrueTraceShorts Website MVP v0.1

TrueTraceShorts is the content hub behind the short-form channel:

> One screen. One red flag. One safer move.

The site gives everyday internet users simple red-flag guides, safety checklists, and calm next steps before they click, pay, scan, or log in.

## Stack

- Astro
- TypeScript
- Static output
- Astro Content Collections for red-flag companion pages
- Plain CSS with design tokens
- Optimized TrueTraceShorts logo/banner assets from Google Drive
- No backend, database, login, comments, or forms in MVP

## Local development

```bash
npm install
npm run dev
```

Open the local URL printed by Astro, usually `http://localhost:4321`.

## Build

```bash
npm run build
npm run preview
```

The static output is written to `dist/`.

## Production QA loop

Before pushing website changes or after adding a companion page:

```bash
npm run sync:youtube-links -- --dry-run
npm run sync:youtube-links -- --apply
npm run qa:production
```

`qa:production` builds the site, checks generated routes, internal links/assets, sitemap/robots, JSON-LD, and common placeholder leaks. For live-domain smoke checks after deploy:

```bash
npm run qa:live
```

See `docs/production-qa-runbook.md` for the full checklist.

## Companion-page generator

`v0.2` includes a local generator for approved AutoShorts/TrueTraceShorts candidates. It creates a Markdown companion page and, when given a rendered MP4, extracts the real 9:16 opening frame as a WebP visual asset.

Visual asset rule: the first frame or companion image must show the actual scam screen clearly — phone, laptop, invoice, login, popup, review section, payment request, etc. Avoid generic mood graphics. If a separate AI/LLM image is produced for the page, store it as `screenImage` and keep critical fake UI text manually reviewed / renderer-owned.

Dry run with the included sample candidate:

```bash
npm run generate:companion -- --candidate data/sample-video-candidate.json
```

With a rendered video:

```bash
npm run generate:companion -- \
  --candidate data/sample-video-candidate.json \
  --video /absolute/path/to/render.mp4
```

Output paths:

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

The generator refuses to overwrite existing pages unless `--force` is passed. It also blocks obvious real URLs, domains, phone numbers, card numbers, bank-like identifiers, and common real-brand names in candidate example text so examples stay generic. `videoUrl` is allowed separately because it is the legitimate channel link.

The formal AutoShortsBot → Website payload contract is documented in `docs/website-companion-contract.md`.

## Content structure

Red-flag companion pages live in:

```text
src/content/redflags/
```

Each file contains frontmatter fields for automation-ready video companion pages:

- `id`
- `slug`
- `title`
- `shortTitle`
- `hook`
- `category`
- `riskLevel`
- `visibleScreen`
- `redFlag`
- `whyItWorks`
- `saferMove`
- `ifAlreadyClicked`
- `checklist`
- `checklistDetails`
- `faq`
- `videoUrl`
- `thumbnail`
- `screenImage`
- `screenImageAlt`
- `visualBrief`
- `related`
- `toolRelevance`
- `affiliateCategory`
- `lastUpdated`

Initial entries:

- `delivery-sms-trap`
- `fake-support-popup`
- `fake-invoice-payment-route`

## Pages

- `/` — home and channel positioning
- `/already-clicked/` — immediate recovery triage after a click, password entry, payment, download, fake support call, or family incident
- `/safety/` — start-here safety guide
- `/redflags/` — red-flag library
- `/redflags/delivery-sms-trap/` — full companion page example
- `/tools/` — trust-first tool categories and recommendation policy
- `/about/` — channel purpose
- `/privacy/` — MVP privacy policy
- `/terms/` — simple terms and disclaimer

## Safety rules

- No real scam phone numbers, domains, bank details, or QR codes in examples.
- No panic language.
- No guarantees.
- No real submit-a-scam form in MVP.
- Tool recommendations must never replace the safe action.

## Current automation

`v0.2` now includes a local AutoShortsBot companion-page generator. It turns an approved candidate JSON plus optional MP4 render into a Markdown red-flag page and real WebP start-frame thumbnail.

Current polish notes:

- Homepage now emphasizes the video-to-guide flow.
- Red-flag detail pages include companion-page action anchors: watch, checklist, already-clicked steps, and related red flags.
- Library categories show guide counts and safe coming-soon states.