@generativereality/content-studio 0.0.0-stage → 0.1.0

package/skills/content-studio/references/copy.md

@@ -0,0 +1,201 @@
+# Copy and story: what to say first, and how it holds attention
+
+This file covers how words and stories are built for any piece people read, watch or hear. Read
+`voice.md` beside it: this file decides what to say, and that one decides how the sentences sound.
+
+Sources: *Made to Stick* (Heath & Heath), *Breakthrough Advertising* (Schwartz), Ogilvy, Copyhackers
+(Wiebe), *Everybody Writes* (Handley), *Building a StoryBrand* (Miller), *$100M Offers* and *$100M
+Leads* (Hormozi), *The Wizard of Ads* (Williams), *Influence* (Cialdini), and about 120 advice videos
+from working creators and ad buyers, transcribed and read frame by frame (Nov 2026). The creators'
+numbers are their own, often from people selling courses: use them as a creator's benchmark, never as a
+fact in a claim. Where a book and a video disagree on tone, follow the book.
+
+## The failure this file exists to prevent
+
+A piece built from what the writer can cite instead of what the reader cares about: the product
+introduced, then counts, then features. Every line is true and a stranger stops after the first one.
+That is the *curse of knowledge*: once you know a thing, you can't see it as someone who doesn't.
+**Evidence backs the copy. It isn't the copy.**
+
+## 1. The one idea
+
+Before a line of copy, write the core as one sentence that still holds when everything else is cut.
+Then make it stick:
+
+- **Simple:** one core, short and deep. Not a list of everything.
+- **Unexpected:** break the reader's pattern, open a gap in what they know, then fill it. The surprise
+  serves the core or it is a gimmick.
+- **Concrete:** something a person does or sees. *"It found the three people who already recommend you"*,
+  not *"relationship intelligence"*.
+- **Credible:** proof the reader can test: a demo, a free try, a real output.
+- **Emotional:** one person beats a statistic. In the book's study, a letter about one named child
+  raised more than twice what a letter of statistics did, and adding the statistics lowered it.
+- **A story:** a short sequence of what happened to someone, which the reader can run in their head.
+
+Write three to five angles for the idea, pick the one a stranger in that channel would stop for, and
+say in one line why it beat the others.
+
+## 2. Study what already works {#study}
+
+In the niche and the channel, find the pieces that did **3 to 5 times** better than their own
+author's normal (by views, saves or upvotes against that author's median). Copy their hook **form**
+and structure, never their content. Then fill the form with what only this person can say: *what have
+they earned the right to explain?* Keep a bank of the audience's problems in their exact words, from
+comments, threads and reviews of the alternatives. Their phrases make the best headlines. Never
+invent a channel, a link or a number while studying. Write *"not verified"*.
+
+## 3. Hooks
+
+**The first one or two sentences (or seconds) decide everything, and clarity beats cleverness.** Say
+what this is about and why it matters to this reader, in short plain words. A great hook isn't
+catchy; it is a trap the reader walks into because it is about them.
+
+Formulas, one per piece:
+
+- **Context, pull, turn:** line one says exactly what this is; then a pull (something hidden that is
+  happening to them, a contradiction, or proof shown); then the opposite of what they expect.
+- **Context, challenge, transition:** *"…so today is day one of… But let me start from the
+  beginning."* It opens a series.
+- **Connect to what they already want:** *"a dinner that gets you a third date"*, not *"knife skills"*.
+- **Audience qualifier:** *"If you sell anything, you need to hear this."*
+- **I built X because Y**, and **the problem, then what I did about it**. These are the commonest
+  shape of top maker posts.
+- **Confession:** a true, specific thing that went wrong.
+- **Receipts first:** a real, small, verifiable number in the first line or first second. Only true
+  ones.
+- **Newsjack:** this week's change, ruling or announcement.
+- **Attention triggers:** an extreme size or speed, a specific large number, a person the reader
+  wants to become, a big result from no experience, a line going up and to the right.
+
+**Visual hooks** (the first one or two seconds of a video are a picture): a slow reveal of the result,
+before and after, a list that unblurs item by item, a tier board, a split screen, a prop, a walk-in, a
+pinned title bar with the claim, a counter that climbs. A kept imperfection (a dog walking through)
+works as a pattern interrupt. The first visual must match the first words.
+
+**Text hooks:** LinkedIn rewards a hook that gets to its purpose at once; X rewards a plain contrarian
+line or a prediction. *"Press release energy"* fails everywhere. Never open on the product's name for a
+reader who hasn't heard of it.
+
+## 4. Scripts and structure
+
+- **Stories are loops:** stakes, an open question, an unexpected turn, a re-hook, then again. Answering
+  one question opens the next. Every loop closes; pay the promise before 80% of the runtime; never
+  summarise at the end.
+- **Name the framework early.** A video that took 22 seconds to say what it was about flopped.
+- **Entertain the many, teach the interested, sell to the committed.** If it looks like an ad, people
+  scroll.
+- **Tell the story while doing something visually interesting** (cooking, walking, building).
+- **Show, don't list.** Lists with no opinion stopped working. Showing the expertise (a case study, a
+  worked hypothetical, a live build, the product doing the thing) is where the room is.
+- **Structures that work:** man in a hole (fine, worse, better); big goal, challenge, breakthrough;
+  before, bridge, after. Use one per piece, filled with the customer's words and invisible to the reader.
+- **For a 30 to 60 s ad or a song-led piece:** shock and an open loop; personal stakes; failed fixes and
+  a low point; a guide and a new explanation; doubt and a demonstration; progress you can follow; the
+  payoff and who they are now; the reveal; one invitation that calls back to the start. The test is
+  whether a first-time viewer could retell what changed.
+- **Carousels and list posts:** each item carries its proof and an opinion; a list that overflows the
+  screen gets saved.
+- **Long video:** a counterintuitive opening, a promise of value, then deliver it at once.
+- **Newsletters:** frameworks and breakdowns, no filler. It is the highest-intent channel there is.
+
+## 5. Copy rules
+
+- **The headline does most of the work.** It promises something the reader wants, and is specific.
+- **Feel first, then ask.** Let the reader see their own situation in concrete words before any ask.
+- **Specifics over adjectives:** swap every adjective for a fact, a named situation or a visible
+  result. A slogan and vague adjectives insult the reader.
+- **The reader's own words** (§2) write the headline and set the order.
+- **Write to one person.** Draft fast, then cut everything that is there for the writer.
+- **The reader is the hero; the product or person is the guide** with a plan and one next step.
+- **Value is outcome × likelihood ÷ (time × effort).** Showing how soon the first result comes and how
+  little it asks usually beats a bigger promise, which lowers belief with sceptical readers.
+- **Proof, honestly:** social proof works best from people like the reader, and only when true and
+  specific (named only with consent). Give first: the piece itself should be useful. Use scarcity and
+  authority only when they are real.
+- **Plan what the reader sees with what they read.** For an article, page, guide or launch, plan the
+  picture in the brief (the real screen, a diagram, the chart of the number that matters, a before and
+  after) and write around it. One visual per idea it explains, with a caption saying what to notice.
+- **A landing page is one promise and one button,** and the visitor feels the win in under a minute.
+  For a launch that has to explain *why*: the insight (what changed, or what the reader gets wrong), the
+  alternatives and their cost, the better way, then the product, its proof, and one ask. Most pages
+  are one sentence too long.
+- **The call to action** says what to do, why, when, how easy it is and what happens next. It can be
+  the lesson itself. Never ask for upvotes, shares or support, and always say in the first line that
+  you made the thing.
+
+## 6. What people share
+
+One specific relationship, one small concrete moment, a reveal or a line that lands at the end, and an
+implicit *"send this to…"*. Content made to be sent to one person is what gets passed on. People trust
+"people like me" over the best success story, and a moment they can picture over a number (*"close the
+laptop at five"*, not *"save five hours a week"*). Raw beats produced: smooth AI transitions and
+sharpening push a piece toward looking like an ad. Less production often performs better:
+platform-native, phone-shot, talking video beats a polished studio piece.
+
+## 7. Formats and series
+
+- **A series beats one-offs.** A named recurring format (*"day 1 of…"*, *"one teardown a week"*) makes
+  the audience a participant. A **default piece** that is easy to make every week keeps the cadence.
+- **Kinds to rotate:** teaching, story, authority (the "if I started again today" case study), series,
+  and doubling down on a hit by turning it into a format.
+- **Pieces every profile needs:** the origin story, how it works, how it was made, a day in the life,
+  the before and after (the maker's and a customer's), the mission, a hypothetical.
+- **Formats that work as ads and as posts:** prototype to product, blind test, stress test, notes-app
+  screenshot, "don't buy this if…", teardown, reply to a real comment, day 1 to day 30, price
+  breakdown, screen recording, founder demo, raw review.
+- **One core piece, cut for each channel** (post, short clip, carousel, newsletter section, a reply in
+  the thread where someone asked exactly that). Use one home platform for the original work and treat
+  the rest as distribution, in the same voice.
+- **Own a category, a word and a visual,** and repeat them past the point of boredom.
+- **Old drafts and archived posts are material.** Refresh and republish what still holds before
+  inventing a new topic, and mine the person's voice notes for ideas (a memo saying "idea for a post"
+  is a brief waiting to be written).
+
+## 8. Ads
+
+Distinct creative is the targeting now. Ad delivery systems reward distinct concepts and count
+near-duplicates as one. Test many hooks against a few bodies and a few calls to action, change one
+variable per test, and write a hypothesis for each test. A lead magnet solves one narrow problem
+completely, in a way that reveals the next problem the offer solves.
+
+## 9. The check {#check}
+
+Read the piece cold, as the brief's reader meeting it in that channel. Each must hold:
+
+1. **Hook:** would they stop for the first line or first second? Does it open on their situation, not
+   the product's name or the writer's numbers?
+2. **Reader:** is it about them, at their stage of awareness? Internal numbers dressed up as the story
+   always fail.
+3. **Specificity:** a concrete scene, example or number that makes the point; where the form carries
+   pictures, the planned one is there.
+4. **One idea:** could they repeat it to a friend in a sentence?
+5. **Voice:** a person talking, none of the tells (`voice.md`).
+6. **Channel fit:** the form, length and rules of that place (`channels.md`), and nothing a moderator
+   would remove.
+
+The floor under all six: every claim has its source; nothing is invented; nothing promised that isn't
+true. A self-score does not predict quality. Pieces that scored well on every point have been judged
+bad on sight. The person's reaction and the result are what count, so treat this as a gate against
+obvious faults, not as proof the piece is good.
+
+## 10. After it goes out {#after} {#ceilings}
+
+- **Before posting, predict** the piece's result as a multiple of the person's normal at 6, 24 and 72
+  hours, and compare afterwards.
+- **Read start, stay, signal:** nobody stopped means the hook failed; they started and left means the
+  payoff came too late; they watched and did nothing means it entertained but wasn't memorable. Write
+  three notes per piece: why they started, where they left, which line got a reaction.
+- **View ceilings** (one creator's diagnostic): stuck under 1,000 views, the hook is unclear (fix
+  subject, stakes, simple, short); under 10,000, the topic doesn't touch a pain or desire, or the first
+  visual doesn't match the first words; under 100,000, the angle is obvious. Past that it takes
+  controversy, which is usually wrong for a brand. A business can be built without ever passing 100,000.
+- **Benchmarks** (creators', unverified): Instagram share rate around 4% is excellent; watch-through
+  above 50% (60% on 15 s); X reply rate 1 to 3%; LinkedIn engagement 4%+; newsletter opens 30% normal,
+  40% great; YouTube click-through 2 to 10% for most channels (YouTube's own range).
+- Write the winning **formula** into the house style, not the piece.
+
+## Never
+
+- Invent a number, quote, testimonial, user or result, or present a hypothetical as a real case.
+- Borrow the *comment a keyword and I'll DM you* call to action at scale. Platforms ban automated DMs.
+- Use a revenue screenshot, a "study shows" number without its caveats, or anyone's content as your own.

package/skills/content-studio/references/costs-and-licences.md

@@ -0,0 +1,75 @@
+# Costs, licences, disk, local or hosted, Windows
+
+## Budget and the spend log
+
+- Work inside a budget the person set, in money and time. When you reach it, stop and say so. Running
+  past it "because it was nearly done" is still over budget.
+- Log every paid call (`scripts/spend.mjs add …`) with the model, settings, cost, wall time and output
+  file, and report the total per piece (`scripts/spend.mjs total`). Show the person what each sample
+  cost and how long it took. Some tool skills say never to tell the person prices: this skill
+  overrides that.
+- Typical spends (Nov 2026): a full round of image, video and voice experiments for one area cost $1 to $2.
+  A 30 s product clip with three generated shots cost $1 to $8 depending on the model. Generation was
+  about $20 against about $300 of agent tokens in one production, so the agent's own time is usually the
+  bigger cost.
+- **Budget attempts, not length.** A discarded take costs the same as a kept one; the keep rate in one
+  production was 3 of 7.
+- Video per second of output (Replicate, read 25 Aug 2026, 1080p unless noted; re-read before boarding):
+  Seedance 1.5 Pro $0.026 (720p, silent), Kling 2.5 Turbo Pro $0.07, Veo 3.1 lite $0.08 ($0.05 at
+  720p), Runway Gen-4.5 $0.12, Veo 3.1 fast $0.15 ($0.10 at 720p), Kling v3 pro $0.224 ($0.336 with
+  audio), Seedance 2.5 $0.23 (720p), Veo 3.1 $0.40. **The spread for the same shot is about 15×, and
+  that spread is the budget.**
+- Local electricity is small (about €0.0003 an image, €0.01 a local video clip at €0.20/kWh); what
+  local costs is wall time and disk.
+- Never create an account, start a trial, accept a licence or buy anything on the person's behalf.
+
+## Local or hosted
+
+Local and free by default **where the quality is as good**. Otherwise use the best tool within the
+budget. In Nov 2026 on an Apple Silicon Mac with 32 GB or more, these run well locally: FLUX 3 Klein and
+Z-Image (images), ACE-Step (music), Qwen3-TTS and Kokoro (voice), and whisper (transcription). Local
+video is impractical (10 minutes to over an hour a clip, 70+ GB weights). Hosted wins on video, on
+Nordic voices and on images that must hold a design or a cast.
+
+- **macOS kills long GPU jobs while someone uses the screen**
+  (`kIOGPUCommandBufferCallbackErrorImpactingInteractivity`). Run long local generation at night, or
+  shrink the input.
+- Hugging Face downloads stall on xet transfer: `HF_HUB_DISABLE_XET=1 hf download … --max-workers 1`. If
+  the client deadlocks, delete the model's `.locks` and `*.incomplete` files and retry. One `--exclude`
+  per pattern. Download one model at a time.
+- mflux needs `pillow<13`.
+
+## Disk
+
+Check free space before any model download, and stay inside a cap the person agrees (models run from
+2 GB to 80 GB each). Install into the project's own folder (venvs, local `node_modules`), not
+system-wide. List what can be deleted when you finish. Keep generated media out of git unless the
+project says otherwise.
+
+## Licences: what may be used for what
+
+Read the licence on the **model card**, not the GitHub badge. A repository's code licence often
+differs from its weights' licence.
+
+| Class | Examples | Meaning |
+|---|---|---|
+| Apache-2.0, MIT, BSD | HyperFrames, Kokoro, Qwen3-TTS, Chatterbox, ACE-Step, Wan 2.2 weights, Real-ESRGAN, mflux, whisper, YuNet, Playwright, Z-Image Turbo | use, bundle, sell |
+| MPL-2.0 | Satori, resvg | bundle; publish only changes to those files |
+| Free under a revenue or size limit | FLUX 3 Klein (under US$5M), LTX-2.x (under US$10M ARR), Remotion (up to 3 employees), MiniMax Music 3 local (under US$20M, credit in the UI), Stable Audio (under US$1M) | fine while under it; plan a licence past it |
+| GPL, AGPL | Piper's engine, espeak-ng, ComfyUI, OpenMontage | fine as a separate program a person runs on their own content; bundling it makes the product GPL, and AGPL also covers a network service |
+| Non-commercial weights | OmniVoice, Voxtral, MusicGen, F5, XTTS, CodeFormer, Qwen-Image-2.1, FLUX.2 dev | private use only, never behind anything sold |
+| Free tiers | ElevenLabs free (attribution required), Apple system voices (personal use) | not for anything published for a business |
+| Regional | HunyuanVideo (licence excludes the EU, UK and South Korea) | not for companies there |
+
+The outputs of the major hosted models are usable commercially under each provider's terms. Some
+carry an invisible watermark (SynthID on Google's). Openly licensed photos, clips and music come with
+their licence from the Wikimedia Commons API (CC0, public domain, CC BY, CC BY-SA, attributing BY and
+BY-SA) or Openverse. **Record each asset's licence and source beside it.**
+
+## Windows
+
+HyperFrames, Remotion, Playwright, ffmpeg, Kokoro (ONNX), whisper.cpp and Real-ESRGAN run the same on
+Windows. MLX models (mflux, mlx-audio, mlx-whisper) are Apple-only. Local image and video models need an
+NVIDIA GPU there (ComfyUI or diffusers), so a Windows machine without one uses the hosted models.
+Replace Apple's Vision with an ONNX face detector plus OCR text density, and HEIC handling with libheif.
+On a smaller machine, make fewer variants and use a pre-made library of music beds.

package/skills/content-studio/references/generation.md

@@ -0,0 +1,192 @@
+# Generated images and video
+
+The models change monthly. **Read the live price and input schema before every batch.** Treat the
+names and numbers here as the shape of the answer, dated. Swapping the hosted model is the cheapest
+quality fix there is.
+
+## Calling a hosted model
+
+- **POST, then poll.** Never hold a request open (`Prefer: wait`) for anything long: a dropped
+  connection is paid for twice, and on Replicate the output of a dropped prediction can be purged.
+  Submit all jobs first, then poll them all, about every 10 s.
+- **Read the live schema** (`GET /v1/models/{owner}/{name}`) and grep it for every control you are
+  about to describe in words. A schema field such as `camera_fixed` works; the same request written as
+  prose in the prompt doesn't.
+- **Read the live price** from the model page and check its unit (per image, per second, per 1,000
+  images). Replicate's API exposes no price, but each model page embeds its billing table as JSON:
+  fetch the page to a file and parse the `"criteria"` / `"prices"` objects (read the file in a heredoc
+  script; `python3 -c "…"` lost its inner quotes to bash). **Check every parsed number against its
+  unit:** the same parser read one model correctly at $0.04 an image and another as "$3", which was
+  per 1,000. A price two orders of magnitude off its neighbour is the tell. Prices are tiered by
+  resolution and by audio on or off, so one number per model is wrong by construction, and a rate
+  carried in a doc was once half the real one when a shoot was planned on it.
+- **Spend is computed, not measured, on Replicate:** there is no billing endpoint, and the predictions
+  list 403s intermittently on paging, so a ledger built from it is silently partial. Compute from the
+  rate table and say so. OpenRouter returns the real cost per call in `usage.cost`.
+- **Log every call:** model, settings, seed, cost, wall time, output file (`scripts/spend.mjs`).
+- **Never overwrite a take.** A take that exists has usually been cut against, and re-shooting over it
+  pays twice and swaps the file the edit and the review point at (a queued job once landed a second take
+  on top of the one a scene was built from; the provider's copy of the first had not yet expired). Skip
+  outputs that exist; `--force` writes `<name>-2`. **A cache key must name everything the output depends
+  on:** cloned voice-over keyed on the line and not on the reference take kept the wrong voices.
+- **Retry a 429 after the server's `retry_after`** and keep looping: low-balance accounts are throttled
+  but still finish. Space batch calls a few seconds apart.
+- **No silent fallback to a second provider.** A fallback once returned JPEG bytes saved as `.png`;
+  a clean failure is better. Output may be a string or a one-item array, so handle both.
+- API traps: community models need `POST /v1/predictions` with a version id; the model endpoint returns
+  a bare 404 for them although `GET /v1/models/{owner}/{name}` returns 200. A GET without a
+  `User-Agent` can be refused with a 403 that reads like a bad token (POSTs pass, curl never sees it).
+  The predictions list omits `output`; fetch each prediction. Prediction ids are about 26 characters, and a
+  truncated id gives a 404 that looks like a vanished prediction.
+- Credentials come from wherever the person keeps them (a keychain entry, an environment variable).
+  Ask, never print them, and never paste them into files that get committed. When minting a token in a
+  browser, capture it by command substitution straight into the store, never by reading the page into
+  the transcript. On macOS a keychain read on a locked login keychain can hang on a prompt nobody can
+  answer ("In dark wake, no UI possible"): stop retrying, only a person at the machine fixes it.
+- **Hosts:** switching models saves money, switching hosts mostly doesn't (Veo 3.1 and Kling 2.5 cost the
+  same on Replicate as first-party, Aug 2026). Move hosts for a model one lacks (query the API, not the
+  collection page, which omitted models it serves), lower cold starts (fal.ai) for interactive work, or a
+  consumer plan whose included generations beat per-second billing, after checking its terms for
+  commercial use and visible watermarks.
+- **OpenRouter** (Oct 2026) serves image and video leaders Replicate lacked (MAI-Image, Muse, HeyGen
+  Video 1, MiniMax H3): `POST /api/v1/images` is synchronous (base64 in `data[0].b64_json`, references
+  as `input_references`), `POST /api/v1/videos` is async (poll, then download `/content`). List a host's
+  models with `GET /api/v1/models?output_modalities=image|video|audio`.
+
+## Images: what to reach for (as of Nov 2026)
+
+Image leaderboard (Artificial Analysis, read 24 to 26 Oct 2026): GPT Image 2.5 (~1220 Elo), Nano Banana
+2.1 (~1180), MAI-Image 2.6, Grok Imagine 2, Muse, FLUX 3 Image (~1120), Seedream 5 Pro, Qwen-Image 3 Pro.
+FLUX Kontext pro (~920, around 78th) and FLUX 1.1 pro (~870, around 90th) look dated: over-processed
+"AI portrait".
+
+| Need | Use | Price and time (Nov 2026) |
+|---|---|---|
+| Default hosted picture; text that must be right; one design across slides; a consistent cast | **Nano Banana 2.1** | $0.034 at 1K, $0.05 at 2K; 17 to 30 s (once 135 s under load) |
+| Cheapest | Muse Image ($0.01, 17 s); GPT Image 2.5 at medium quality via OpenRouter ($0.011 to $0.016, 15 to 27 s) | |
+| Designed, illustrated look | **Recraft v4** ($0.04, 11 s) | watch hands |
+| Restoration, faces changed least | Nano Banana Pro ($0.15 at 2K) | |
+| Nothing uploaded | **FLUX 3 Klein locally** (mflux on a Mac with 32 GB+, 2 to 4.5 min an image, 30 GB weights; free under US$5M revenue) | Mac only through MLX; Windows needs an NVIDIA GPU |
+| Most photographic local | Z-Image Turbo | ignores colour constraints |
+
+Faults to expect: Nano Banana tends toward an orange-glow "ad" look and over-even lighting, and once
+added a second parent unasked. Seedream ignored a colour instruction. Ideogram drew nonsense phone
+screens. MAI-Image refuses any scene with a child. Recognisable copyrighted characters were refused by
+GPT Image 2.5, Nano Banana 2.1, FLUX 3 Image and Seedream, and drawn by Qwen-Image 3 Pro and FLUX 1.1
+pro (Oct 2026); don't make them for anything published.
+
+For a transparent cutout (sprites, props), run a background-remover model on the finished image.
+Identity-preserving variations of one character (another outfit, another palette) come from an
+editing model given the base image and an edit instruction; plain text-to-image makes a new character
+each time.
+
+## Prompting what renders
+
+- **Models render the ordinary well and turn the extraordinary into cliché** ("humanoid robot",
+  "figure made of light"). Prompt the room, the light and the action, not the concept. Flat interiors,
+  one deadpan figure doing something mundane, two people at a table in available light and a period
+  video look (grain hides artefacts) all render reliably; scale effects and invented creatures don't.
+  Test a look with cheap stills before paying for video.
+- **A negative prompt can't enforce an absence.** Four "closed laptop" takes failed across two model
+  families. Remove the object, or describe physical facts instead of states.
+- **Props and wardrobe don't arrive reliably; posture and movement do.** Anything that must be seen
+  should be an action.
+- **Say the age** of any child in the scene, or the model will age them up.
+- **Ask for the real number.** An invented "six tabs" was really five, and five looked better (five
+  different things, so the beats differed, and a counted number can't be caught out). Find the real
+  figure, count or label before it reaches a frame; it is usually one search away.
+- **In video, screens and paper in shot come out as gibberish.** Prompt them illegible on purpose
+  (angled, defocused, turned away) and composite every readable word afterwards.
+- For backgrounds under text, end with *"No printed matter, no writing, no labels, no logos."*
+
+## Consistency across images and shots
+
+- **A cast sheet as the reference image, with the clothes named in the prompt.** Without named clothes,
+  local models copy the reference portraits' outfits. GPT Image 2.5, Nano Banana 2.1, FLUX 3 Image,
+  Seedream 5 Pro and Muse kept everyone recognisable in a bench of family scenes.
+- **Chain the style:** use the first accepted still as the style reference for the next ones.
+- **One room across shots is not a prompt problem, and no seed fixes it.** Four separate text-to-video
+  takes of "the identical room" gave four rooms, and the same seed with one clause changed gave two (a
+  seed reproduces one generation; it carries nothing between them). Generate several shots in one call
+  where the model supports it (Kling v3 `multi_prompt`, up to 6 shots; Seedance 2.5, 30 s in one call),
+  or chain: one still of the room, edits of that still that change only the light or time, each fed as
+  the clip's start image, and start plus last frame where two shots must join.
+- **Repair rather than re-roll:** models that take a `reference_video` as a base (Kling omni) edit a
+  clip you already paid for in plain language, so a take wrong in one object is a cheap edit, not a
+  reject.
+- **A locked-off composition holds** (one room stable over ten seconds). A static camera with no
+  recurring face is the cheapest reliable shot. Where the schema has `camera_fixed`, set it; the same
+  wish written in the prompt and negative prompt is a hope.
+- **One recurring face:** use the model's `reference_images` (counts differ by model). Decide this
+  before boarding, because it decides the model and the price.
+- An on-camera speaker commits you to a voice the video model can't reproduce: it re-rolls the voice on
+  every generation, and no seed or id fixes it. Generate the face once, then clone the voice from that
+  take (`audio.md`) only if it is a synthetic person, never a real one (`real-people.md`). Decide
+  whether anyone speaks on camera before boarding.
+
+## Video: what to reach for (as of Nov 2026)
+
+| Model | Price | Use, and what it does wrong |
+|---|---|---|
+| **Seedance 1.5 Pro** (image to video) | about $0.026/s silent, $0.052/s with audio at 720p; 5 s ≈ $0.13 at 720p, $0.30 at 1080p | the liveliest and best looking. **Invents things:** an extra person in a group, drips, sprouting leaves; cut to a new shot mid-clip despite `camera_fixed`. Never on anything that must stay true without an invention check |
+| **Kling 2.5 Turbo Pro** | about $0.07/s | faithful (kept the right number of people), native 1080p; slower |
+| Wan 2.2 i2v fast | about $0.11 a clip | **out for anything shown: choppy, as if 10 to 15 fps** |
+| Text to video leaders (read 26 Oct) | Wan 3 $0.05/s, HeyGen Video 1 $0.036/s, MiniMax H3 $0.08/s, Seedance 2.5 $0.23/s, Kling 3 Pro $0.34/s | judge by frames |
+| Local (LTX-2.5, Wan 2.2 5B) | free; about 10 min for 10 s, or over an hour a clip, 70+ GB weights | not practical on a laptop |
+
+Controls differ per model, and a model's ceiling is not the medium's (read Aug to Oct 2026; re-read the
+schema before boarding, because the newer models were the ones that had grown the controls an older
+shoot failed for want of):
+
+| Model | Durations | Sound | Controls worth knowing |
+|---|---|---|---|
+| Veo 3.1 (and fast, lite) | 4 / 6 / 8 s | yes, with dialogue | `reference_images` 1 to 3; `image` + `last_frame` to join shots |
+| Kling 2.5 Turbo Pro | 5 / 10 s | no | start and end image; no seed |
+| Kling v3 | 3 to 15 s | yes | `multi_prompt`, up to 6 shots in one call |
+| Kling v3 omni | 3 to 15 s | yes | `reference_images` up to 7; `reference_video` as a base to edit a clip |
+| Seedance 1.5 Pro | 2 to 12 s | optional | `camera_fixed`, `seed`, first and last frame; 720p only on Replicate |
+| Seedance 2.5 | up to 30 s | yes, with dialogue | `reference_images` up to 30, `reference_videos` up to 10, `seed` |
+
+- **Spend on the expensive models only where a face or spoken dialogue has to persist.** A held static
+  shot with no face is the commonest thing a board asks for, and the cheapest model does it for about a
+  fortieth of the dearest (per-second prices in `costs-and-licences.md`). In one production a single 6 s
+  take on the dearest model was a third of the spend for a fourteenth of the footage.
+- **One-shot to test a concept, composite to build it.** Veo will one-shot a split screen with spoken
+  commentary ($1.20 for 8 s on the fast tier), which answers "does this idea work" in minutes. It can't
+  re-roll half a frame, hold one room in both halves, set its own lettering or keep voices across shots;
+  compositing separate panes can.
+- **Provider overload is not your prompt.** Veo's `high load` failure (`code: 8`) once failed one shot
+  eight times in a row while a sibling succeeded. Retry unchanged; don't rewrite the prompt.
+- **Check a model is still served** before boarding on it, on the vendor's own deprecations page:
+  OpenAI removed Sora 2 and its Videos API on 24 Sep 2026 while a reseller still listed it, and a shot cut
+  from a removed model can't be re-rolled.
+- **A cheap concept test:** one 8 s Seedance call with audio (about $0.42) made a three-shot ad that
+  spoke every scripted line correctly. Its product interface was gibberish and the voice unnatural, so
+  it tests an idea and never ships.
+- **Budget 3 to 5 attempts a shot.** One production made 7 takes and kept 3, for $7.22. The price spread
+  between models for the same shot is about 15×, and that spread is the budget.
+- **Board before shooting:** write the shots and get the plan approved, check the schema against every
+  rule, make one cheap still per setup, then video. One $7 set made before its board was approved
+  returned 3 usable seconds.
+
+## The invention check (for any generated motion near real things)
+
+Review every clip by its frames, not by its first frame. For anything that must stay true: count faces
+on about 20 frames against the source; ask a vision model narrow questions (*"any person, figure,
+silhouette or animal?"*), not open ones (an open "boats: yes" turned out to mean the cabin the camera
+was in); measure camera shift; map where the pixels changed. **Only animate stills whose motion is
+obvious and that have no faces** (water, fire, light, sky).
+
+## Generating assets for a product build
+
+When generated images or music ship inside an app or a game, generate them at build time and commit
+the output as the offline content. The shipped build then holds the files, never the keys or the
+generation code, and makes no network calls for them. If users later generate their own at run time,
+that is a separate code path that calls the project's own server, which holds the key; never bundle a
+key into a client. Keep one canonical copy of the generated files and let other targets mirror it,
+never regenerate per target. Large binaries go through git LFS: commit `.gitattributes` before the
+files, and after a fresh clone check the build reads real bytes, not LFS pointers. A chain of
+providers (best quality first, a cheaper one, then a free on-device floor) lets a run degrade instead of
+failing, chosen by which keys are present and logged per file (this is a planned chain, unlike a
+silent fallback); check each level's licence (MusicGen weights are
+non-commercial).

package/skills/content-studio/references/real-people.md

@@ -0,0 +1,108 @@
+# Real people: photos, faces, voices, and personal content
+
+This applies to anyone's real photos, videos, voice or words, and to personal pieces for family and
+friends (a trip, a month, a child's year, a tribute).
+
+## Consent and what leaves the computer
+
+- **A person's own media is shown as it is.** Never redraw, "enhance", animate, age or re-pose a real
+  person, and never generate a person into real memories. Restoration is the one exception, and only
+  at the owner's request, compared with the original at the faces (`stills.md`).
+- **Nothing of a person's goes to a hosted model without a yes for that specific use.** Keep the pixels
+  local. An agent can plan a film from text alone (local captions, face boxes, times, places, transcripts),
+  and the quality checks can run locally too.
+- **Say exactly what is local and what isn't.** Never write "nothing leaves your computer" when an AI
+  provider reads anything.
+- **Names come only from the person's own tags or words.** Someone tagged nowhere stays unnamed.
+- **Never use synthetic faces as evidence of quality.** Generated "family" photos (everyone centred,
+  facing the camera, in the same jacket) read as AI-made and say nothing about real material.
+- **Real people in demos and posts:** blur names and faces of anyone who hasn't agreed. A customer is
+  named only with their consent.
+
+## Cloning a voice
+
+1. Consent from the **voice's owner**, never from whoever uploads the audio. Verify it live (they read
+   a random phrase shown on screen).
+2. Purpose-bound, revocable, deletable. Treat the voice as biometric data: encrypted, on the device,
+   never used for training.
+3. An older relative consents in their own voice while alive. After death: only with consent given in
+   life or the next of kin's agreement, and only to read words they actually wrote or said. **Never
+   invent new statements in a dead person's voice.**
+4. **No children's voices.**
+5. Label every cloned output, in the piece and in its metadata, and keep the engine's watermark. The EU
+   AI Act's disclosure rules (Art. 50) apply from August 2026 (check the regulation's current text).
+6. No free-text speech with a cloned voice, rate limits, and never export the voice model.
+7. The engine needs a commercial licence for anything published.
+
+## Get the facts right before anything creative
+
+- **Time and place come from the metadata; what is in the picture comes from looking.** A caption
+  called a cabin window "a train at sunset"; the data said 07:10, at sea.
+- **Compute every count and weekday.** "Three cities" was invented, and the data said five. "Saturday"
+  was said for a Sunday.
+- **No inferences dressed as facts:** "friends" becomes the tagged names; "sunrise" becomes "at sea"
+  when 07:10 was before sunrise; "a new outfit" was said where she only tried one on.
+- **Local time comes from the place's time zone,** not the camera's.
+- A line never runs over a shot from another time or place.
+- **Received photos** (forwarded in a chat) are labelled or left out. A dozen photos stamped the same
+  minute with no location are probably someone else's phone, so say so and ask. Generated images found
+  in a library stay out.
+
+## Read every trail before asking
+
+Before asking the person anything, read everything available (tags, notes, messages, the calendar,
+memos, the work log) and say what you read. Then look for gaps: lay out each day's photos by hour,
+mark waking-hours gaps of two hours or more, and mark which are explained. **Ask one question**, about
+the gap that matters most, neutrally (*"what was happening on Sunday afternoon?"*, not *"what was so
+funny?"*). Fourteen questions is too many. Say which source could have answered it, had it been
+connected.
+
+## The language follows who it is for
+
+Dates, times (Swedish writes 14.20 and lower-case weekdays), and place names (Helsingfors for Helsinki
+in Swedish) move with the language. Translated words aren't quotes, so drop the quotation marks.
+Scan every visible text node for words left in the wrong language. A word the language needs but
+the data lacks (Swedish distinguishes a mother's sister from a father's) is looked for in every trail,
+then asked, never guessed.
+
+## Photos: technical faults that ruin a film
+
+- **Orientation.** Phone HEICs carry an EXIF orientation tag. Converting while keeping the tag and also
+  rotating the pixels makes browsers rotate again: 58 of 120 photos came out sideways. Bake the rotation
+  and strip the tag (ImageIO `CreateThumbnailWithTransform` on a Mac; libheif or pillow-heif applying
+  `irot`/`imir` elsewhere). **ffmpeg applies a HEIC's grid rotation (`irot`) while decoding, even with
+  `-noautorotate`**, so a pipeline that also applies the EXIF turn rotates the photo twice. Portrait
+  phone photos came out sideways that way. The test: if the decoded size equals the stored size with
+  width and height swapped, ffmpeg has already turned it, so don't turn it again. **Check the rendered frames**, not the source files: each shot should match
+  its source best at 0°, and the face roll measured at full resolution should match the source's. A
+  film with one sideways photo isn't a candidate.
+- **Edits in the photo app are lost** when you read the original file. A crop or adjustment the
+  person made isn't in it, so read the edited rendition where the library offers one.
+- **Junk filter:** a utility classifier (receipts, screenshots, decoys) is reliable as a filter (20 of
+  20, no false positives, in one test). An aesthetic score ranks posed groups highest, so never use it
+  to pick.
+- **Live Photos** hold 1 to 3 s of real motion and sound, the authentic version of what image-to-video
+  fakes. A shot longer than its clip plays the clip up to the key moment, then settles on the still. A
+  shorter one centres on the key moment. Keep the sound, ducked. Real motion went from 34% to 85% of
+  a film this way.
+- **Real motion first, generated motion last,** and only on stills with obvious motion and no faces,
+  after the invention check (`generation.md`).
+
+## The personal register
+
+Personal content is the opposite of growth content, so keep its own template: slow dissolves or
+honest cuts, real sound kept (wind, laughter), a serif caption, no kinetic type, no "motivational"
+music. Seven rules for a 30 to 60 s memory piece:
+1. Open on the most specific moment.
+2. One throughline.
+3. A small turn near the end.
+4. Captions in the family's own words.
+5. Music chosen as "day in the life" or "emotional".
+6. Unproduced on purpose. Sharpening and smooth AI transitions push it toward an ad.
+7. End on a face, or a line addressed to the person it is for.
+
+What people respond to: one relationship, one small moment, a line that lands, made to be sent to one
+person. Useful feedback-to-change mapping: "boring, like the phone's automatic memories" → a social or
+product cut opening on the most specific moment; "too fast" → longer shots, no word captions; "I wasn't
+there" → an index card or a cut scene; "who's that?" → only tagged names; "make one for <child>" →
+their photos first, labels in their language, no narrator, about 30 s.