editorbrain 0.31.0 → 0.32.0

package/README.md

@@ -5,13 +5,13 @@ Editorial references, brand context and portable video projects for Claude Code
 Inspect the CLI without configuring your agent:
 
 ```sh
-npx editorbrain@0.31.0 help
+npx editorbrain@0.32.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.31.0
+npm install -g editorbrain@0.32.0
 editorbrain login --url https://api.editorbrain.com
 editorbrain status --url https://api.editorbrain.com
 editorbrain projects list
@@ -19,7 +19,7 @@ editorbrain pull --project YOUR_PROJECT_ID --dir ./my-videos --url https://api.e
 editorbrain skill install --dir ./my-videos --agent both
 ```
 
-Create an account and follow connection instructions at https://editorbrain.com/app/settings. Login requires browser consent. Pull downloads only the selected project and its brand/style context, remembers the selection, and leaves reference evidence remote. Use `documents list/get` for additional saved documents; `pull --all` is an explicit full-workspace operation. Skills install locally: editorbrain handles context and library access; editorbrain-motion is loaded only for animation work. Both inherit the project identity and preferences. MCP authentication is configured separately. Preserve existing customized instructions and inspect installation conflicts. The package contains the CLI and skill documentation, not private library content or customer credentials. Editing and rendering use your agent's external tools.
+Create an account and follow connection instructions at https://editorbrain.com/app/settings. Login requires browser consent. Pull downloads only the selected project and its brand/style context, remembers the selection, and leaves reference evidence remote. Use `documents list/get` for additional saved documents; `pull --all` is an explicit full-workspace operation. Skills install locally: editorbrain handles context and library access; editorbrain-motion is loaded only for animation work; editorbrain-formats only for the selected editorial structure. All inherit the project identity and preferences. MCP authentication is configured separately. Preserve existing customized instructions and inspect installation conflicts. The package contains the CLI and skill documentation, not private library content or customer credentials. Editing and rendering use your agent's external tools.
 
 ## Local production checks (0.12+)
 

package/bin/editorbrain.mjs

@@ -58348,6 +58348,39 @@ var VERIFIED_GUIDANCE_RELEASES = [
       "editorbrain/references/style-creator.md": "1b1bc289a5bc308cbbf7f4d699de2933b8934733a2b69b3e98fb1b7420d986f2",
       "editorbrain/references/workspace-files.md": "cd3006a7cc4f04ff5dfeb1bd901a21c53455017aa7d19fcde9a6e26f1fbbd5b6"
     }
+  },
+  {
+    "version": "0.31.0",
+    "archiveSha256": "34a074361f35b099d673e4f310b566d359bc18ec6f326b055c4e0ce811f07c97",
+    "files": {
+      "editorbrain/AGENTS.md": "2361aaa3202d3f4ea9e941684fbda1a84d9711389cca89f7f6cd3ae03b7ab6d0",
+      "editorbrain/references/audio-production.md": "038504d738db98939aeed14407b15561e4f82c650aace7eb545e77cdffd8dadb",
+      "editorbrain-motion/references/authored-scenes.md": "11109dcd35ab7138fdc18e54605885bb26d9e948f12221e18dea4038987dede2",
+      "editorbrain/references/cli-mcp.md": "3a83731d73dd09b55ee5a250bebd950b5a0daedc2b1c3af23bfc6c36f748d793",
+      "editorbrain-motion/references/code-motion.md": "50382a797adc1e1596086e2408e81ee75ceb6730ca409be9c884646db643a7cd",
+      "editorbrain-motion/references/component-library.md": "e4593622ebe371bba1b1c62f698c6709c36a8d01ddce4a07d40534fca44b797e",
+      "editorbrain/references/editorial-evidence.md": "caf72365b3e7492a62d96b39cd17031fa7c961671ce32bc4649420d8a353a026",
+      "editorbrain/references/first-edit.md": "d71271ab32c6432cce01316917b4504f15411ea59511566a1f6169ac6d09723c",
+      "editorbrain-motion/references/generated-motion.md": "a8d214b53c15f742658abd84f03b768fa2821f8cde94f50aab82a3759a30b36b",
+      "editorbrain/references/integrations.md": "a3500dd79c71ab3ee80a865bb5bf8c94287efb933e07d577738891e276a819a0",
+      "editorbrain/references/local-production.md": "2d170bb217854eda7581f64d8342fffe3b56234bbe56b2715fa93eb3210e6354",
+      "editorbrain/references/media-preferences.md": "d1b92b181fbc226c8d3fda762726dd413944175768651fbfb8200eae44fb2ec8",
+      "editorbrain/references/memory-and-review.md": "2a89d6fc4737b750a380c69630d6fd4f4132aed27656b92e8f0c5748887b70ae",
+      "editorbrain-motion/references/motion-craft.md": "adba1b0cbb3c6327a7665857b0a6d144f97dc843464ccf154d3f76ee3ada905d",
+      "editorbrain/references/motion-review.md": "0fb09a2d61ecd13114ced5cca5daa4580a922cf7d7b3f8698077ceb0e96da6f0",
+      "editorbrain/references/onboarding.md": "875d1b9049c4663780f993c2843528c531a51d6b51380b08ed77d82f618185fb",
+      "editorbrain/references/production-and-review.md": "50f10a98a4f3709a5a585f58e4154f33d6d883b218cd25f3abd72eccc43b15a7",
+      "editorbrain/references/production-continuity.md": "c4b346c9634f3d1ef63b24a97d178e0253c2e45d53f6934076a5417e66e34d9b",
+      "editorbrain/references/real-media.md": "106bee5a34641d53f021ead5d41630d473c2bfc98e4f7ee5500dae837e2e45bb",
+      "editorbrain/references/search-brief.md": "ea2a9c2d5a5cf685c1e5918366901ef2589c4d79aaa78a0dd31e97d6fed42b7b",
+      "editorbrain/references/sfx-library.md": "fa0b02c8765988257e46e16298ecca9cdb0e338a863915e29f831162e237eac4",
+      "editorbrain-motion/SKILL.md": "86617d39341d7325d613b877838258f40f05b4286301dacf8e1ec85ccd502aab",
+      "editorbrain/SKILL.md": "d53070052608fc2535af7cb51bcac2c10097b289450958ca7372cab3fb8364a9",
+      "editorbrain/references/storage-and-previews.md": "8a3057f1c1a2a1e1cd32028059dc897a8461da38c36e812fbd24943d3740b4d5",
+      "editorbrain/references/studio.md": "7a84e43bd72f8590d1a91c7d1bc5f6b60678c1c8eba6523b51b99243e22a1322",
+      "editorbrain/references/style-creator.md": "1b1bc289a5bc308cbbf7f4d699de2933b8934733a2b69b3e98fb1b7420d986f2",
+      "editorbrain/references/workspace-files.md": "18462e7b66ba6204770c654e4a2f7e505c343319671a0447aa55c59f0b9096ec"
+    }
   }
 ];
 function isVerifiedHistoricalGuidance(skillName, relativePath, sha2562) {
@@ -58356,7 +58389,7 @@ function isVerifiedHistoricalGuidance(skillName, relativePath, sha2562) {
 }
 
 // packages/cli/src/agent-guidance.ts
-var BUNDLED_SKILLS = ["editorbrain", "editorbrain-motion"];
+var BUNDLED_SKILLS = ["editorbrain", "editorbrain-motion", "editorbrain-formats"];
 var previousSkillHashes = { "SKILL.md": ["9df2c89deeec30ddf556c359027efe1d90e6b4e9c08717cd8827e210b38a187f", "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9", "1e2fff65a1b303b18b2d65156bef6eb2439a19d77ba2a25b37bcb1819ff009e3", "dacce1c4127f4281df6f7e1681e243444bb6f8a8e74b829e52ee0108c6672348", "09740ab4b275eada65b5040ae6000104ff39094f534a2784e67feb2afc2a59b3", "f18269ad5504fff8a4fc522d463483261f5041e56cb7f1081f9614bc67e0d96f", "5779a28879313070b0d819771ac967d4a133cff1c3dbda2ec44b4dd2abcb17d1", "30f1e64622e70552a1a6129cacc646f56b09b3d7a1fd3f5bf22299bc6bfd0d1e", "6975d917226f75ad55c67543bf7f1c5ef18f4cfe43426c69400c56c1ed497db3", "0029d5da60efc14759a66c4e3299d5da09c4ab8e3f255fe5da9990699c42f3e4", "09d5441cba061349b43b36ab683d966f772d0cec94698823e32c35f2475d287e"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "1b07de01698a0040b47ea0eddb1b017f70a69e81acd0bf9710647ca5e02f5125", "b5ee3439ff974c668755816149fab76899d7ad9266f63978b30fbc9b7d2cd640", "bacedb7bdedab5abe75c9601717cfdb05a96208fa2e2a42af878e2dfd2ae4251", "ea3b473179857ccc07e9e4f21a6ede9e0906a09e495f4a051069d15aee1556cd", "faa2bba99ae3023be7f588d02177a4abf583d3a8a65f617b8cff7a3ceed09dfc", "83c75394bc7eaab6662a76d89339361e836cc1a988237720eeeacdd6b62e726f", "b685cb7ff21d5bfe19d96ce0139c17b7eb014b7ecda8ec5321558b0004bfdc71", "9da0b84e166ad3799dd0c644adaa3ce8727f383e5571b0a212c3d34f5c05ab40", "12f5dce738eb974ddd96f4bd00d8de5be236a54dbb20720f6f4ab455bcc319d9"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "666082653efc000f8a7cc5f1836c80bbdda5f0f57cdbbdcb393f2b84aeb93a01", "78b737796a8685b1135e0acb91b620c51845b62e31dba04eb51dd9dd38b41008", "8b2e01bfd937237919f5ade794eed01dc6e32b556ede9de3a0ccc28cbdd988d1", "ca88b2816a795a5ebe834074b178469367634b80ad837e3697182ea585af1c05", "490daf154b428b536d0a6f590030c854b2fc8ca6adb995c6ecd5a162f85e471e", "9f98affecd69752c17f52fb51ae74b26a1cadea5919b8b74b7865a20661c4418", "19fc85e92cef203f4162e2bfb2dd2df8ef90472bc8f81dfb568b65a714335ff9", "f697c525a32d8ed6c0752d833cb98cca8b9aec9eadf456e178dfbc9fc246c58c", "d2a3dd980fb712110861ac9802288bb025ac5ea0055f1e56d70d649412a4d733", "955d60d1be71d0eb134ae9fc35a771d41303fae8fe63daa99bfce514a6522e14"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3", "4a4035b87a6c024b419847ab8592bddfeb9b2d9c184f65880c47d661f0bb250e", "c3669af0717a5fafbf7cc8b01bd66f74d4c82028715323a870a1298d25250d5e"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf", "97053b092e0ff36e3cfb764095fcb4a4fca94e722567e774b53bc118279f40e5", "70fc660e7ed3d70c16c33c62c8e0399b99c3251808f093ef3d4ea5e8d39e4c8a", "28c62c1e28842142607f5168ee79b18fd797900dd66dd9ac5eb3cfcf8a09f781", "b86eae85cf86dbf4409b10f4d8df1f1649fc408ce1a240f7cf26d5bb69aabfd1", "fc65f343e50b91327653bdc5d94f35af9c86c097bb46810b4b2f7c9a1c200166", "8a650485bc4f26bbebf6d6a66957bdea87b156632e52a27e9becc194b003a9fc"], "references/first-edit.md": ["cb1e9d3272b2b22ae095aed02e33067c646da48e7b64cf71ff81197f6e67b673", "5a02253d9907f5e6705304565da7b2d1787e84ae17616414b295a8526ec3e4a5", "586b1f18bab01ad6b2bb0efd95cfdc8f8002ecfd022ae91021779ab1d5e432c9"], "references/memory-and-review.md": ["51a274e522270f1fc295d0c0b9a1c23672ce01abea097c2499c9a8db56c0c289"], "references/search-brief.md": ["137203383a7873593136428520f5f9cd6ce1ab6cfeab365c277175786eba3ab3", "df93154562bb89a9f22d31260c17406565f5f308c407643c85d15e528ef2c086", "a472eeb61a2a60172d5cdb71f80be3d18f59e248028ab107b6cd1b68535ff588"], "references/style-creator.md": ["1b1bc289a5bc308cbbf7f4d699de2933b8934733a2b69b3e98fb1b7420d986f2"], "references/local-production.md": ["0a13c65cd60e40ba703095f5e33a1ea66433323b38345c2034fb73c602c438ee"], "references/integrations.md": ["a3500dd79c71ab3ee80a865bb5bf8c94287efb933e07d577738891e276a819a0"], "references/media-preferences.md": ["970b97fbd55b8e9e05fd7e51b4a953cd1b96b9bee7830382aa7514f1b240b3aa", "481c643a5e6516413a6cae970b5170573c981d0effd7d4e146c5cd07c0ee3b1f", "8f11e1956ed06ab73ba58d8c880f0d2292eb76829b07d2de2eaaed1965885158", "e94bc13c05ffd57eceecc4ceaa42df2b83904c12f8c552e161c98f13e6427e5b", "00e50c6231a917639c8d9eb39bff61b0b90e3a1886a4d4684ef6d85fa754e87c"] };
 var destinations = {
   codex: { directory: ".agents/skills/editorbrain", entryPoint: "AGENTS.md" },
@@ -58364,6 +58397,7 @@ var destinations = {
 };
 var previousHashesBySkill = {
   editorbrain: previousSkillHashes,
+  "editorbrain-formats": {},
   "editorbrain-motion": { "references/code-motion.md": ["9c9bd4c7c6ef8c607e4de6198408e4a49e6d6c4deda681dd7aadada1e46c1a80", "dc7446d5349fd107d6c722fcf62ad6ad6dfc7b9a1d4829c0adfbc00e41a9c8a5", "08fd07e904424a98ec4dd68732d55e15fa9f6edffe14e4ee0241f0483acb82be"], "references/generated-motion.md": ["a8d214b53c15f742658abd84f03b768fa2821f8cde94f50aab82a3759a30b36b"], "SKILL.md": ["f732ba6c896e01a844df92a353a77d18da1be7f09ce557bf7a543e3066a667d2", "0920c79979dc029fae3526a565e5eab75d5b7f1f51c369fb7ef0d652b95876eb", "0b6f6e6990528579fdff4275a2bcf0b0fe6f0f2de59ae84d0f57b81a07185cec"], "references/component-library.md": ["ad7142f9bbd52903b61f401104dfdbb430535f358946e58788f9f740d8f44b56", "7ff9e079116c410be0dc80fb470e79226c380b6fcc7d6eb72cb94443dd8915a4", "c2ab96ee61dc1e9480cb6f7fd160c016b35ff946e3d8ffe31267d127718482c8", "fea1fb710d23830c3ed14c3e4bed7bc53540ae2e2e662b74fe6eb6307b010d28"] }
 };
 function installedSkillDirectory(agent, skillName = "editorbrain") {
@@ -58421,11 +58455,11 @@ async function prepareAgentGuidance(root, agent = "both", sourceDirectory, compa
   root = await ensureRoot(root);
   parseAgentTarget(agent);
   const agents = agent === "both" ? ["codex", "claude"] : [agent];
-  const companions = companionSources ?? (sourceDirectory === void 0 ? {
-    "editorbrain-motion": bundledSkillDirectory(void 0, "editorbrain-motion")
-  } : {});
+  const companions = companionSources ?? (sourceDirectory === void 0 ? Object.fromEntries(
+    BUNDLED_SKILLS.filter((name) => name !== "editorbrain").map((name) => [name, bundledSkillDirectory(void 0, name)])
+  ) : {});
   for (const name of Object.keys(companions)) {
-    if (name !== "editorbrain-motion") throw new Error(`Unknown companion skill: ${name}`);
+    if (name === "editorbrain" || !BUNDLED_SKILLS.includes(name)) throw new Error(`Unknown companion skill: ${name}`);
   }
   const sources = /* @__PURE__ */ new Map([
     ["editorbrain", await loadSkill(sourceDirectory ?? bundledSkillDirectory())]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editorbrain",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "EditorBrain editorial knowledge, portable workspaces and skills for AI video agents",
   "type": "module",
   "license": "UNLICENSED",

package/skill/editorbrain/SKILL.md

@@ -28,7 +28,7 @@ For factual subjects or real demonstrations, inspect authentic footage/images fr
 
 ## Specialized work, loaded when needed
 
-Use the decision ownership in [the shared contract](AGENTS.md#decision-ownership): montage, media, motion, sound and review share one direction. For animated scenes, read [editorbrain-motion](../editorbrain-motion/SKILL.md) with the active project and resolved context. Ordinary cuts, static graphics or sync/install tasks need no motion skill. User memory belongs in scoped brand/style/project files; shared guides describe methods and examples supply evidence.
+Use the decision ownership in [the shared contract](AGENTS.md#decision-ownership): montage, media, motion, sound and review share one direction. For animated scenes, read [editorbrain-motion](../editorbrain-motion/SKILL.md) with the active project and resolved context. Ordinary cuts, static graphics or sync/install tasks need no motion skill. When the edit follows a recognizable format (for example a numbered tutorial, or a reference whose structure the user wants replicated), read [editorbrain-formats](../editorbrain-formats/SKILL.md) for its structure and sync rules; identity still comes from the resolved brand and style. User memory belongs in scoped brand/style/project files; shared guides describe methods and examples supply evidence.
 
 For built-in transcription, image generation or narration, read [EditorBrain Studio](references/studio.md) only when needed. Discover availability first; quote and obtain an authorized budget before spending. Local MP4 preparation, durable job recovery and private result retrieval are covered there.
 

package/skill/editorbrain/references/cli-mcp.md

@@ -41,7 +41,7 @@ editorbrain skill install --dir ./my-videos --agent both
 
 If unauthenticated, `editorbrain login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: register the MCP URL without a bearer header and authorize through the host’s OAuth login. Choose the same workspace in the consent page. Existing bearer-key connections remain compatible; do not overwrite one during setup.
 
-Skill installation is offline and independent of login. CLI 0.19+ installs sibling `editorbrain/` and `editorbrain-motion/` skills under `.agents/skills/` for Codex and `.claude/skills/` for Claude. Read the core first; load motion only for animated scenes. Open the target folder in the agent and explicitly follow the returned instruction path if automatic discovery has not refreshed. The core directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
+Skill installation is offline and independent of login. CLI 0.19+ installs sibling `editorbrain/` and `editorbrain-motion/` skills under `.agents/skills/` for Codex and `.claude/skills/` for Claude; later versions add `editorbrain-formats/`. Read the core first; load motion only for animated scenes and formats only when replicating a format's structure. Open the target folder in the agent and explicitly follow the returned instruction path if automatic discovery has not refreshed. The core directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
 
 Existing root `AGENTS.md`/`CLAUDE.md` are preserved. Read the install result's instruction paths and conflict reports. A preserved root guide does not mean the native skill failed; a conflicting existing skill needs a deliberate merge, not an overwrite. Do not replace the user's custom instructions to finish setup.
 

package/skill/editorbrain/references/workspace-files.md

@@ -11,8 +11,10 @@ AGENTS.md                         Codex entry point (existing instructions prese
 CLAUDE.md                         Claude Code entry point (existing instructions preserved)
 .agents/skills/editorbrain/      Codex skill, contract and references
 .agents/skills/editorbrain-motion/  Codex animation skill, loaded when animating
+.agents/skills/editorbrain-formats/ Codex format guides, loaded when replicating a format
 .claude/skills/editorbrain/      Claude Code skill, contract and references
 .claude/skills/editorbrain-motion/  Claude Code animation skill, loaded when animating
+.claude/skills/editorbrain-formats/ Claude Code format guides, loaded when replicating a format
 .editorbrain/
   brands/<brand-id>/
     brand.md                      Identity, audience, constraints
@@ -90,7 +92,7 @@ Updating the global CLI does not replace skills already copied into a project. R
 
 Known unmodified release files can be upgraded; unrecognized differences are preserved as conflicts. Prepare the new version in a separate temporary directory, compare it with the project's installed copy, and merge changes while preserving custom instructions. Do not assume a successful exit means all guidance was upgraded. Root `AGENTS.md`/`CLAUDE.md` remain user-owned: if already present, use the returned skill path explicitly, or add a narrowly scoped pointer when the user asks to integrate it. There is no automatic global installation for every future project.
 
-CLI 0.19+ installs the core and `editorbrain-motion` together for the selected agents. `readInstructions` points to the core; its `onDemandSkills` lists specialized entry points to read only for matching tasks. Installation makes files discoverable, not proof the host refreshed its skill catalog or the agent read them. Follow the explicit path if discovery has not refreshed. Shared skill files hold production methods, never the customer's palette, personal integrations or style memory.
+CLI 0.19+ installs the core and `editorbrain-motion` together for the selected agents; later versions add `editorbrain-formats`. `readInstructions` points to the core; its `onDemandSkills` lists specialized entry points to read only for matching tasks. Installation makes files discoverable, not proof the host refreshed its skill catalog or the agent read them. Follow the explicit path if discovery has not refreshed. Shared skill files hold production methods, never the customer's palette, personal integrations or style memory.
 
 
 ## Review preference

package/skill/editorbrain-formats/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: editorbrain-formats
+description: >-
+  Replicate a proven video format's structure in an EditorBrain edit, such as a
+  numbered tutorial or demonstration (hook promise, numbered steps, a visible result
+  for each step, presenter returns, CTA). Use when the user names a format or
+  editorial family, asks to follow a reference's structure, or the material is a
+  step-by-step list. Formats define structure, sync and pacing only; identity comes
+  from the user's resolved brand and style.
+---
+
+# EditorBrain Formats
+
+A format guide describes **how a kind of video is built**: its beats, what each beat must make the viewer understand, how entrances sync to speech and how to review it. It never describes how the video looks. Every user has a different identity, niche, footage and taste.
+
+## Reuse the active contract
+
+Read the sibling [EditorBrain contract](../editorbrain/AGENTS.md) once in the active context, including when this skill activates directly. Reuse it if already loaded. Discover the active project and read its brief, direction, brand, style and output profile; use [first edit](../editorbrain/references/first-edit.md) if no workspace is ready. Use `resolve_project` / `editorbrain resolve <id>` and `check_workflow` / `editorbrain workflow check` for tokens, `creativeDirection`, review mode, media/audio preferences and safe areas. Reuse valid results already obtained.
+
+## What a format owns and what it never owns
+
+| A format guide owns | Always resolved from the user's context |
+|---|---|
+| Beat order and each beat's function | Colors, fonts, logos, shapes, textures |
+| Sync anchors (which spoken word triggers what) | Caption design and caption rules |
+| Recurring layout grammar between beats | Sound bank, SFX taste, music, loudness |
+| Failure modes and review checks for this structure | Niche examples, copy tone, language |
+| Fit and misfit criteria | Output size, fps and safe areas |
+
+Map each visual **role** a format names (headline, numeral, step label, instruction surface, emphasis, background) to resolved tokens and `design.md`. When a role has no token, decide it from the brand's existing choices, record the decision in `direction.md` and keep it consistent across the video. Never copy colors, fonts or decorations from a reference, a pilot or this guide's examples. Authentic material (footage, screenshots, product colors, real logos) keeps its own appearance.
+
+When `creativeDirection` is `automatic` and the identity leaves room, choose freely. When the review mode asks for directions or a sample, or the user is unsure of their look, show the format's key states (hook, one chapter, one result, close) rendered on the user's real frames in 2–3 identity options before the full edit. Do this only when review mode or the user calls for it; `direct` mode proceeds.
+
+## Choose and adapt a format
+
+A format is an editorial family, not a template. Choose it after inspecting the material, only when its fit criteria hold. Distinguish faithful transfer, adaptation and borrowed techniques, as the contract requires. Search the library for edited examples of the family with `search_from_brief` (describe the structure and communicative need along with relevant subject context) and inspect what you retrieve. A matching structure does not certify that every device fits this video.
+
+The number of steps, durations, demo mechanisms and the headline's wording come from the user's script and footage. Values in a guide are measured pilot evidence, not defaults.
+
+## Available formats
+
+| Format | Use when | Guide |
+|---|---|---|
+| Numbered tutorial / demonstration | The voice teaches N discrete steps, tips or instructions and each one can be shown working | [numbered tutorial](references/numbered-tutorial.md) |
+
+Read only the guide you will use. For animated beats, also use the sibling [motion skill](../editorbrain-motion/SKILL.md); for authentic results, follow [real media](../editorbrain/references/real-media.md).
+
+## Adding a format
+
+Each new guide uses the same sections: fit and misfit, skeleton with each beat's function, sync anchors, adaptation rules, identity roles, failure modes, review checklist, and evidence status (`concept`, `implemented`, `user-approved pilot`, `transfer tested`). Add it to the table above. Keep one user's taste out of the shared guide: personal choices belong in that user's brand or style files.

package/skill/editorbrain-formats/references/numbered-tutorial.md

@@ -0,0 +1,135 @@
+# Format: numbered tutorial / demonstration
+
+A presenter promises a fixed number of steps, then teaches them one at a time. Each step is named, its instruction is shown where it would be used, and a visible result proves it works. The viewer always knows which step they are on and how many remain.
+
+Evidence status: one implemented, user-approved pilot (talking-head creator, software instructions, Spanish, vertical). Transfer to other niches and layouts is untested; record the first adaptation's review.
+
+## Fit
+
+Use when:
+
+- the voice teaches N discrete steps, tips, rules or instructions, in order;
+- each step can be **shown**: an on-screen action, a setting, a prompt, a technique, a before/after or a product doing something;
+- there is a presenter or a voice that can carry a short hook and transitions.
+
+Niche examples: recipe steps, workout cues, makeup techniques, software prompts, editing tricks, sales scripts, study methods, home repairs.
+
+Avoid or adapt when:
+
+- the steps cannot be visualized; a talking-head list then needs another format;
+- the material is one continuous story or opinion;
+- the count is vague. Never invent a number the voice does not state.
+
+## Skeleton
+
+| Beat | Function | What must be on screen |
+|---|---|---|
+| Hook | State the pain or promise and the count | Presenter plus a designed headline lockup; the count appears when it is spoken |
+| Chapter k (repeat N times) | Name step k and show its instruction | Large step numeral, step name, progress (k of N), and the instruction shown on the surface where it is used |
+| Result k | Prove step k works | A demonstration that performs what the voice says, synchronized to it |
+| Presenter return | Explain, react or bridge | The presenter when the function changes (opinion, why it matters, transition); not on a quota |
+| CTA | Ask for the real action | Keyword or action object, optional recap of the N steps, sign-off |
+
+Keep one chapter grammar for all N chapters so the viewer learns it once: same positions for numeral, label, progress and instruction surface. Vary the results instead.
+
+## Rules per beat
+
+**Hook.**
+- The headline is a designed lockup, not a caption. Typical structure: 2–3 lines with a dominant line and a contrasting accent line, plus subject marks at the line ends.
+- Use the brand's type roles.
+- For subject marks, use real logos, custom icons or mascots that belong to the topic. Use emoji only if the user's identity uses them.
+- When the count is spoken, make it visible. If the presenter gestures it (fingers, pointing), sync the number to the gesture.
+- The headline must not cover the face. If it belongs above the head and there is no room, slide the shot down and extend a plain, static background from its own edge rows (blurred, feathered seam). Otherwise place the headline over clothing or empty background.
+- Optional generated lockup: only if media preferences allow generated images and the spend is authorized.
+  - Pass real logos as references, request a transparent background, check spelling and accents, and trim to the alpha bounds.
+  - Generate only the variants covered by the authorized budget; one can be enough. Treat it as one object: animate the whole lockup (pop, settle, exit), not invented sub-layers.
+  - Keep matching follow-up stickers (count, CTA keyword, mascot) in the same generated style.
+
+**Chapter.**
+- The numeral enters on the ordinal word ("first", "second"…). The step label follows within ~0.1–0.3 s.
+- The instruction surface is a realistic container for the step: a chat prompt, recipe card, settings panel, whiteboard or product label. Use real interface captures when the step is factual; label illustrative UI as such.
+- When appropriate for the resolved text and motion preferences, reveal the instruction word by word as it is spoken and emphasize its keywords. Otherwise use a readable static instruction. Coordinate this surface with captions to avoid competing duplicate text; preserve explicitly requested captions and accessibility requirements.
+- If the instruction is "sent" or "applied", show that action (button press, tap) before cutting to the result.
+
+**Result.**
+- Derive the mechanism from the step's verb and object: reveal, chain, follow, transform, sync, cut, mix, stretch, compare, measure…
+- Choose each result mechanism for the action being taught. Reuse a mechanism when the actions genuinely match; never force variety at the expense of clarity.
+- Make the result literally do what the voice says, at the moment it says it:
+  - "the words appear behind an edge": the spoken words appear behind an edge.
+  - "this card expands": the instruction card itself expands.
+  - "the camera follows my hand": the frame tracks the real hand. Use pose or hand tracking when it is available; smooth the track by about ±0.3 s and clamp it to the frame.
+- Use before/after when the step's value is a contrast. Replay the after state, compressed, when the voice says "look" or "like this".
+- Prefer authentic footage or screen capture of the real result when the claim is factual. Authored animation is right for abstract or illustrative steps.
+- When the next step's subject is an object already on screen, transform it into the next state instead of cutting. Use this only when it preserves continuity and fits the resolved motion preferences.
+
+**Presenter return.** Return when the voice explains why a step matters, reacts or bridges. A single resolved keyword can land on the presenter; it must not duplicate the caption line under it.
+
+**CTA.**
+- Only a real CTA from the script.
+- A recap of the N step names works as a save trigger when the voice says to save or remember.
+- Sync any closing gesture (wave, point) to a small sign-off element.
+
+## Sync and pacing
+
+- Anchor meaningful entrances to measured spoken words or visible gestures. A ±2-frame tolerance is a useful starting point for exact demonstrations, not a universal pacing rule. Read word timestamps from the transcript; do not estimate them from the script.
+- Hold each state long enough to read and understand, considering copy length, language, accessibility and the resolved pace. Review unintended dead time; an intentional hold is valid and does not need decorative motion.
+- Between consecutive states of one transformation, avoid unintended empty gaps. Preserve deliberate pauses that explain the result; timing follows the current material, not a fixed pilot threshold.
+- Keep step count consistent everywhere: the spoken count, the headline, the chapters, the progress indicator and the recap must agree.
+- Sound follows the user's audio choices, including no SFX. Tie cues to meaningful events, avoid mechanical per-letter clutter and keep any typing cues subordinate to narration.
+
+## Identity roles to resolve
+
+Map these roles to the user's tokens and `design.md`; never to a reference's or pilot's palette:
+
+| Role | Notes |
+|---|---|
+| Headline type | Dominant and accent styles |
+| Step numeral | Display face; large |
+| Step label fill and text | |
+| Progress indicator | |
+| Instruction surface and text | |
+| Keyword emphasis | |
+| Result graphics | Main object, secondary object, success state |
+| Background for chapter and result beats | Footage, solid, texture or the brand's ground |
+| Captions | The brand's caption rules |
+
+## Failure modes seen in practice
+
+- **Absolutely positioned lines overlap** when a font or the copy changes. Lay out text in flow and measure it.
+- **Mask edge mismatch.** If a text mask's clipping edge is not exactly the visible line, letters peek out below the line and read as broken. The visible edge is the clip edge.
+- **A word strip placed by time overlaps** when speech is fast. Lay the words out in flow and scroll by interpolating between spoken timestamps.
+- **Tiny demo objects.** Size them for a phone. Pilot minimums that worked on a 720 × 1280 logical canvas: objects ≥ 120 px, labels ≥ 40 px, buttons ≥ 160 × 84. Scale them to the output profile.
+- **A dead surface between states**, such as an expanded card waiting for its contents. Start the next state immediately.
+- **Rolling counters look broken in stills** when the clip window is taller than one digit. Clip to the digit height.
+- **Results that only illustrate** the topic instead of performing the step.
+- **The same demo template reused**, or chapters whose layout drifts.
+- **A headline covering the face**, or anything outside the output profile's safe areas.
+
+## Review checklist
+
+1. **Contact sheet.** Make a still of every beat state: hook, each chapter after typing, each result at its key word, CTA.
+2. **Anchors.** For every anchor, check stills at about −0.1 / 0 / +0.1 s around the word or gesture.
+3. **Count.** Confirm the step count matches everywhere and every step has a visible result.
+4. **Variety.** Confirm each result performs its instruction; justify repeated mechanisms or deliberate variation by the action being taught.
+5. **Safe areas.** Check them for every element, not only captions, using the output profile.
+6. **Audio.** Watch the real motion, and listen or measure cue timing against the voice. Report anything not heard.
+7. **Labelling.** Report what is authentic, illustrative and generated.
+
+## Pilot evidence (example values, not defaults)
+
+These measurements come from one 66 s vertical tutorial with 5 software instructions. They are examples only.
+
+| Measure | Pilot value |
+|---|---|
+| Hook | 4.5 s |
+| Chapter beats | 2.6–4.6 s |
+| Result beats | 2–9 s |
+| Presenter returns | 2–4 s |
+| CTA | 6 s |
+
+What the user approved in the pilot:
+- choosing between three identity options shown on real frames before the edit;
+- a generated headline with real logos and the topic's mascot instead of emoji;
+- the instruction typed on the spoken words;
+- results that performed each step;
+- the count synced to the presenter's five-finger gesture.