editorbrain 0.31.0 → 0.34.0

package/package.json

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

package/skill/editorbrain/SKILL.md

@@ -24,11 +24,13 @@ For factual subjects or real demonstrations, inspect authentic footage/images fr
 5. Ground each new edit or materially changed direction in the **edited-video reference library**, including when a favorite style is selected. Search with `search_from_brief` (CLI `editorbrain search brief --file <brief.json>`) and the project ID after inspecting the material. Read [search brief](references/search-brief.md) for the schema and [editorial evidence](references/editorial-evidence.md) for selection/adaptation. Search communicative needs, not a guessed template. A scoped revision may reuse still-valid inspected evidence and approval. The optional `search_for_edit` server-analysis path is never an automatic fallback.
 6. Survey candidates across the video's needs, then inspect selected documents and actual frames/intervals, plus audio when sound matters. Build a coherent scene-level palette of techniques: opening, imagery, type, explanation and transitions can come from different references. A shortlist is not a single template for the whole video. Use preferences to retain, adapt or reject mechanisms; save evidence, limitations and beat-level adaptations in `direction.md`. A motion-catalog lookup does not complete this step. If evidence is inaccessible or unsuitable, disclose the gap. For factual beats, compare allowed user footage and authentic web media with authored explanation. The engine does not dictate the imagery or entire layout.
 7. Follow the effective review mode: `direct` → implement and review; `directions` → propose suitable alternatives with labelled reference evidence; `sample` → show a frame/short clip made with customer material before the full edit. Respect existing approval. Check the preference version before proposals, costly generation and full rendering; a web update cannot interrupt an active tool.
-8. Carry the same `editorialSnapshot` into implementation and any specialist handoff. For a sample or localized correction, use [production continuity](references/production-continuity.md): register the exact version, retain unaffected work and retrieve pending feedback. Before delivery, use `production verify --project ID --file <render>` when available, inspect its real samples and review the final motion/audio. An editing request needs the edit, not only a plan. Use [production and review](references/production-and-review.md) to compare editorial quality with the chosen references and any applicable user-approved sample; a technical pass alone cannot satisfy that comparison. Report unverified dimensions separately from technical results.
+8. When available, read `check_workflow.projectProgress` on resuming (or `get_project_progress` / `editorbrain projects progress --project ID`). Register actual work with `update_project_progress` (`action:start`, current `expectedVersion`) / `projects start`. This keeps the web board current; it is not a heartbeat. See [production continuity](references/production-continuity.md) for final delivery and conflict handling. Carry the same `editorialSnapshot` into implementation and any specialist handoff. For a sample or localized correction, use [production continuity](references/production-continuity.md): register the exact version, retain unaffected work and retrieve pending feedback. Before delivery, use `production verify --project ID --file <render>` when available, inspect its real samples and review the final motion/audio. An editing request needs the edit, not only a plan. Use [production and review](references/production-and-review.md) to compare editorial quality with the chosen references and any applicable user-approved sample; a technical pass alone cannot satisfy that comparison. Report unverified dimensions separately from technical results.
 
 ## 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 multiple final videos, read the batch section of [production continuity](references/production-continuity.md): confirm clip grouping, isolate projects, acquire turns and respect batch budgets. `check_workflow.batch` carries coordination; it does not replace project preferences.
 
 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/production-continuity.md

@@ -100,3 +100,96 @@ allowed lists. `MEDIA_USE_REVIEW` stays pending even after a technical pass: com
 the plan and actual visible resources, including useful omissions, using
 [production review](production-and-review.md). The tool does not inspect or count
 imagery automatically, generate assets or authorize any provider.
+
+
+## Keep the project board current (discover availability)
+
+Web, CLI and MCP use the same server state; do not store an independent status in
+`project.json`. First discover these tools/commands with the installed CLI help or
+MCP tools list. Older clients/services remain usable; report unavailable progress
+tracking without claiming that the board was updated.
+
+- `get_project_progress` / `editorbrain projects progress --project ID` returns
+  `stage`, `version`, latest review and pending count. Read on resume and before writes.
+- `update_project_progress` with `action:start`, `expectedVersion` / `projects start
+  --project ID --expected-version HASH`: mark actual editing, including a correction.
+  It does not run a render, wake an agent or authorize paid tools.
+- New registered samples automatically appear **Para revisar**. Requested changes
+  return to **En edición**. Sample approval alone never finishes a project.
+- When the user accepts the exact complete video as the final delivery, use existing
+  production approval for that revision, read progress again, then `projects complete
+  --project ID --revision UUID --expected-version HASH --user-confirmed` or MCP
+  `update_project_progress` with `action:complete`, `revisionId`, `expectedVersion`,
+  `userConfirmed:true`. Do not request the same approval twice; record an existing
+  explicit final acceptance. A frame, preview, successful render or technical pass
+  is insufficient. Only the latest current, available, approved video with zero
+  pending project feedback can finish. Direct editing mode still skips proposal
+  gates; final acceptance is not inferred from that preference.
+- `action:queue` / `projects queue` returns work to **Por editar** when the user
+  defers it and no corrections are pending. `start` can reopen a completed video.
+- On `progress_changed`, refresh and reconcile; never automatically replay stale
+  intent. If a write response is lost, read progress before retrying. No push/pull
+  is needed for this operational state. No live-agent presence is implied.
+
+Archived samples and approvals remain historical evidence. Context changes,
+new samples, removed media and requested corrections can invalidate completion.
+Report unavailable/unknown state honestly; do not assign a stage from filenames.
+
+## Multiple videos: one batch, isolated projects
+
+Load this section only for multiple deliverables. Discover `batches` / editing-batch
+MCP tools first. One project means one final video, not necessarily one source file.
+Inspect the supplied inventory; if grouping is ambiguous, show a short visual list
+of proposed titles and assigned clips for confirmation. For videos from scratch,
+create one project/brief per idea through the existing project workflow. Never
+silently turn ten clips of one story into ten videos. Keep originals intact.
+
+Create the projects normally, then `batches create --file batch.json` (MCP
+`create_editing_batch`). Retain a UUID batchId for retry-safe creation:
+
+```json
+{"batchId":"UUID","name":"This week","styleMode":"series","maxConcurrency":1,"maxCredits":0,"items":[{"projectId":"first-video","maxCredits":0}],"userConfirmed":true}
+```
+
+Confirm the grouping and ceilings with the user; start paused. Zero forbids paid
+Studio generation, not local editing. `series` means a shared direction, not copied
+scenes. `individual` chooses references for each story. Neither overwrites brand,
+language, exclusions, review preference, project exceptions or integration access.
+Reuse relevant shared context but search edited-video references for each brief;
+carry the evidence into each project. Never copy a previous video's factual assets
+or assume its approval transfers. Keep directories, renders and feedback separate.
+
+Read `batches get ID` / `get_editing_batch`. Resume with `batches resume ID
+--expected-revision N` / `update_editing_batch`. This enables scheduling; it does
+not start a renderer or authorize spending. Work serially by default; use at most
+the configured slots if the host supports independent workers and enough disk,
+RAM and render capacity. Do not load every project's full context into one task.
+
+Before work, claim ONE project using `batches claim ID --project PROJECT
+--lease-token UUID` / `editing_batch_lease`. Keep that UUID for retries; another
+session cannot acquire the same item. Read `check_workflow.batch` and the project's
+snapshot; mark actual editing through project progress. Renew within 20 minutes
+and recheck before each expensive step. Stop scheduling on pause, cancellation,
+expiration or conflict. Local processes already running cannot be remotely killed
+by the queue. On host shutdown work waits for another authorized session.
+
+Studio still needs exact quotes and authorized spending. Pass `--batch-lease-token`
+to `studio run` (MCP `studio_run.batchLeaseToken`). The server enforces the shared
+lot ceiling, per-video ceiling and credit balance atomically. External services
+have separate budgets: these limits cannot control a user's own API/MCP charges.
+Read existing job IDs after unknown outcomes; never replace them with new quotes.
+
+After registering a fresh project sample, `batches release` / lease action release
+frees the turn for the next video. This does NOT approve the sample or finish the
+video. On failure use `attention`, preserve outputs and continue unaffected items.
+Expired turns require inspection of local outputs and paid jobs before explicit
+`batches retry ID --project PROJECT --expected-revision N`. Retry resets only that
+queue item; it does not regenerate, delete files or waive existing approvals.
+A requested correction similarly requeues its project after pending jobs settle.
+Final acceptance remains per exact video; batch completion is derived from those
+individual acceptances, never inferred from all renders finishing.
+
+Pause stops new turns/paid jobs. Cancel also prevents future resumption of that
+batch; in-flight jobs may still finish and be charged. To work separately afterward,
+`batches detach ID --project PROJECT --expected-revision N` removes active membership
+only after the cancelled project's jobs and turn have ended. History/costs remain.

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,51 @@
+---
+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) or an aspirational list that turns personal
+  and ends in a demonstration. Use when the user names a format or editorial family,
+  asks to follow a reference's structure, or the material is a list of steps or items. 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) |
+| Aspirational list → personal experience → demonstration | The voice lists N people, tools or habits, each illustrated by strong images, then turns personal and shows how to act on it with real material | [aspirational list](references/aspirational-list-demo.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/aspirational-list-demo.md

@@ -0,0 +1,140 @@
+# Format: aspirational list → personal experience → demonstration
+
+A narrator promises a list ("N things, people or tools that…"). Each item opens its own short block of images carrying one lesson. The list then turns personal, toward the narrator's own practice or the viewer's future self, and lands on a concrete demonstration of how to act on it. The narrator stays present as a small element over full-frame imagery instead of filling the frame.
+
+Evidence status: one implemented, user-approved pilot (talking head, a list of five practices, Spanish, vertical, about 130 s). Its reference was a library profile of an English aspirational list of about 85 s ending in a product demo. Transfer to other niches and to voice-over-only material is untested; record the first adaptation's review.
+
+## Authority and adaptation
+
+Reuse the coordinator's resolved context. This guide offers reference grammar, not a mandatory layout or an override of presenter, media, motion or accessibility preferences. In direct mode, make compatible decisions and record them; ask for a sample approval only when the resolved review mode or an unresolved user requirement calls for one.
+
+Match visual changes to meaning; do not cut the audio to force a picture change onto a timestamp. ASR word starts are candidates to verify against playback. Short phrases may need a shared image and longer explanations may need several states.
+
+## Fit
+
+Use when:
+
+- the script enumerates items that can each be illustrated by strong images: people, tools, places, habits, products;
+- the voice carries continuously (voice-over or talking head), and reducing the presenter to a small element does not lose meaning;
+- the list ends in something actionable that can be shown with real material: the narrator's own practice, a configured tool, a product, a first step.
+
+Niche examples: people to study in any field, tools for a craft, habits for a goal, places to visit, investments to understand, routines of known performers.
+
+Avoid or adapt when:
+
+- the items cannot be illustrated without fabricating evidence (biographical claims, results, quotes);
+- the presenter's face is the content (reaction, emotion, testimony). Keep them full frame instead;
+- the demonstration would promote something that does not deliver what is said. Omit the demo and keep the list.
+
+## Skeleton
+
+| Beat | Function | What must be on screen |
+|---|---|---|
+| Hook | Promise the list and who it is for | A collage of the list's strongest visuals (one per cell), a short headline lockup over it and the presenter small over the collage |
+| Item k (repeat N times) | Name the item and its lesson | Item marker (k of N plus name) and one full-frame image per idea, cut on the word that introduces it |
+| Personal turn | Move from examples to the narrator or the viewer | The narrator's real material: their folders, screens, products, recordings |
+| Demonstration | Show how to act on the list | Real interface or product: page scroll, configured screens, steps; the presenter may shrink, move or leave |
+| CTA | The real ask | The presenter returns (full frame or small), optional recap of the N items, the CTA object |
+
+The personal turn can be a final block or woven into every item, with each item ending on the narrator's own tool or result. The pilot wove it into every item. Choose by the script; do not force a twist the voice does not make.
+
+## Voice and image
+
+- **One idea, one image.** Cut when the voice introduces a new idea, name or example (on that word), not on a timer.
+- **The image answers the sentence:**
+  - a named tool or product: its real mark or interface at the moment it is named;
+  - an abstract claim: an illustrative image, labelled when it could be mistaken for evidence;
+  - a number: the number on screen;
+  - a spoken series in one sentence ("apps, documents, tables, projects"): one demo that advances on each word (scroll steps, highlighted rows).
+- **Authentic material first** for anything factual: the user's own product screens, folders, repositories, dashboards and recordings. Clean captures of public pages for named products are authentic support. Hide consent overlays without accepting them, and use logged-in or private screens only when the user provided or explicitly authorized them. Retain source attribution and exclude private details unnecessary to the edit.
+- **Illustrative stills** (generated or licensed) only within the media preferences and an authorized budget. Keep one coherent look across them (lighting, grade, depth) so the list reads as one piece.
+- **Brand characters:** when generating a brand character or mascot, always attach the real asset as a reference; an off-model character undermines trust.
+- **Do not reuse an image, capture or clip** for a different idea. A deliberate callback is the exception and must read as one.
+- **The hook headline** sits directly on the collage in the reference. Keep it legible with the resolved type treatment (outline, shadow, weight) before adding a backing band; follow accessibility and the user's caption/text preferences.
+
+## Presenter treatment
+
+- **Reference grammar:** the presenter is a small floating cut-out (person matte, no background, no frame) placed over each image and relocated per shot.
+  - Placement keeps faces, headlines, controls and the demo's key interface visible.
+  - Adapt to the user's presenter/layout preferences: a split layout, full-frame return, framed picture-in-picture or no presenter may fit better. A clean matte is not a requirement for using the narrative structure.
+- **Matte:** generate it for the whole cut before designing. The pilot used on-device person segmentation on a static camera; other cameras and motions need verification. Apple Vision is an optional macOS implementation, not a client dependency. On other platforms use an available, authorized masking tool or an agreed layout without a matte. Do not install tools or upload private footage merely because this guide mentions segmentation.
+  - Check hair, hands and anything held near the body.
+  - If edges fail, compare the available alternatives within the user's tools, budget and data permissions; a simpler layout is acceptable.
+- **Size and crop:** head to mid-torso, hands included, at about a third of the frame width in the pilot.
+- **Edge treatment:** a clean crop, fades, outline or shadow is an identity choice; resolve it from preferences or ask. The pilot shipped a clean crop with a soft drop shadow.
+- **Relocation:** when the presenter moves with the cut, a small settle (scale or position) can help the eye find them again; follow the resolved motion intensity.
+
+## Rhythm
+
+- Measured pilot holds ranged from about 0.7 s to 6 s (median about 3 s) per image; item blocks lasted 15–31 s. These are evidence, not targets: holds follow the idea and the copy.
+- A longer hold can use a slow push, page scroll or a later overlay when it helps meaning. A deliberate static hold is valid for reading or calm motion preferences.
+- Cuts can land with a short push-in to give each new image energy, within the resolved motion preferences.
+- Captions stay in one stable band, never under the presenter. Short phrases suit the fast image rhythm.
+
+## Filling the frame
+
+Authored scenes (numbers, code or file windows, badges, logo grids) should use the chosen output frame deliberately, including square and landscape adaptations. Options include:
+
+- a full-bleed image behind them;
+- windows that span the width;
+- overlays sized to be read on a phone.
+
+A small centered element on an empty stage reads as a placeholder next to full-bleed images. Crop real captures to their most legible region (one card, one heading, one logo) instead of shrinking a whole page into a cell.
+
+## Identity roles to resolve
+
+Map these roles to the user's tokens and `design.md`, never to a reference's or pilot's look:
+
+| Role | Notes |
+|---|---|
+| Hook headline lockup | Dominant and accent styles, legibility treatment |
+| Item marker | Numeral and item name; persistent or entering per item |
+| Captions | The brand's caption rules |
+| Tags on real captures | Source or explanation labels |
+| Overlay cards | Numbers, badges, stamps, logo tiles |
+| Grade of illustrative stills | Consistent across the video |
+| Presenter edge treatment and shadow | |
+
+## Failure modes seen in practice
+
+- **A framed picture-in-picture** where the reference floats a cut-out: it changes the format's look. Confirm the presenter treatment before rendering.
+- **Opacity fades or backing bands** added for legibility without being asked for. Prefer type treatment, and confirm visible changes to the presenter or headline.
+- **Authored scenes as small elements on an empty dark stage.**
+- **The same image used in the hook, an item and a recap.**
+- **Collage cells with unreadable page text.**
+- **Generic stand-ins** (an unbranded laptop app) where the voice names a product: show its real mark or interface.
+- **A brand character generated without its reference image**, coming out off-model.
+- **The presenter covering the key element** of a real capture.
+- **Consent banners left visible** on page captures.
+
+## Review checklist
+
+1. **Contact sheet:** one still per shot at its key word.
+2. **Named products:** every named product, person or tool shows its real mark or interface when named.
+3. **Reuse:** list every visual; confirm none repeats except a deliberate callback.
+4. **Presenter:** check placement per shot (nothing important covered) and matte edges on hair and hands in motion.
+5. **Frame use:** authored scenes fill the frame; overlays are readable at phone size.
+6. **Captions:** the band is stable and safe areas are respected for every element.
+7. **Labelling:** report what is authentic, illustrative and generated.
+8. **Audio:** follows the user's choices; report what was not heard.
+
+## Pilot evidence (example values, not defaults)
+
+| Measure | Pilot value |
+|---|---|
+| Total | ≈ 130 s; hook 4.2 s; CTA 10.5 s |
+| Images | 37 shots, none repeated |
+| Public page captures and the narrator's own screen recordings | 14 shots |
+| The narrator's own brand assets (product mascot) | 3 |
+| Authored scenes built from the narrator's real data (folders, files) | 3 |
+| Illustrative generated stills | 15 |
+| Hook collage and full-frame presenter CTA | 2 |
+| Presenter | Floating cut-out, relocated on almost every cut |
+
+What the user approved:
+- the floating cut-out;
+- real product pages and the narrator's own tools as the personal experience;
+- one image per idea;
+- the headline set directly on a collage that shows the real brand marks of the list.
+
+What the user corrected: a framed presenter, an opacity fade on the cut-out, a backing band behind the headline, repeated images, empty authored scenes and generic stand-ins for named products.

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.