@generativereality/content-studio 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,80 @@
+# The pick: showing work so a person can choose
+
+The pick is where most studio work has failed: not because the work was bad, but because the
+person could not choose between options. They couldn't open the page where they were, they couldn't
+tell the samples apart, or they were asked to assemble a combination. A review page is part of the
+product.
+
+## One best, then a few real alternatives
+
+- **Lead with your recommendation, finished.** The first thing on the page is the version you would
+  post, complete (title, body, image, first comment, everything), ready to approve as it is.
+- **Then two or three alternatives**, each one also complete, and each different in **angle or
+  format**, not in wording. One line under each says how it differs and when it would be the better
+  choice.
+- **Never a parts menu.** A page of 19 titles, 5 bodies and 4 images asked one person to compose about
+  380 combinations. They answered by asking whether it was a bug. If the titles matter, show the best
+  title on the recommended version and list three alternative titles beneath it, no more.
+- **Keep the variations, out of the way.** All the hooks and angles you tried can go at the bottom
+  under a plain heading, for anyone who wants to look. The decision must not depend on reading them.
+
+## Make it reviewable where the person is
+
+- **It opens on a phone.** Use the review mechanism the project has (a card with a review page, a
+  shared document, an artifact link). A local file path opens nowhere but on the machine that has it.
+  Put the full clickable link in the message.
+- **Size:** each image under about 1.5 MB, and the whole page under about 6 MB, or phones drop it. Use
+  stills and short clips. Never embed a full-resolution master.
+- **Label every sample** with what it is, the tool or model that made it, what it cost and how long it
+  took. Unlabelled samples cannot be judged: a reviewer who couldn't tell which voice was which in a
+  concatenated sampler could review none of them.
+- **Side by side** for anything compared (two cuts, two thumbnails, before and after). **One player per
+  voice or clip**, never one long file with all the takes.
+- **Show it as it will be seen:** a feed image at feed size, a vertical clip in a phone frame, a title
+  as it will look in the feed, with the first line of the body under it.
+- **Numbered lists render as lists**, and verdicts and notes stay separate from the work itself.
+
+## Reviewing generated media: board, shoot, review
+
+- **Board before shoot.** No paid clip before the board is approved (`generation.md`).
+- **Re-render the review after every shoot**, including a small one, before reporting. A take nobody
+  has watched isn't a deliverable.
+- **One review doc for the production, not one per round.** Retire superseded material out of it and
+  leave a short ledger of what went and why, so nothing is re-shot by accident; with two docs, the
+  person reads whichever they opened last.
+- **Say what is wrong with each take in the doc, beside it.** The faults found are the review's output;
+  the clips are the evidence.
+- **Import the prompts from the generation script; never retype them.** Guard the script's run loop
+  behind `main()` so the review builder can import its job table. A doc that claimed to extract its
+  prompts while carrying a hand-pasted copy drifted.
+- Keep the markdown body as the source and let a build step embed the clips. Stage web-sized copies
+  somewhere persistent beside the takes, never `/tmp` (one staging folder was wiped mid-project).
+  Transcode small first (about 854 px wide, CRF 27).
+- With a markdown renderer, wrap a `<video>` in a `<figure>` on **one line**: `<video>` isn't a CommonMark
+  block tag and `<figure>` is, and a newline inside the figure leaks the rest as escaped text.
+- With `review-md` (`tools.md`): media needs `--allow-html` and `media-src 'self' file:` in the CSP, or
+  the players look normal and refuse every clip. Confirm in the tab by loading each element
+  (`x.load()`, then `x.error`), not by the player being visible. Heading ids carry no section number, so
+  list them before linking (`[...document.querySelectorAll("h2")].map(h=>h.id)`), and add `?v=N` to
+  reload a re-rendered file the browser has cached.
+- **Verify the render, not its exit code:** count the missing-clip markers the builder writes (it
+  should write a visible one, never a gap), count `<video>` tags, grep for `&lt;figure` leaks, then open
+  it. **Prove an embed is current by hashing it,** not by mtime and not by opening a heavy page (evals
+  timed out on a 13 MB render): decode every `data:` payload, hash it, and match it to the current files;
+  one that matches nothing is stale. When the change under review is to the sound or grade, also measure
+  the embedded clip, because a current file can still be the cut before the fix.
+
+## The question
+
+One question, one line: *"Post the recommended version?"*. Offer up to three one-tap answers that are
+real answers (*"Post it as is"*, *"Use alternative B"*, *"Shorter"*). Always leave a free answer, and
+always a way to say it is wrong, which is not one of the buttons.
+
+## After the answer
+
+- Write the pick or the no, with the person's reason in their own words, into the lessons file.
+- A reason like "sounds like AI" or "not good enough" is new material, not a request to polish: ask
+  what is off and what they would say instead (`voice.md` §critique).
+- A preference is one person's taste, and a fault they saw or heard (choppy motion, a wrong accent, a
+  face that changed) rules a tool out for everyone. Record which kind it was.
+- If they pick, make that version well. Don't ask again about what they have already decided.

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

@@ -0,0 +1,135 @@
+# Search: pages that rank and are worth landing on
+
+A page meant to be found has two jobs, and it fails if it only does one. It has to answer the query
+well enough that a search engine or an AI assistant puts it in front of someone, and it has to be
+worth that person's time once they arrive. Both jobs fail the same way: writing what we want to say
+about our product, in our own words for it, on a query nobody types.
+
+## 1. The query is measured, never guessed
+
+Choose the target query from measured volume (Google Keyword Planner, Search Console, Bing Webmaster
+Tools), and write the measurement down with its date the same day, in a numbered file in the
+project's research folder, because scratch files vanish. Keyword Planner without ad spend gives buckets
+(10–100, 100–1K, 1K–10K, 10K–100K, 100K–1M): precise enough to choose with, too coarse to forecast with.
+What has changed decisions:
+
+- **People search the job, not the container.** An AI-prefixed phrasing ("ai expense tracker app")
+  has measured two to four volume buckets below its plain twin ("expense tracker app"), and in other
+  languages the AI-prefixed form often returns nothing. The AI belongs in the answer, not in the title.
+- **People search the label and the product, not the idea.** A bank-statement label or a product name
+  carries thousands a month; an idea like "private budgeting" carries almost nothing. A page about an
+  idea needs a product or label word in its title.
+- **A brand nobody searches can't carry a comparison page.** Check the brand's own volume first.
+- **Volume isn't intent.** Read the results before choosing: a query whose top ten are all about fees
+  can't be won by a page about something else with the same words.
+
+## 2. Read the results page before writing
+
+Open the query in a real browser and write down what is there:
+
+- **Who owns the top three, and whether any small independent site ranks at all.** That second point
+  is the winnability test, and it is usually kinder than it looks.
+- **What takes the click before the results.** Where an AI overview answers completely, a page that
+  only summarises loses, but **being cited is a way in that ranking isn't**: overviews often cite
+  small sites. Note the narrowing question the overview asks at the end; each split it offers is a
+  page.
+- **People Also Ask, word for word.** They are the best outline for the page's sections. Put FAQ
+  schema only on questions the page visibly answers.
+- **Freshness.** Results dated this week mean a maintained query; undated results mean an open one.
+- **Intent.** "Personal expense tracker" turned out to be a spreadsheet-template query.
+- **What the ranking pages do well:** a method section with numbers in it, a spec block with
+  identical fields per item, jump links, an FAQ, a visible date checked, named experts where real.
+  The best openings in one read of thirteen ranking pages were first-person failure stories, usable
+  only when the failure is real.
+- **What they all leave out.** The gaps are where the page comes from.
+
+## 3. The bar: what does this page have that nobody else's does?
+
+A page about a job **teaches the job in full**: the job in the heading, what makes it annoying, how to
+do it yourself step by step, the named operators people search for in the detail actually verified,
+then the offer to let the product do it. The call to action is gated; the page isn't. Someone who never
+downloads anything should be able to finish the job with the page alone, and that is what makes it
+worth ranking.
+
+**Before writing, name the one thing on this page that neither the ranking pages nor the company's
+own help pages carry.** If you can't name it, don't write the page yet. Sourcing every sentence from
+the operator's own help pages is a reliable way to make a page that adds nothing to those pages. Kinds
+of novelty that have worked:
+
+- **A real run:** we did the job and wrote down what happened, including what went wrong.
+- **A synthesis nobody has done:** the same questions asked of every option, in one table.
+- **What the company doesn't say**, found by reading its pages against each other.
+- **The consequence people act against:** a regulator's sentence that changes what to do.
+- **Something made from the reader's own kind of data:** a real household's numbers (anonymised,
+  presented as "one household", never identifying anyone).
+
+A real run on people's own data is presented as **one household's, never as "ours"**, with every
+identifying detail left out (whose profile, children, names, places). A run on the author's own account
+told in the first person is different, because it concerns nobody else. A paraphrase of the company's
+help pages may sit on the page as the reference half, short and saying whose rules they are, after the
+novel part and never as the reason the page exists.
+
+Three tests before publishing:
+1. **Delete the product paragraph.** Is the page still worth reading?
+2. **Can someone actually follow it?** Real steps with the real friction: which button, which export,
+   what goes wrong the first time.
+3. **Does it answer the awkward question too**, honestly, even when the honest answer sends the reader
+   elsewhere?
+
+## 4. Facts from the primary page, quoted and dated
+
+- The vendor's, operator's or regulator's own page is the only acceptable source; directories and
+  review sites are often wrong or stale (three of sixteen listings checked in one directory were).
+- Quote the sentence and keep its address and the date read beside the draft; a footnote lets a
+  reader check it.
+- "Not stated on their site" is a finding, and isn't the same as "no".
+- **Never invent a number for illustration.** If it wasn't measured, write the sentence without it.
+- A page whose facts age shows the date they were checked, where the reader sees it.
+
+## 5. The opening is for the reader
+
+The first lines say who the page is for and answer the question, then date the facts. It is not a
+note about our research. Headings are plain and say the thing.
+
+## 6. Comparison pages
+
+A title like *"X or Y?"* tells the reader they are choosing. When the two don't do the same job, say
+so: frame it as "who does what" (tables like "a month with both", not "a month with each"), with no row
+leaning our way and at least two rows where we answer "no". Record per comparison whether the other
+product competes, and let a test pin the page's framing to it. A comparison with no real difference in
+it is a pitch with a new heading.
+
+## 7. Writing for AI assistants as well
+
+- In a study of generative engines (GEO, KDD 2024), adding quotations, statistics and cited sources
+  raised a page's visibility in AI answers the most, roughly 30 to 40%. An authoritative tone didn't
+  help, and keyword stuffing did worse than nothing. Answer the question in the first two sentences;
+  write self-contained, citable claims, each number with its source.
+- Assistants search in long specific queries (about 12 words on average for one of them, 2026) and lean
+  on *best*, *review*, *vs*, *alternative* and the year. A title should contain the words such a query
+  would: on an "X alternative" query they cited small pages with *alternative* in the title and missed
+  pages titled "X or Y?".
+- Answer each sub-question in its own paragraph or table row, because assistants lift the piece that
+  answers their part.
+- Carry a `dateModified` (Article schema) from the date the facts were checked.
+- Where assistants look matters more than markup: ChatGPT search, Copilot and DuckDuckGo use Bing's
+  index; one major assistant most likely uses Brave's, which has no submission console and finds pages
+  through links from sites it already indexes (forums, code hosts, directories); Perplexity has its own.
+  Ping Bing (IndexNow) after every release that adds or changes pages; a 403 on the first run after a new
+  key is key validation, so run it again. `llms.txt` exists but no major assistant has committed to
+  reading it.
+- **Describe the product exactly**, because an assistant repeats it word for word. Never claim more
+  privacy or capability than is true.
+- Search engines accept AI-assisted pages that add value and treat mass pages without it as spam.
+
+## 8. After it is live
+
+Check the page serves (grep for a phrase only the new build has), is in the sitemap and isn't
+blocked by robots.txt. A page waiting for approval must not ride along on someone else's release, so
+keep it on its own branch. Search Console and Bing Webmaster Tools are the feedback, not opinion:
+impressions with no clicks means a title or answer problem; neither means not indexed or not
+competitive. Search Console data lags about four days and covers Google only. Bing Webmaster Tools'
+AI Performance report shows Copilot citations and the grounding queries behind them, the nearest thing
+to a list of what assistants search. Which crawlers actually read a page is in the CDN's request logs
+by user agent (OAI-SearchBot and ChatGPT-User, ClaudeBot, PerplexityBot, DuckAssistBot). Expect nothing
+for weeks on a young domain: the first pages are an investment in a corpus, not a test of one page.

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

@@ -0,0 +1,112 @@
+# Stills: thumbnails, covers, carousels, lead images, collages
+
+**Code sets the words, AI makes pictures and decoration, and no generative model touches a real photo
+it isn't explicitly restoring.** That rule decides most of this file. Every model asked to "arrange" or
+"restore" photos redrew faces a little. Every current model spells a headline correctly, so the
+reason to set type in code isn't spelling: one word can change without re-rolling the picture, and
+the brand stays exact.
+
+## The idea comes from the subject
+
+Seven image models answered one thumbnail brief with the same layout (condensed headline left, phone
+in hand right). The only thumbnail that looked designed was built from the product's own output: a
+transcript with its filler words struck out. **The sameness is the slop.** Start from something real
+and specific to the subject: its own output, its own screen, a real photo, a real number. Write
+the idea down before opening any tool.
+
+## Recipe A: layout in code (the default)
+
+1. One `brand.css` with tokens and fonts. Bundle OFL fonts locally, with no font CDN at render. **Never
+   name a font family `Serif` or `Sans`**: unquoted, those are CSS generic keywords and Chrome silently
+   draws Times. Give custom families unique names.
+2. One HTML file per frame, sized exactly to the output.
+3. Render with headless Chrome: `scripts/render-frames.sh <out-dir> <w> <h> <frame.html>…`. It uses the
+   installed Chrome or Chromium, at 0.1 to 1 s a frame, and runs the same on Windows.
+4. Gate: contrast and anti-slop (`npx impeccable detect <folder>` caught a real 3.2:1 grey), then
+   **open every PNG and look**. Faults found only by looking: a title on a busy patch, a note behind a
+   print, a cropped footer, a caption box over the screenshot, an accent dot vanishing on an
+   accent-coloured slide.
+5. Measure margins in code rather than by eye; uneven ones (71/61/61/52 px) read as sloppy.
+
+Without a browser (a server, a Worker), use Satori with resvg (MPL-2.0, fine to bundle). It needs static
+TTF fonts, an explicit width on every text box (or text won't wrap), and footers pinned with absolute
+positioning.
+
+## Recipe B: a generated background under typeset text
+
+Ask the model for the picture only, and end the prompt with *"No printed matter, no writing, no labels,
+no logos"*. Local models write gibberish on any paper or sign in the scene without it. Then use the
+image as the CSS background in recipe A. See `generation.md` for models.
+
+## Carousels
+
+- Slide 1 carries the hook; each later slide is one item with its proof; the last slide is the next
+  step. A list that overflows the screen gets saved.
+- **Model-drawn carousels:** make slide 1, then pass it as the reference image for slides 2 to 5 with
+  *"use the attached slide 1 as the exact design system"*, in parallel. Ask for 2K, because 1K returns
+  928 × 1152, below Instagram's 1080 × 1350. One run of five cost $0.17 and took about 30 s (Nov 2026).
+  The output is a flat bitmap, so a typo fix is a re-roll and the re-roll will differ. Prefer recipe A
+  for anything with text that may change.
+
+## Lead images of a real product
+
+Use a real screenshot or a real recording frame, framed and captioned in code. Never mock up a screen,
+and never let a model "improve" one. If the screenshot shows a stale or wrong state (another brand's
+name in the header, a debug banner), get a new one; don't paint over it. Blur real people's names
+in it. Test the image at the size the feed shows it (often about 400 px wide on a phone).
+
+## Collage (the "paper reel")
+
+A layout of 3 to 8 pictures on a generated paper, as a still and as a 5 to 10 s film. People find it
+very shareable.
+1. **Paper,** one per output size. Prompt: *"decorations only along the outer 12% of the frame; the
+   whole centre plain, evenly lit; top-down; no photos, screens, text, people or hands"*. A hosted model
+   at 2K costs about $0.05 and takes about 30 s; a local one is free but slower, with a less clean
+   centre (put the title on a card). **The paper's mood is the choice**, and the layout follows it.
+2. **Spec:** theme (notebook, desk, cork, scrapbook, album, journal), layout (scatter for many photos,
+   grid for calm, hero with satellites, timeline for dates), motion (drop, fade or slide in; camera
+   drift, push or pan).
+3. **Layout in code:** take a decoration mask from the paper; detect faces (YuNet, MIT) so no crop cuts
+   one; seed and score placements against decoration and overlap; put notes where they cover nothing
+   and the title in the least decorated spot. Make the still from the end state, not the last frame
+   of a camera move. Step the film frame by frame into ffmpeg.
+4. **Accept only if** no face is cut, the title and prints overlap decoration by less than about 15%,
+   you have looked at the still, and the film decodes.
+5. A person's own photos are never altered and never sent to a hosted model without their yes. Make
+   the paper locally or reuse one.
+
+Faults seen: a still taken from a zoomed last frame crops the margins; strings or arrows drawn across
+interface text make it unreadable; the hero print got buried under the others until grid cells fixed
+it. Feeding all the photos into an image model to "arrange" them redrew every face.
+
+## Thumbnails
+
+Note the conventions of the outliers in the niche (colour, amount of text, face or no face,
+composition) and decide on purpose. The title and the thumbnail are one promise, so don't repeat the
+title in the image. Text readable at phone size. Make two or three that differ in idea, not in colour,
+and let YouTube's Test & Compare decide, not taste.
+
+## Covers
+
+A cover makes someone stop and feel the claim. An illustration that carries the argument beats a data
+chart; charts belong in the body as evidence. For a personal album or keepsake, the person's untouched
+photo with a well-set title is usually the one to use. A painted version made from it is a separate,
+labelled option.
+
+## Restoring an old photo (a person's own, at their request)
+
+- **Most faithful:** a top hosted editor with *"Do not change any face, expression or pose"* (Nano
+  Banana Pro, about $0.15 at 2K, Nov 2026). **Best value:** Nano Banana 2.1 at 2K, about $0.05 (it slightly
+  enlarged a child's eyes). **Best free:** a local FLUX 3 Klein edit, then Real-ESRGAN.
+- **Always compare original and result side by side at the faces** before accepting.
+- **Upscale only after cleaning:** Real-ESRGAN on a raw scan sharpens the scratches as detail.
+- **Colourising invents facts** (eye and hair colour). Offer it as a separate, labelled version, never in
+  place of the original.
+- Don't use: GPT Image (reframed the photo and redrew two new children), Kontext's restore app
+  (colourised unasked, with modern faces), GFPGAN and CodeFormer (kept every scratch and put blue eyes
+  into a black-and-white photo; CodeFormer is also non-commercial), OpenCV inpainting (faces to mush).
+
+## Fixing a bad generated detail
+
+Remove the object rather than asking for a repair. A backwards hand was fixed by *"lying on the
+surface, no hands"*. Asking a model to repair the hand kept it backwards and re-laid out the whole image.

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

@@ -0,0 +1,26 @@
+# Tool skills this one routes to, and where it overrides them
+
+content-studio holds the process and the craft. For a tool's own mechanics, read that tool's skill
+when it is installed. Where a tool skill's defaults conflict with the rules here, **this skill wins**,
+because its rules protect the person (cost, consent, nothing going out). Those conflicts are listed
+below.
+
+| Tool skill | Use it for | Overrides from content-studio |
+|---|---|---|
+| `hyperframes` (+ `hyperframes-cli`, `hyperframes-registry`) | HTML-to-video: the render contract, motion craft, captions, the registry of ready-made blocks (transitions, titles, charts, maps). Search the registry before hand-building any named visual. | Telemetry off (`npx hyperframes telemetry disable` or `HYPERFRAMES_NO_TELEMETRY=1`); `init --skip-skills` so it doesn't write skills into the person's global folder; **never** its `publish`, `cloud`, `billing` or `feedback` commands, and no cloud render, without the person's yes; render only after the person picked (the pick in `review.md` replaces its own approval step) |
+| `media-use` | sourcing media for a HyperFrames video: catalog music and images, logos (never redrawn), cutouts, colour treatments, transcripts | **Always show what a run cost** (it says never to); local and free first where quality is equal, not only when asked; no HeyGen-hosted generation of a real person |
+| `review-md` | rendering a markdown review page to one HTML file, or an artifact | media pages need `--allow-html` and `media-src 'self' file:` in the CSP, or `<video>`/`<audio>` are silently refused; verify a media page by decoding each embedded file, because an automation browser may load no audio |
+| `browser-automation` | reading a place's rules and outliers in the person's signed-in browser; preparing a post in its form for the person to send; screen-recording a web app | read-only unless preparing a draft; never press post, send or submit |
+| A personal voice skill or voice notes (whatever the person keeps) | their voice, their banned words, their lessons | it overrides `voice.md` wherever they differ |
+| A strategy or growth skill (positioning, channels, bets) | what to say, to whom, where and why now | content-studio never overrides its decisions; it raises doubts in the brief |
+
+## Scripts in this skill
+
+The `.sh` scripts need bash: on Windows, run them from Git Bash (which Claude Code on Windows uses).
+`spend.mjs` needs only Node.
+
+| Script | What it does |
+|---|---|
+| `scripts/voice-sweep.sh <file>` | the mechanical machine-prose sweep: em dashes against paragraphs, short fragments, banned words, negative-parallel shapes, drumbeat lines. Exit 0 always; read the hits |
+| `scripts/render-frames.sh <out-dir> <w> <h> <frame.html>…` | renders HTML frames to PNG with the installed Chrome/Chromium headless (macOS, Linux, Windows Git Bash) |
+| `scripts/spend.mjs add|total` | the per-piece spend ledger (`spend.jsonl` in the piece's folder) |

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

@@ -0,0 +1,155 @@
+# Video: demos, explainers, reels, launch clips, memory films
+
+Video prefers pieces that combine real footage, stills and animation over any single one. A narrated
+slideshow is the least exciting format there is, and to many people it reads like the phone's own
+automatic "memories" feature.
+
+## The pipeline
+
+1. **Script and shots first,** as one timeline file (JSON): shots, text, captions, focus points,
+   music, end line. The agent's job is writing the timeline; any renderer can consume it.
+2. **Voice (if any) and its transcript** for word timings (`audio.md`).
+3. **Render:** for HTML-based motion, use **HyperFrames** (HTML + GSAP rendered to MP4 through Chrome
+   and ffmpeg, Apache-2.0); read its own skills for the render contract (`tools.md`). For a
+   zero-dependency route, use Pillow + ffmpeg. Remotion is the fastest renderer, but it is free only
+   for up to three employees and doesn't normalise loudness. The renderers look nearly identical on the
+   same timeline. HyperFrames' text came out slightly clearer.
+4. **Check:** `hyperframes check` (it caught captions too short to read, an end card too short for its
+   credits, overlaps, type under 28 px and low contrast), a contact sheet of frames to look at, then
+   the encode checks below.
+
+A timeline shape that has worked well for photo-and-clip films:
+
+```json
+{"width":1080,"height":1920,"fps":30,"style":"calm|cut",
+ "shots":[
+   {"photo":"<file>","seconds":3.2,"motion":"push|pull|pan-left|pan-right|none","focus":[0.5,0.4],"caption":"…","transition":"cut|dissolve"},
+   {"clip":"<file>","from":1.2,"seconds":2.5,"sound":true,"caption":"…"},
+   {"card":{"title":"Day 2 · Saturday","lines":["…"]},"seconds":2.0}],
+ "music":"<file>","music_db":-10,"end_line":"…"}
+```
+
+Calm style pushes 1.00→1.09 with dissolves; cut style punches in 1.04→1.18 with hard cuts. A text that
+needs longer than its shot's seconds is a warning to fix, not a render to ship.
+
+## Cut craft
+
+- **Open on the most specific moment,** never a title card.
+- **A real person's recorded voice sets the order** (a memo, an interview, a founder talking): edit
+  to the order of the telling, not to the timeline, and use the word timestamps to put each shot on
+  the word that names it.
+- **Cut on the words.** Hard cuts on the narrator's or speaker's words, using word timestamps.
+- **Punch in** toward the face or the subject (1.04 to 1.18).
+- **Real sound from real clips:** the loudest 2.5 s window of a clip, one to three times a film, ducked
+  under any voice. Never use a performance's music.
+- **One label per run of shots** (a day and place on a dark pill). Per-shot labels stack up and become
+  unreadable in fast cuts.
+- **Index and stats cards** (*"Day 2 · Saturday · harbour, market"*, counts computed from the data),
+  and an **itinerary map** where the route matters: the camera follows the route, solid where there
+  are pictures, dashed and captioned where not.
+- **For what wasn't filmed:** an index card, a cut scene done properly in motion design, or generated
+  stills in one style. Crude drawn shapes look terrible.
+- **End on a line that lands,** or a face, or a line addressed to whoever the film is for.
+- **Lengths:** social 35 to 45 s, product 45 to 55 s, scrapbook 30 to 40 s, calm slideshow 50 to 70 s.
+- **Offer different styles** (social, product, scrapbook, calm) from the same material, and say which
+  you'd pick and why. The person's favourite changes with the material.
+
+## Showing a real product
+
+Every frame is the real product. Record the real web app with Playwright and a Chrome DevTools
+screencast (3× device pixel ratio, about 45 fps, recorded in real time), or record a native app with the
+OS screen recorder, then compose the result with punch-ins and captions. Best: write the demo screen as
+a page whose state is a pure `render(t)`, so the same page can be recorded live and seeked frame by
+frame by the renderer. Caption pills must not cover the rows you are showing during a punch-in.
+
+Recording a native app on macOS (four takes once captured the wrong thing without one error):
+- **Use `screencapture -v`, not ffmpeg `-f avfoundation`.** avfoundation records whoever is on the
+  console whatever user it runs as, its device numbers differ per session (one session's "screen" was
+  the other's camera), and its feed froze while the file kept growing.
+- **`screencapture -v` writes the file only when `-V <secs>` runs out; an interrupt saves nothing.**
+  Record in short parts (`-V 60`) in a loop and stop by letting the part in flight finish.
+- **Prove the picture moved:** hash the menu-bar clock region of each part's first and last frame. A
+  frozen capture otherwise looks like a quiet screen.
+- **Address footage by wall-clock time,** and have whatever drives the app write a UTC event log, so a
+  cut is written against events and every on-screen line can be checked against what happened.
+- Background tabs and covered windows aren't on camera: lay out the windows before the take, with the
+  driven browser tab the one showing.
+- **Compose screen recordings in a renderer with sub-pixel transforms,** not ffmpeg `zoompan`, which
+  moves in whole-pixel jumps (still for 6 or 7 frames, then a jump): judder on interface text. Master
+  at 4K, crop as clipping boxes, push in with a CSS transform, set captions as real text. Remotion
+  writes full-range `yuvj420p` / bt470bg; convert to tv-range bt709 for deliverables. A zoomed-out
+  recording at 720p leaves interface text at about 7 px.
+
+## Captions
+
+- **Caption text comes from the script; timing comes from the transcript,** zipped word by word by
+  position. Whisper writes "That's spinach" for "That spinach?" and misspells names, so its text is never
+  the caption.
+- **Reading time** at least 0.5 s + 0.3 s a word; type at least 28 px at 1080 wide; contrast at least
+  3:1. White on light images measured 1.4 to 2.3:1, so give them a soft dark backing.
+- Bold word-by-word captions for social cuts; phrase captions for calm films. 17 to 20 characters a
+  second is a comfortable pace.
+- **Over a voice, a caption is on screen exactly while its line is spoken.** A separate reading-speed
+  floor (15 characters a second) made every voiced cut drag and made a faster voice change nothing. A
+  text-only cut of the same film takes the voiced cut's timings.
+- Translated captions with no voice: spread the timing by word length.
+
+## Crops
+
+- 9:16 from landscape: set a focus point per shot (faces and saliency), or the subject is lost. Set it
+  on the subject of the line being said: a portrait crop once cut someone out of their own goodbye.
+- A group wider than the slice is shown whole over a blurred, darkened copy of itself. Never letterbox.
+
+## Motion that survives a seek
+
+HyperFrames renders by seeking. GSAP suppresses `call` and `onUpdate` on a seek, so counters are
+stacked numbers switched with zero-length sets, and flicker is precomputed from a seed. Move with
+transforms, not `top` (which snaps to pixels); use `svgOrigin` in SVG; never overlap tweens on one
+element; start overlays hidden.
+
+## HDR phone clips
+
+iPhone clips are HDR (HLG), and some renderers then promote the whole film to HDR at a fraction of
+real-time speed. Tone-map to SDR BT.709 first (`avconvert --preset Preset1920x1080` on a Mac in about
+2 s a clip; ffmpeg `zscale` + `tonemap` elsewhere, which needs zimg), then render as SDR.
+
+## Encode and verify
+
+- Master: x264 CRF 18 at 1080p. Chat copy: H.264 720p at most about 15.5 MB. HEVC 1080p is about 10 to 16 MB.- Always `-movflags +faststart`, or a browser downloads the whole file before playing a frame. A `-c
+  copy` concat doesn't inherit it, so name it again, and check the atom order (`moov` before `mdat`)
+  rather than trusting the flag was passed. Ask what each intermediate is for: a clean master that
+  existed only as a pre-burn concat had no faststart and no home.
+- Loudness: −14 LUFS for social, −16 to −18 for a quiet film, true peak −1.5 dB (`audio.md`).
+- **Verify by decoding, not by exit code:** `ffmpeg -v error -i out.mp4 -f null -` prints nothing when
+  the file is sound; a killed render leaves a file of the right size that is truncated. Run a backgrounded
+  build under `python3 -u`, or its log stays empty and reads as a hang. Transcribe the finished mix once
+  more.
+- **Count frames; never read `Duration:`** (it reported 7.62 s and 7.63 s for parts a whole frame
+  apart). Count with `ffmpeg -v error -i f.mp4 -map 0:v -f null - -progress /dev/stdout`. Three causes
+  it hides: `-t` before `-i` cuts at a packet boundary (after the filter it is exact); a video-only part
+  rounds differently from one with audio, so build every part with the same command, silent track
+  included; and `-shortest` with `-c copy` drops frames. Use `-shortest` only for a truly unbounded
+  input (a looping bed, `anullsrc`).
+- Some ffmpeg builds (Homebrew 9.x, Remotion's bundled one) have no `drawtext` and no subtitles filter.
+  Text comes from the HTML layer or Pillow, never from ffmpeg. An app-bundled ffmpeg that has `drawtext`
+  may lack a fontconfig configuration (pass `fontfile=`), and with a variable font a newline inside one
+  `textfile` draws a missing-glyph box: one `drawtext` per line.
+- **The poster frame is a deliverable,** with its own build step. Take it from the captioned master,
+  and derive the timestamp from the subtitle cue whose line it should carry, so retiming the line moves
+  the poster. Then check the page uses it: a site may mount its own local still, so re-uploading changes
+  nothing a visitor sees (read the page's `poster=` attribute).
+
+## Publishing the file
+
+- **Serve a draft film at a stable URL** and overwrite it; mint a dated copy only when a published embed
+  must not change underneath it. Check the CDN's caching before building around it: an overwrite may
+  be live at once.
+- **Verify an upload by hash, and know when the ETag can't answer.** For a single-part S3 or R2 upload the
+  ETag is the MD5; above the multipart threshold (about 8 MB for `aws s3 cp`) it ends in `-<parts>` and
+  never matches. Download and hash instead; don't recompute a multipart ETag, which depends on a
+  configurable chunk size. Four perfect uploads once reported as failures this way, and a check that
+  cries wolf on the normal case gets ignored on the real one.
+- **"Is this new?"** When someone reports a fault in a cut they approved before, fetch the published
+  version and compare before reasoning about recent edits. Validate the comparison first: a correlation
+  at a guessed offset read 0.02 ("different files") for identical audio. Compare windowed RMS, and scan
+  for the alignment if you correlate.

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

@@ -0,0 +1,115 @@
+# Voice: the person's words, and prose that doesn't read as machine-made
+
+Readers now assume low-effort text is machine-made and trust it less. Merriam-Webster's word of 2025
+was *slop*. In a 2025 survey of 3,000 US adults, trust in a piece fell by nearly half when people
+believed AI made it, whether or not it did (Raptive). Some places ban generated text outright (Hacker
+News). So voice is the first craft problem, not the last polish.
+
+## 1. The person's material first
+
+Before the first draft of anything published under someone's name:
+
+1. **Ask for their material, not the copy.** One question with no draft attached, built from what you
+   found: *"What did you think when you saw the first real sign-up?"*, *"Which of these three threads
+   would you actually reply to, and what would you say?"*. Never *"what should the post say?"*. Say a
+   spoken answer is welcome and that a minute is enough.
+2. **Build from their answer.** Keep their phrases, their order of telling and their opinion. Cut and
+   arrange; don't paraphrase into smoother words. On the review page, mark which lines are theirs.
+3. **Look for their written voice.** Their published posts, a voice notes file, their lessons from
+   earlier picks, and any voice skill they keep for themselves. Read those before writing, and follow
+   them over this file wherever they differ.
+4. **Name the sources** of the person's material beside the draft (which answer, which memo, which
+   earlier post), so the next version can go back to them.
+
+A piece the person didn't shape isn't ready for review, however well it scores.
+
+## 2. The critique is new material {#critique}
+
+When the person says it sounds like AI, misses the point, or asks how this is good, **do not reword
+the same draft**. Answer their question honestly (including *"it isn't, and here is why"*), ask what is
+off and what they would say instead, and rebuild from their reply. After a piece has been sent back
+once, offer two or three one-line directions or ask for their dictation; don't write another full
+draft on your own.
+
+## 3. The tells
+
+Machine drafts perform emotion instead of expressing thought: they build suspense, stage reveals and
+punch up clauses, where a person talks through a thought and lets the content be the drama. Each of
+these tells has killed a real draft. Rewrite the sentence; don't just swap a word.
+
+1. **Dramatic fragments and one-line paragraphs.** *"That's not what happened."* *"Free. Local. Yours."*
+   Carry the beat inside a full sentence.
+2. **Meta-narration.** *"Here's the part that…"*, *"Here is the trap"*, *"Let me explain"*, *"The part
+   nobody puts in these posts"*. Do the thing instead of announcing it.
+3. **Negative parallelism.** *"Not X. Not Y. Z."*, *"It's not about X, it's about Y"*, and the
+   two-sentence version *"X was not the total. It was the spread."* Say what the thing is.
+4. **Rule of three.** Triads for rhythm read as machine rhythm. Use two items, four, or a sentence.
+5. **Zinger endings.** Paragraphs ending on a quotable punch line. End with the thought completed.
+6. **Rhetorical question answered at once.** *"Is it faster? No."* Make it a statement. Real questions
+   to the reader are fine.
+7. **Em-dash punch-ups.** One dash per paragraph is the tell. Commas, parentheses and colons do the work.
+   When you remove a dash, re-read the sentence, because removing the pause can change the meaning
+   (*"the ones that were not — in a browser on your own machine"* became a sentence about something
+   else). Split the sentence or use a full stop. A dash doing comma or colon work isn't the tell; dashes
+   added for emphasis, about one a paragraph, are.
+8. **Uniform rhythm.** Every paragraph two to four sentences of the same length. Vary it the way speech
+   varies.
+9. **Escalation.** Everything world-changing. Plain understatement carries the extraordinary better.
+10. **AI vocabulary.** pivotal, delve, tapestry, testament, vibrant, boasts, foster, leverage (as
+    filler), landscape, intricate, meticulous, showcase, garner, seamless, unlock, supercharge,
+    game-changer, "in today's fast-paced world", "the reality is", and the sincerity tic ("to be
+    honest").
+11. **Copula avoidance.** *"serves as"*, *"functions as"*, *"marks"*, *"represents"* where *is* would do.
+12. **Elegant variation.** Rotating synonyms to avoid repeating a word. People repeat their words.
+13. **Trailing -ing clauses** (*"…, highlighting the importance of"*), emoji bullets, a bold lead-in
+    on every line, a summary at the end.
+
+What reads as a person: long sentences that carry a whole thought, in speech order, connected with
+*and*, *so*, *but*, *because*; concrete names, numbers and what actually happened; the writer's own
+uncertainty said plainly; a dry aside; plain descriptive headings; an invitation instead of a call to
+action; numbers stated once, precisely, without ceremony.
+
+**Where this applies:** everything published under the person's name, and correspondence sent as them
+too (a support request, a reply to a partner), where one staged sentence is a large share of a short
+message and the register is plainer still. Release notes count: they drift into feature-marketing
+voice, every item a small triumph with a beat at the end. Channels change the register (tighter on a
+professional network, more instructional in a course), never the list of tells.
+
+## 4. The sweep, and why it isn't the check
+
+Run `scripts/voice-sweep.sh <file>` over every text before review. It counts em dashes against
+paragraphs, lists short fragments, and finds the banned phrases and the commonest negative-parallel
+shapes. It is a net with known holes. Pages have gone out passing every grep while carrying two tells
+in one sentence. A launch post sent back as "way too AI generated" came up almost clean: what gave it
+away was its shape (a slogan argued with in the title, tidy labelled sections, a bullet list explaining
+itself), which no grep sees. So, after the sweep:
+
+- **Read it aloud as the person.** Would they say this sentence on a call? Rewrite any sentence you
+  can picture on a conference slide.
+- **Count the shapes no grep finds:** how many paragraphs end on a punchy clause (more than one or two
+  means the prose is performing), and whether three paragraphs in a row have the same shape.
+- **Three parallel full-length sentences** starting the same way (*"The … you meant to …"* three times)
+  are a fragment drumbeat even though each is long.
+- **Negative parallelism split by a full stop** (*"X was not the total. It was the spread."*) and the
+  bare *"What it is missing is not A. It is B, C and D"* slip past comma patterns; the sweep has a line
+  for the first shape, and reading catches the rest.
+
+The fragment list is candidates, not verdicts: brand names with a dot and abbreviations come back as
+false positives, and a short fragment is sometimes right (a deliberate two-word line in an approved
+hero). On `.svelte`, `.ts` or `.html` files the sweep skips comments, so a dash in a code comment doesn't
+count as one in the copy.
+
+## 5. A document is not a log of itself
+
+A post, page or guide reads as if written this morning by one author who knew everything in it. No
+*"updated on…"*, *"this section used to say…"*, no editor's notes. A date that says how old a fact
+is ("prices as read on 3 November") is a property of the fact and stays. A date that says when the
+text was edited goes.
+
+This holds for any document meant to be read through, internal plans and review packs included, not
+only published prose. Most self-history wraps a warning a first-time reader needs, because they would
+make the same wrong inference: **keep the correction, drop the autobiography.** Re-aim it from the
+document's past to the reader (*"What this does not mean: X is not solved"*, not *"this section said X
+was solved for a few hours"*). The one exception is an agent-facing operations file, which may name a
+wrong version that escaped into other docs or habits, because someone may still hold it; if nobody does,
+it is autobiography there too.