# Santos Labs — TikTok Shop Operation: Session Handoff

**For:** Claude sessions on other machines (office) getting up to speed.
**Updated:** 2026-08-16 (evening). **Home base:** `c:\Users\Dell\brain-template` on the home PC (GOTCHA-architecture repo, NOT in git — code referenced below lives only on that machine).
**Live dashboard:** https://ops.santoslabs.ai (Cloudflare Worker `santoslabs-ops-dashboard`, account 777maint@gmail.com). Videos and product research are viewable there.

## The business

Owner is building a TikTok Shop affiliate operation using ~100% AI-generated videos.
Decisions made (with the owner, over one long working day):

1. **Niche #1: sleep/stress wellness.** Chosen over home/kitchen, pet, and toddler/educational after data showed 10x revenue pools and 25–30% commissions. Toddler/"mom voiceover" concept is benched as a future account #2.
2. **Lead product: Toplux Magnesium Complex** (TikTok Shop product id `1729448464509734958`): $532K/wk revenue at research time, 25% commission, $16 price, proven small-affiliate winners. Backup product: LullaBites Sleep Gummies.
3. **Strategy: faceless volume accounts first** (voiceover + b-roll, no persona), 3–5 posts/day once live; a consistent AI persona is a phase-2 asset.
4. Owner starts with zero followers — needs 1,000 for Shop affiliate links; pilot-program caps apply below 5K.

## Infrastructure (all working)

- **Kalodata Open API** — market research. Base `https://www.kalodata.com/openapi/v1`, auth header `X-API-Key`, full OpenAPI spec at `/openapi/v1/api-docs`. Endpoints: product/creator/video/shop/category rank+detail. Filters: `is_affiliate`, `commission_rate`, `unit_price_range`, `followers_range`, `is_ai_video`. Tool: `tools/research/kalodata_hunt.py` (subcommands: categories, hunt, credits). 7 niche hunts saved in `.tmp/kalodata_hunt/` and rendered on the dashboard.
- **Kling API** (video + image gen) — `https://api.klingai.com/v1`, Bearer auth. Models: `kling-v3` (text2video, image2video, images/generations). Funded with a video resource package. Gotchas learned: error 1102 = wrong-wallet/no balance (app credits ≠ API package), error 1303 = parallel-task cap (tools retry with backoff), durations only 5s/10s.
- **ElevenLabs** — voice. Upgraded plan: 600K chars/cycle. Voice: **Jessica** (`cgSgspJ2msm6clMCkdW9`), model `eleven_multilingual_v2`, single-take generation via `/with-timestamps` (word-level alignment drives video cutting). Earlier voices (Sarah) rejected as "announcer-like."
- **Gemini API** — billing active. `veo-3.1-*` models available (unused so far; option for hero hook shots) and `gemini-2.5-flash-image` (Nano Banana) used for product-scene stills from the real listing photo.
- **Cloudflare** — wrangler OAuth on the home machine (no DNS-edit scope; Workers custom domains auto-provision DNS, which is how ops.santoslabs.ai exists — same pattern as the owner's other dashboards). Dashboard rebuild: `python tools/dashboard/build_dashboard.py` then `npx wrangler deploy --config tools/dashboard/wrangler.toml`.
- **ffmpeg 9.0** installed (winget Gyan.FFmpeg) — assembly engine.

## The video factory (`tools/video_factory/`)

Pipeline: `generate_script.py` → `generate_voice.py` → `generate_broll.py` + `generate_reveal.py` → `assemble_video.py`; `batch_daily.py` chains it. Config = `args/video_factory.yaml` (variants defined as playbook beats). Everything cached (clips by prompt hash, voice by settings+text hash) so re-runs are near-free.

Key architecture points:
- **Videos follow a researched 6-beat structure** (hook → tension×3 → reveal at 40% → soft CTA → proof×2 → CTA+loop). Full spec: `context/tiktok_video_playbook.md` — the distilled output of a 12-agent research workflow (232 sources) on scroll-stopping structure. THE reference for all video work.
- **Voice-first cutting:** VO is generated as ONE continuous take with char-level timestamps; video segments are cut to the voice's line boundaries; captions are word-accurate karaoke chunks with yellow keyword pops.
- **Real-product reveal:** Kalodata gives the real listing photo → Nano Banana generates a 9:16 lifestyle still preserving the real label → Kling image2video animates it. Solves "AI mangles labels."
- Craft layer: punch zooms on reveal/price beats, film grain, hook text card on frame 1, −14 LUFS master, loop-to-hook ending (replay signal).

## Current state (as of this handoff)

- **`3am_v3.mp4` (33.5s)** is on the dashboard — first full playbook-spec video with the single-take Jessica voice. Owner is evaluating; earlier cuts scored 3/10 (v1) with steady improvements since. Voice iterations so far: turbo Sarah (robotic) → multilingual Sarah (announcer) → Jessica single-take (current).
- ~$10 total spent on generation across all iterations.
- Owner interaction style: fast, decisive, hands keys/payments over as needed, expects autonomous execution and honest quality assessments.

## Open items / next steps

1. Owner verdict on the Jessica single-take voice → if pass, write 4 more hook variants (data-diary, contrarian, before/after tease, identity-callout archetypes from the playbook) = day-one posting slate (~$6 generation).
2. TikTok account creation + posting protocol (bottom of `args/video_factory.yaml`): product tag, catalog-matching caption, 2+2 hashtags, AIGC label ON, pinned comment within 60s, post 7–10 PM, never delete-and-repost.
3. Real phone footage of the physical bottle ($16 order) still the top conversion upgrade when it arrives → drop clips in `.tmp/video_factory/product_shots/`.
4. Runtime is at the top of the 21–34s band; if completion data says trim, tighten the script (not audio manipulation).
5. Consider Veo 3.1 for hook shots (billing now active) — hybrid Veo-hook/Kling-beats.

## Constraints the office session must know

- The brain-template repo is local to the home PC only (not in git). From the office you can read this brief and the dashboard, but not the code. If code access is needed, ask the owner to push the repo to a private remote.
- API keys live in `.env` on the home machine and are NOT in this document. The office session needs the owner to re-provide keys for any direct API work.
- All memory/diary/decision logs (BIMRI) are in the home repo's SQLite brain. Key decision IDs: 64–71 cover this operation.
- Supplement compliance rules are strict (see playbook): structure/function language only, no disease names, time-qualified personal results, AIGC label always on.