@generativereality/content-studio 0.0.0-stage → 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "content-studio",
+  "description": "Make content well, in any medium: the production process (brief, variations, one best version for a pick, making it, checks, learning) plus craft and tool references for copy, voice, channels, search, stills, generated images and video, editing, audio and real people's photos.",
+  "version": "0.1.1",
+  "author": {
+    "name": "generativereality"
+  },
+  "repository": "https://github.com/generativereality/content-studio",
+  "homepage": "https://github.com/generativereality/content-studio",
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 generativereality
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# content-studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Claude Code skill for making content well, in any medium and for any purpose: posts, articles,
+pages, newsletters, launches, ads, scripts, short videos, demos, explainers, carousels, thumbnails,
+collages, narration, music beds and personal memory films.
+
+It holds the **process** a small, good studio follows, in `SKILL.md`, loaded whenever something is to
+be made: brief → study what works → variations → **one best version shown for a pick** → make it well →
+check → learn from the pick and the result. It also holds **references**, loaded only when the brief
+needs them:
+
+| Reference | Covers |
+|---|---|
+| `brief.md` | the brief template, purpose (brand, audience, teaching, product, personal), reader awareness |
+| `review.md` | showing work so a person can choose: one best plus a few alternatives, phone-ready review pages |
+| `copy.md` | the one idea, studying outliers, hooks, scripts and story loops, copy rules, sharing, formats, the check, reading results |
+| `voice.md` | the person's own material first, answering a critique, the machine-prose tells and the sweep |
+| `channels.md` | Reddit, Show HN, Product Hunt, directories, blogs, newsletters, LinkedIn, X, Instagram, TikTok, YouTube; sizes |
+| `search.md` | measured queries, reading the results page, the novelty bar, primary sources, writing for AI assistants |
+| `stills.md` | layout in code, generated backgrounds, carousels, product lead images, collages, thumbnails, restoration |
+| `generation.md` | hosted image and video models (dated), POST-then-poll, prompting, consistency, the invention check |
+| `video.md` | timelines and renderers, cut craft, showing a real product, captions, crops, HDR, encoding |
+| `audio.md` | whether to narrate, voice engines by language, verifying speech, music, mixing and loudness |
+| `real-people.md` | consent, voice cloning, facts before creativity, photo faults, the personal register |
+| `costs-and-licences.md` | budgets and the spend log, local or hosted, disk, licences, Windows |
+| `tools.md` | the tool skills it routes to (HyperFrames, media-use, review-md, browser-automation) and where it overrides them |
+
+Scripts (no dependencies beyond bash, node and Chrome):
+
+- `scripts/voice-sweep.sh FILE` finds machine-prose tells (a candidate list, not a verdict).
+- `scripts/render-frames.sh OUT W H frame.html…` renders HTML frames to PNG with headless Chrome.
+- `scripts/spend.mjs add|total DIR` keeps a per-piece spend ledger with a budget check.
+
+## What it never does
+
+It never posts, publishes, uploads, sends, comments, signs up or buys. It never invents a fact, a
+number, a quote or a user, and never shows a product doing what it doesn't do. It never uses a real
+person's face, voice or words without their consent. Every paid call is logged and reported with its
+cost.
+
+## Install
+
+```
+/plugin marketplace add generativereality/plugins
+/plugin install content-studio@generativereality
+```
+
+The skill names no person, company or product, so it can be vendored into any project. Your own voice
+notes, house style and strategy skills sit beside it and take precedence over its defaults.
+
+## Licence
+
+MIT

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@generativereality/content-studio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A Claude Code skill for making content well in any medium: process, craft and tool references, plus small zero-dependency scripts.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/generativereality/content-studio.git"
+  },
+  "files": [
+    "skills/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "bash scripts/check.sh",
+    "leakcheck": "bash scripts/check-leaks.sh",
+    "sync-plugin": "bash scripts/sync-plugin.sh"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/content-studio/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: content-studio
+description: Read first whenever anything is to be made for people to read, watch or hear - a post, thread, article, newsletter, page, guide, listing, launch, ad, email to many, script, video, reel, short, demo, explainer, clip, carousel, thumbnail, cover, image, collage, narration, voice-over, podcast segment, music bed, or a memory film of someone's photos - for brand building, audience building, teaching, product work or personal sharing. Holds the whole production process (brief, variations, one best version shown for a pick, making it well in each medium, checks, learning from picks and results) and routes to the craft and tool references for copy, voice, channels, search, stills, generated images and video, editing, animation, audio and real people's photos. Use also for "make this better", "make it less boring", "sounds like AI", "which should I post", hooks, scripts, content ideas or a content calendar.
+---
+
+# content-studio: making content well
+
+This skill is how to make content well, in any medium and for any purpose. It covers what a small,
+good studio does between "we need a post / a clip / a page" and a finished file that someone is glad
+to have read, watched or heard. Read this file first and keep to its process. The references hold the
+craft and the tools for each medium; load only the ones the brief needs.
+
+**What this skill decides and what it doesn't.** It decides **how to make** the piece. **What to
+say, to whom, through which channel and why now** (positioning, the offer, which bet, whether to post
+at all) belong to the person and to whatever strategy or growth skill sent the brief. When such a
+skill exists in this project, its decisions are inputs to the brief here. Do not overrule them; do
+raise a doubt about them in the brief.
+
+## The rules under everything
+
+1. **Facts are strict, craft is free.** A claim about a product, a number, a person, a customer or a
+   competitor is true, and you can say where it came from. A hook, an angle, a joke, an analogy, a
+   framing, a visual, a title or a sound needs no source; its tests are whether it is true to the
+   subject and the person, whether the reader would stop for it, and whether it leads where the brief
+   wants. Never invent a number "for illustration", a quote, a testimonial, a user or a result. Never
+   show a product doing what it does not do: every picture of a product is the real product (a real
+   screenshot or a real recording).
+2. **The person's own material comes first.** Anything you write alone reads as machine prose,
+   however much craft went into it. The moment, the opinion, the thing that annoyed them, in their
+   words, is what makes a piece theirs. Get it before the first draft (`references/voice.md`).
+3. **Real people are not raw material.** Never redraw, animate, clone or put words in the mouth of a
+   real person without their consent. A person's own photos are shown as they are
+   (`references/real-people.md`).
+4. **Nothing goes out without the person's yes** for that exact piece, unless they gave a standing
+   approval that covers it. You make the piece; you never post, publish, upload, send, comment, buy or
+   sign up. Making it ready to post, open in their browser, is fine.
+5. **Every paid call is logged with its cost**, inside a budget the person set. Say what each piece cost
+   and how long it took. Free and local is the default where the quality is as good; otherwise the best
+   tool within the budget (`references/costs-and-licences.md`).
+
+## The process
+
+### 1. Brief
+
+Write one short brief before making anything (`references/brief.md` has the template). It names:
+
+- **the purpose** (brand, audience, teaching, product, personal) and the **one next step** the piece
+  should cause, and how you will know it did;
+- **the reader**: who they are, where they meet the piece, and how aware they already are;
+- **the one idea**, in one sentence that would still hold if everything else were cut;
+- **the channel and format**: length, ratio, what the place rewards, its rules and its requirements
+  on the account;
+- **the proof and material**: the person's own words, real screenshots, real numbers, real photos;
+- **the voice**: whose it is, and where their voice notes and lessons are;
+- **the budget** in money and time, and what has been sent back before and why.
+
+If a strategy skill sent the brief, keep its fields and add the ones it lacks. Never start making from a
+one-line request without writing this down.
+
+### 2. Study what already works
+
+Before writing a word, look at the place it will appear. Find the pieces in that niche and channel that
+did 3 to 5 times better than their author's usual. Note their hook form, length, structure and what the
+first second or line does, then borrow the **form**, never the content (`references/copy.md` §study).
+Write down three to five of them with links. That is the evidence for the angles you choose.
+
+### 3. Variations, then choose the best yourself
+
+Make many cheap variations before making anything well: ten to twenty hooks or titles, three to five
+angles (a story, a confession, a contrarian take, a how-to, a before and after, a demo, a list with an
+opinion), and two or three formats. Vary the tone as well as the words. Humour is one option and never
+the default.
+
+Then **do the choosing yourself**. Pick the best version and finish it to the point where it could
+go out as it stands, and pick two or three real alternatives that differ in angle or format, not in
+wording. Your job is to bring the person a recommendation, not a parts list.
+
+### 4. The pick
+
+Show the person **one best version, finished, first**, with two or three alternatives below it, on a
+review page they can open where they are, which is often a phone (`references/review.md`). Each option
+is labelled with what it is, what it cost and how long it took, and comparable things sit side by side.
+Never ask them to assemble a combination of numbered parts ("T4 + body B + image 2"). An answer
+should take one tap or one sentence.
+
+The person's part is taste, true stories and opinions, never forms. Every no teaches: write the reason
+down (step 7).
+
+### 5. Make it well
+
+Make the pick properly, in its medium:
+
+| Making | Read |
+|---|---|
+| Words: posts, articles, pages, scripts, captions, emails to many | `references/copy.md`, `references/voice.md`, `references/channels.md` |
+| A page meant to be found in search or cited by AI assistants | `references/search.md` |
+| Stills: thumbnails, covers, carousels, quote cards, collages, lead images | `references/stills.md` |
+| A generated picture or clip (background, scene, B-roll, restoration) | `references/generation.md` |
+| Video: demos, explainers, reels, launch clips, memory films, edits | `references/video.md` |
+| Voice, narration, music, sound | `references/audio.md` |
+| Anyone's real photos, face or voice; personal and family content | `references/real-people.md` |
+| Which outside tool skill to use, and where this skill overrides it | `references/tools.md` |
+
+Set the words in code and keep them editable. Let AI make pictures, motion and sound. Never let a
+model redraw a real person. Captions go on every video, because most people watch without sound.
+Every piece carries the link or tag the brief measures it by.
+
+### 6. Check before anyone sees it
+
+Each reference ends with its own checks. The ones that apply to every piece:
+
+- **Facts:** every claim has its source written down beside the draft, and nothing is invented.
+- **Voice:** run `scripts/voice-sweep.sh` over the text, then read it aloud as the person would say
+  it. The grep is a net with holes; the reading is the check (`references/voice.md`).
+- **Look and listen:** open every image, every frame sheet and every clip. Transcribe every voice track
+  back and compare it with the script. A green exit code means nothing until a human or an agent has
+  actually looked or listened.
+- **The reader's test:** read it cold, as the brief's reader meeting it in that channel. Would they
+  stop, understand the one idea in a sentence, and know the next step? (`references/copy.md` §check).
+- **The place's rules:** length, format, sizes, and the community's own rules and account requirements
+  (`references/channels.md`).
+
+Fix what fails and check again. Doubts about craft get fixed, never handed to the person as a question.
+
+### 7. Learn
+
+Write each pick and each refusal, with the person's reason in their words, into the lessons file the
+brief names (a studio's `lessons.md`, or the project's house style). Once results come in, write the
+winning **formula**, not the piece, into the house style for that channel (for example *"a confession
+title, a 150-word body with one real screenshot, a closing question"*). The next brief starts by reading
+both. A piece that flops teaches as much as one that works: note whether it was the hook, the topic or
+the angle (`references/copy.md` §ceilings).
+
+## Where work lives
+
+Keep the brief, the variations, every take, the review page, the spend log and the lessons together
+in one folder per piece. When a project already has a studio or content folder, use that and say
+where it is. **Never overwrite a take that cost money**: a new attempt is a new file. Keep media out of
+git unless the project says otherwise, and record each asset's licence and where it came from beside it.
+
+## Never
+
+- Make one version and ask whether it is good; or make twenty and ask the person to choose among them
+  all.
+- Post, publish, upload, send, comment, sign up or buy.
+- Invent a fact, a number, a quote, a user or a result, or show a product doing what it does not.
+- Use a real person's face, voice, words or work without their consent.
+- Redraft a piece the person sent back by polishing the same text. Ask what is off, then rebuild from
+  their answer (`references/voice.md` §critique).
+- Spend past the budget. When you reach it, stop and say so.

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

@@ -0,0 +1,159 @@
+# Voice, narration, music and sound
+
+**Measure what you can't hear.** An agent can't listen, so every take is checked by numbers:
+transcription against the script, words per second, pitch at line ends, loudness. A person must still
+listen before a voice or a bed becomes a default; a choice made on numbers alone is provisional.
+
+## Narration: whether to use one at all
+
+- **For personal and family content: no narrator by default.** A synthetic voice telling someone's own
+  memories reads as creepy, and it is easily in the wrong language. The person's own recorded words are
+  the voice. Otherwise use on-screen text, or ask them to record a 20 s line. A narrator is a style
+  someone chooses on purpose (a mock documentary, for fun).
+- **For product, teaching and promo pieces:** a voice-over is fine and often carries the cut. The
+  person's own voice beats any synthetic one.
+
+## Engines (as of Nov 2026)
+
+| Engine | Use | Notes |
+|---|---|---|
+| **MiniMax Speech 2.8 HD** (hosted) | default hosted narrator in any language | zero transcription errors in English, Swedish, Finnish and German, with commercial terms; about $0.03 per 30 s; 10 to 26 s a take; `<#0.5#>` pause markers; `speed 1.12` gives about 3.2 words/s; `emotion: happy` ended rising on 2 of 3 reads |
+| **ElevenLabs** (v3, multilingual v2) | most expressive; good in English, Swedish, German | **the free tier is non-commercial and needs attribution**, so business use needs a paid plan; v3 reads slowly (2.3 to 2.5 words/s, so speed it up) and differently every call |
+| **Qwen3-TTS 1.7B** (local, Apache-2.0) | free English and German, sounds really good | about real time on an Apple Silicon Mac, 4 to 5 GB; no Swedish or Finnish; a designed voice ignores gender (asked for male, got 208 Hz), so measure pitch before accepting |
+| **Kokoro 82M** (local, Apache-2.0) | free English promo voice-over | 4× real time, ONNX on Windows; flattest, runs sentences together; its English front-end pulls in GPL espeak-ng (a bundling question) |
+| Chatterbox (MIT) | cloning only | English into Finnish failed (84% word error rate) |
+| Out | OmniVoice (non-commercial weights; Nordic voices sound American), Apple system voices (personal licence only), Piper (GPL engine, robotic), Voxtral, F5, XTTS (non-commercial), Ming (artefacts, wrong gender) | |
+
+No local engine with a commercial licence passed Finnish (Nov 2026); hosted MiniMax, or ElevenLabs on a
+paid plan, is the clean path for Nordic languages.
+
+Engine traps (Aug to Oct 2026):
+- **ElevenLabs v3 reads the same text differently on every call,** including a rising end on a
+  statement (+2.2 semitones on one take, −3.1 on a plain re-read of the identical text). Generate several
+  readings and keep one that falls, then pin that file in the edit, or a cache keyed on (voice, text)
+  hands back whichever reading it got first.
+- **On ElevenLabs v3 through Replicate, audio tags (`[confident]`) are spoken as words,** and one
+  swallowed the words after it. Steer with `previous_text`, `stability` and re-reads. About $0.10 per
+  1,000 characters.
+- **Numbers are where voices fail:** one of three voices read "154" as "100 feet 4". Transcribe every take.
+- ElevenLabs' free plan refuses voice design through the API. Gemini TTS takes a plain-language
+  description in the prompt plus a prebuilt voice.
+- Plain-language style controls exist on some engines (Qwen3-TTS `style_instruction`, "like an excited
+  sports commentator"; MiniMax `emotion`; Chatterbox `exaggeration` and `cfg_weight`).
+
+## Pace and energy
+
+Measure words per second; "too slow" is the commonest note and it is a number. Engine defaults sit at
+narration pace (MiniMax default 2.65 words/s; at `speed 1.35`, 4.22; Chatterbox 3.18; Qwen3-TTS 2.87;
+Aug 2026). Live sports commentary runs about 3.5 to 5. **Speed is not energy:** a fast flat read is worse
+than a slow one. Reach for `speed` first, then for a style or emotion control.
+
+## What sounds machine-made
+
+- **A narrow pitch range** (6 to 9 semitones against 11 to 14 for expressive voices).
+- **Rising line ends,** which sound like questions. **Re-read the line; don't rewrite the script.**
+  Measure the tail pitch (a negative slope means it falls). A leading "And" tells the speaker more is
+  coming: removing it took one line from +1.3 to −7.5 semitones.
+- **Metronomic gaps** between sentences. Set pauses per line.
+- **Accent bleed** when cloning across languages.
+- **A dropped word that changes the meaning,** so transcribe every take.
+- Punctuation is a timing control: the same sentence measured 4.30 s with a full stop and 3.70 s with a
+  dash, and a vocative comma before a name cost 0.33 s. Apply it one line at a time by ear and don't sweep
+  it: the pause is wrong where a name interrupts a clause and right where it hands over a turn.
+
+**Measuring delivery.** Estimate f0 by autocorrelation per 40 ms frame over 70 to 330 Hz, voiced frames
+only, and report four numbers: the **tail** (the last ~350 ms in semitones against the line's median;
+negative falls), the **median** (how high the line sits; this is excitement), the **range** (10th to 90th
+percentile) and the loudness spread. A line called passive already had the widest range in its film; its
+median was low (119 Hz), and `emotion: surprised` on the same words gave 132 Hz. So a style or emotion
+control is the lever for energy and the median confirms it landed. This ranks takes of one sentence; it
+can't hear warmth, and a line can measure well and still be wrong.
+
+## Verifying speech
+
+- Transcribe every take with whisper large-v3-turbo (mlx-whisper on a Mac, about 3 to 6 s per 30 s;
+  whisper.cpp or faster-whisper elsewhere). Aim for a word error rate of 0 against the script.
+- **Pass the people's names and odd words as the initial prompt.** Without them, "Mira's asleep" came
+  back "mirrors asleep".
+- Pace: 3.1 to 3.3 words/s is promo pace, 2.3 to 2.8 is narration, and 3.9 is rushed.
+- **Whisper invents speech over music** (credits that were never there, loops over music-only tails)
+  and can't check sung words. Clip to the speech, or separate stems first.
+- Transcribe the **finished mix** again, not only the voice stem.
+- Dialogue a video model generated is checked the same way: extract the audio
+  (`ffmpeg -i shot.mp4 -vn -ac 1 -ar 16000 a.wav`), transcribe, and diff against the prompt's lines.
+
+## Music
+
+- **Local: ACE-Step 1.5** (MIT, outputs usable commercially). About a 10 GB download; 20 to 60 s a
+  track; hits the asked length and tempo and the quiet-intro-then-band arc. Turn on its "thinking"
+  model for lyrics. Its endings are cut, not composed, so fade the last 1.6 s. Reject takes that end
+  early or have a hole mid-song.
+- **Hosted:** MiniMax Music 2.5 (about $0.15, sings lyrics word for word); Lyria 2 (about $0.06,
+  instrumental, always 32.8 s, flat); ElevenLabs Music (about $0.58 for 70 s, pleasant, generic); Suno
+  through third-party APIs has a real arrangement but an unclear rights chain. Every hosted model
+  ignored "drums enter after the intro". MusicGen weights are non-commercial.
+- Tempo by cut: social about 104 bpm, product 110, scrapbook 92, calm 84. Choose music by what the
+  piece is ("day in the life", "emotional"), never "motivational".
+- The person's own track beats any generated one, if they have the rights to it.
+- Beat detection misreads fingerpicked triplets and finds nothing in some generated beds. Check the
+  number against the ear or the tempo you asked for.
+
+## Sound effects
+
+A generated sound needs an ear before it gets a level: four effects measured to a tenth of a decibel,
+and three were rejected on the first listen ("too violent", "a weird breath"). A level says whether a
+sound will sit in the mix, never whether it is the sound you asked for. **Build the way to hear it
+before wiring it in:** a short sampler, each sound for five seconds behind a card naming it, at its mix
+level. Ask what a model does with a class of request: two "moving air" sounds both came back breathy,
+and two rejections of the same shape are a property of the generator, not of a prompt.
+Put a sound on a visible action, peaking one frame after the picture. Some models pad every output
+to a fixed length with silence and don't put the content first (`stable-audio-open` returns 47.6 s
+whatever length is asked), so read the RMS envelope before trimming, or the trim grabs padding. **A rule
+about a model's output applies to every file it made,** including those already in the cut: a 30 s bed
+from the same model went silent for a third of a film when it was laid as one span.
+
+## Mixing and loudness
+
+- Voice in at about 0.5 s; bed ducked under the voice with `sidechaincompress` (about 12 dB for promo,
+  8 to 11 dB for a quiet film; attack 0.5 s, release 0.8 s). The bed must be at least as long as the
+  mix.
+- **Loudness:** −14 LUFS integrated for social, −16 to −18 for a quiet film, true peak −1.5 dBTP:
+  `loudnorm=I=-14:TP=-1.5:LRA=11`, AAC 192k, 48 kHz.
+- Measure level in one-second windows at several timecodes, not with `volumedetect` (it reports the
+  peak and hides a silent passage). `amix` divides by the number of inputs unless `normalize=0`: six
+  lines on one bed came out about 14 dB quiet while the peak still read fine. Use a `qsin` (equal-power)
+  crossfade between different material; a linear `tri` one dips 3 dB at the midpoint and is for a splice
+  of the same material.
+- **Not every measured gap is a defect.** Four time cards measured 25 dB below the film, and that
+  silence was the editorial beat that made "fifteen minutes later" read; three fixes for it were
+  rejected. Before repairing something in a piece already approved, ask whether it is load-bearing.
+  Moving a per-scene element to the master also lays it under every segment that had none: list them
+  before the move. When a fix is rejected twice, re-read the original note as a verdict on the first
+  attempt.
+
+## Reviewing voices
+
+Four or five candidates per language, **the same script**, one player each, the voice's name visible
+while it plays, loudness-matched (about −18 LUFS ± 1.5), and the voice heard **without** the bed first.
+Filter first by hard rules (speaks the language, licence fits the use, error rate at most 5%, no known
+artefact), then show the rest under "more voices". A pick records the candidates shown beside it,
+because "chose George over MiniMax and Alice" teaches more than "chose George".
+
+## Cloning a voice
+
+Only with the owner's own consent, verified live, purpose-bound and revocable. Never a child's voice,
+and never new words in a dead person's voice. The full rules are in `real-people.md`.
+
+**A synthetic speaker generated on camera** can be carried into later shots by cloning their voice out
+of the take: cut 3 to 4 s of one speaker and give it to a cloning engine as the reference (Chatterbox
+`audio_prompt` takes a data URI; MiniMax has voice cloning). Two generated commentators, each cloned from
+about 3.4 s of their own dialogue, said new lines correctly.
+- **Find the hand-off by a relative dip, not `silencedetect`.** Generated takes carry room tone, so the
+  gap never falls below an absolute floor and the detector reports one speech run, which also looks like
+  a correct single-speaker take. Measure loudness in 0.2 s windows and take the quietest window mid-clip
+  (one measured −45.5 dB against a −26.3 dB speaking median). Print the split and both reference
+  windows, and warn when the dip is under about 8 dB, because then the lines ran together. Cutting the
+  wrong side clones the wrong person, and it sounds like a perfectly working clone.
+- **A clone inherits its reference's tempo:** two takes of one prompt gave about 4.2 and about 3.1
+  words/s from the same lines, so picking the reference take picks the pace of every line. Measure it
+  rather than forcing pace afterwards, which reads fast and flat.

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

@@ -0,0 +1,66 @@
+# The brief
+
+Write the brief before anything is made, and keep it short: one screen. A strategy or growth skill
+that sends work here may already have written most of it; keep its fields and add what is missing.
+
+## Template
+
+```markdown
+---
+piece: <slug>
+purpose: brand | audience | teaching | product | personal
+status: open | working | picking | making | done
+created: <date>
+budget: <money cap> · <time>
+---
+# Brief: <what is being made, in plain words>
+
+**Next step it should cause:** <follow, reply, try it, sign up, share with one person, understand X>
+**Measured by:** <the link or tag, the count to read, and when to read it>
+**Reader:** <who, in their situation> · **meets it:** <where, on what device> · **awareness:** <stage>
+**The one idea:** <one sentence>
+**Channel and format:** <place, form, length/ratio, its rules and account requirements, with links>
+**Material:** <the person's own words (source), real screenshots/photos/recordings, real numbers (source)>
+**Voice:** <whose; where their voice notes and lessons are>
+**Sent back before:** <earlier versions and the reasons, in the person's words>
+**Make:** <how many hooks, angles, formats; which media>
+```
+
+## Purpose decides what good looks like
+
+| Purpose | Good means | The usual mistake |
+|---|---|---|
+| **Brand** (what people think of a person, company or product) | the same few things said, shown and repeated until boring; recognisable without the logo | a different style every time, or slogans with nothing behind them |
+| **Audience** (people who come back) | a series or a format people can expect; something they save, send or reply to | one-off posts; chasing reach over the people already there |
+| **Teaching** (someone understands or can do something) | the reader can do it after one read or watch; the picture carries the hard part | covering everything; abstraction without a worked example |
+| **Product** (someone tries, buys or understands a product) | the real product doing something surprising, then one clear next step | describing the product; internal numbers presented as the story |
+| **Personal** (family, friends, a memory) | one relationship, one small moment, a line that lands; it feels like them | polish that reads as an ad; a slideshow with a stock voice |
+
+## Awareness: where the reader already is
+
+Decide this before the first line (Schwartz, *Breakthrough Advertising*):
+
+| The reader | Open with |
+|---|---|
+| Most aware: knows it, wants it | the thing itself and the offer |
+| Product aware: knows it, unconvinced | a new proof, or what changed |
+| Solution aware: knows the result they want | that result, then how |
+| Problem aware: feels the problem, knows no fix | the problem in their words, then the way out |
+| Unaware | a story or situation they recognise; never the product |
+
+A stranger in a feed, a forum or a news site is problem aware at best. Someone browsing a directory
+of tools is solution aware. Only people who already know the person or product are product aware.
+
+## The next step and its measure
+
+Choose one next step per piece. Write down what counts as success before making anything, with the
+number you expect: views at 24 hours as a multiple of the person's normal, clicks, replies, sign-ups
+in the week after, or for personal pieces whether it was shared and with whom. Without a prediction
+there is nothing to learn from the result (`copy.md` §after).
+
+## When the request is vague
+
+"Make something for LinkedIn about X" is not a brief. Fill in what you can from the project (its
+positioning, earlier pieces, the person's notes) and then ask the person **one** question that only
+they can answer, about the material, not about the craft. Ask *"what happened the first time you
+saw it work?"*, never *"what should the post say?"*.

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

@@ -0,0 +1,144 @@
+# Channels: each place's form, rules and what it rewards
+
+Each channel gets its own piece. A directory tagline, a forum post, a launch page, a newsletter and
+a short clip are written separately, in that place's form. **Read the place's own rules before
+drafting, and link them in the brief.** Rules change, so the notes below are a starting point, not a
+substitute for reading them. Dates say when a fact was checked.
+
+## Before any community post: the account
+
+A community's requirements on the **account** are rules too, and a post that misses one is removed
+unread. Many subreddits and forums set a minimum karma (overall or earned in that community), account
+age or self-promotion ratio, often enforced by a bot and stated only in the sidebar, wiki or a pinned
+post. Read all of them and check the person's account against each, in their signed-in browser. If the
+account falls short, **don't post yet**. Earn the standing inside the rules first, with real comments
+in the person's own words. A removed post stays removed: never propose asking moderators to approve it
+or to waive a rule.
+
+Look at what the community is talking about that day. A post about running many AI sessions, made
+the evening after a thread about usage limits blowing up, got answered with "dude loves wasting tokens".
+
+## Places
+
+**Reddit.** Posting your own work is allowed in reason, and each subreddit's own rules decide what
+counts as promotion (flair, a weekly thread, account age, karma). The "9:1 rule" isn't in Reddit's
+current pages, so treat it as folklore. What wins in maker-friendly subs: a short plain first-person
+title in the shape *"I had problem X, so I made Y do Z"*, with no brand name in front; a short body
+(the top maker posts run about eight short lines); a striking real visual or clip; the maker says in
+the first line that they made it and whether it is free; it names the alternatives and how it
+differs; it ends on a genuine question. Links in the first comment when the sub filters new domains in
+bodies; no tracking parameters where referral links are banned. Be ready in the comments for "is this
+an ad?", "how is this different from X?" and the cost.
+
+**Hacker News, Show HN.** For something people can try, ideally without sign-up; not a landing page or
+a blog post. The title is `Show HN: <name> – <what it is, in words HN already uses>`, with no
+superlatives or capitals for emphasis. The maker posts it and stays to answer. **Show HN bans generated
+text in posts and comments**, so the person writes their own; you can prepare notes for them (what
+they tried first and why it fell short, how this differs from named alternatives, what is rough, the
+likely questions). Never ask for votes.
+
+**Product Hunt.** A tagline of 60 characters or fewer, no gimmicks; a gallery whose first image works
+on its own; the maker's first comment tells the story, who it is for and what is rough, and asks for
+feedback, never votes.
+
+**A directory of tools, plugins or apps.** Readers are solution aware and comparing. The first
+sentence says what it does, for whom, and how it differs from the alternative, in the directory's own
+fields and limits.
+
+**Building in public** (progress posts on any channel). Share a decision, a mistake or a lesson, each
+tied to something concrete that happened. A dump of metrics with no lesson reads as a status report and
+invites "so what?"; a number belongs only when it is the lesson.
+
+**A blog post.** Something a stranger can use even if they never try the product: a lesson, a method,
+a mistake and what fixed it. The product comes in as the way the author did it. Plan the pictures with
+the words (`copy.md` §5). For search, read `search.md`. Before it goes: every link opens, the title
+and subtitle are set, and there is a one-to-two-sentence meta description. When a post is excerpted
+elsewhere (a forum, a professional network, a short post), each excerpt is written for that place and
+links back to the original.
+
+**A newsletter** (Substack, Beehiiv, Ghost, email). This is the highest-intent channel and the one the
+person owns. Frameworks, breakdowns and real stories, with no filler. Most reach often comes from
+forwarding person to person, so a piece someone would send a colleague does best. Avoid holiday weeks
+for anything whose next step is a work action.
+- *Substack mechanics, when preparing a draft through its API from a signed-in browser* (read Jul to
+  Oct 2026):
+  - **The editor's ProseMirror schema is strict,** and a draft that saves through the API can still open
+    blank ("Failed to parse JSON for post"). Copy the shape of an existing draft
+    (`GET /api/v1/drafts/<id>`): the doc has no `attrs`; paragraphs and headings carry
+    `attrs:{textAlign:null}` (headings also `level`); lists are `bullet_list` → `list_item` →
+    `paragraph`; a link mark carries `href`, `target:'_blank'`, `rel:'noopener noreferrer nofollow'` and
+    `class:null`; bold and italic are `strong` and `em`. Open the draft in the editor before calling it done.
+  - **The cover field only drives the social preview and feed thumbnail.** A picture shown at the top of
+    the post must also be the body's first node, a `captionedImage` (copy its exact shape from a post that
+    has one; its width and height are the display box, scaled to 1456 px wide). Upload images with
+    `POST /api/v1/image` (a data URI) from a script over CDP, since the payload is too big for a one-line
+    eval. The cover field wants the signed CDN form of the URL, whose signature can be read from a
+    published page's `og:image`.
+  - **An open editor tab saves its copy back over an API update,** minutes or hours later and from any
+    device. Before an update, find every tab on that post's editor (the person's own too) and navigate it
+    away; re-verify about 30 s after pushing, not only at once. If the live body matches an earlier
+    version exactly, it was this, not a failed write. `GET /api/v1/drafts/<id>/versions` lists every save
+    with time, user and content hash: use it whenever a draft "changed by itself".
+  - **Never rely on Substack's scheduled send;** a stale tab's save went out by email on a schedule once,
+    and an emailed copy can't be fixed. Snapshot the approved body, and at publish time compare the
+    draft with it (block sequence and every paragraph's text). On any mismatch, stop and tell the person.
+    Publish only when the person says so, then compare the public post's `body_html` with the snapshot.
+  - **A published post is a separate snapshot:** a `PUT` to the draft changes nothing live. Use the
+    editor's Update → Update now, which sends no second email; never re-POST publish.
+  - Authorship reads correctly from `postBylines`, not `draft_bylines` (empty even when right). The editor
+    page is heavy enough that evals time out; do API work from a light tab on the dashboard. Sign-in is a
+    one-time code: read the newest one, scoped to the address it was sent to, and switch accounts with
+    `change_user=true` (plain sign-in keeps the current session). A prepublish `MISSING_SUBSCRIBE_CTA`
+    offers to insert subscribe widgets.
+
+**LinkedIn.** Professional readers; a hook that gets to its purpose at once, often with an opinion.
+200 to 500 words, short paragraphs, the person's real story or framework. Plain register works,
+and the person's own speech register beats "professional" polish. Don't open by diagnosing a
+stranger's organisation ("your team isn't X-limited, it's Y-limited") before you have any credibility
+with them: lead with what surprised you and the receipts, and let the diagnosis come as the answer to
+the question the reader asks next. Close with an invitation, not a call to action. Links in a post are commonly believed to reduce reach. If that matters, test it.
+- *Mechanics:* uploads can report failure and land anyway, and a message compose box can still be
+  bound to the previous conversation. Check which thread you are in, and read the result, before
+  assuming anything.
+
+**X.** Plain contrarian one-liners and predictions; a thread only when every post earns its place.
+
+**Instagram (feed, carousel, Reels).** It distributes on **sends** (shares in DMs) and watch time. At
+most five hashtags; keywords in the caption and the on-screen text. Carousels save when the list
+overflows and each slide carries proof.
+
+**TikTok and Shorts.** The first two seconds decide; a contrarian or surprising line within four
+seconds; native, phone-shot, talking or showing.
+
+**YouTube.** Story-driven teaching; the title and thumbnail are one promise (`stills.md`). Most channels
+see a click-through rate of 2 to 10% (YouTube Help). Compare videos with each other by traffic source,
+not against a universal number. Use YouTube's Test & Compare to test thumbnails, not taste.
+
+**Email to many** (a launch note, an update). One reader in mind, one next step, a subject that says
+what it is. A one-to-one cold email is sales work and belongs to whatever relationship or sales skill
+the project has, not here.
+
+**Answer engines** (ChatGPT, Claude, Perplexity, Copilot, Google's AI answers): see `search.md`.
+
+## Sizes and lengths
+
+| Format | Size | Notes |
+|---|---|---|
+| Feed image / carousel slide (Instagram, LinkedIn) | 1080 × 1350 (4:5) | the tallest that shows in feed |
+| Square | 1080 × 1080 | |
+| Story / Reel / Short / TikTok | 1080 × 1920 (9:16) | keep text inside the safe band, about 250 px clear top and bottom |
+| YouTube thumbnail | 1280 × 720 | readable at phone size |
+| Reddit or link lead image | 1200 × 900 or 1200 × 630 | shown smaller in feed; test at about 400 px wide |
+| Open Graph / social preview | 1200 × 630 | |
+| Product Hunt gallery | 1270 × 760 | the first image must work alone |
+| Video for chat apps (WhatsApp) | H.264 720p, at most about 15.5 MB | `+faststart` |
+| Video for a TV | landscape 1080p HEVC | from the same edit as the portrait cut; pan across faces, never letterbox |
+| Video for a digital photo frame | silent, captioned, 30 s or less | frames play without sound |
+| Short-form clip length | 15 to 45 s | the payoff before 80% of the runtime |
+
+## Never
+
+- Post, upload, publish or comment. Prepare it, open it in the person's browser, and let them press
+  the button.
+- Reuse one piece unchanged across channels.
+- Write *upvote*, *please share* or *support us*, or hide that the person made it.