editorbrain 0.34.0 → 0.35.0

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -10,7 +10,7 @@ When present, resolved `editorial.identity` or workflow `context.identity` holds
 
 Read effective `creativeDirection` from the resolved context/snapshot. `automatic` delegates unspecified aesthetic decisions per video; `guided` starts from saved choices and still resolves gaps. Neither changes quality, explicit constraints, review mode, tool access or spending. Preserve stored preferences; do not convert an automatic project direction into a reusable style without a request.
 
-If `creativeDirection.configuration.status` is `pending`, use [onboarding](references/onboarding.md) to complete only its pending categories with the user before editing. Preserve prefilled choices; record explicit choices or delegation, never infer confirmation from defaults. Recheck the saved state before proceeding.
+If `creativeDirection.configuration.status` is `pending`, use [onboarding](references/onboarding.md) to complete only its pending categories with the user before editing, except when questionPolicy.mode is autonomous: resolve open aesthetics per project without marking categories reviewed. Preserve prefilled choices; record explicit choices or delegation, never infer confirmation from defaults. Recheck the saved state before proceeding.
 
 When no style is explicitly chosen, choose the editorial direction yourself after inspecting the source and relevant evidence. Keep brand requirements separate from creative hypotheses: a favorite, onboarding example, component or top-ranked result does not fix the composition. Distinguish faithful preset transfer, adaptation of an editorial family and inspiration from selected techniques. Preserve requested mechanisms, not merely colors. Missing footage, timing or evidence remains a production dependency; do not call an approximation a verified transfer.
 
@@ -26,11 +26,11 @@ that direction:
 
 | Specialty | Owns | Read when needed |
 |---|---|---|
-| Montage | Take selection, source order, cut points and pacing that preserve the intended meaning | [Production review](references/production-and-review.md); speech joins: [audio](references/audio-production.md) |
-| Media | Authentic or illustrative asset selection, acquisition and inspection for the scene | [Real media](references/real-media.md) |
+| Montage | Preserve the intended ideas and selected CTA; map complete takes and purposeful pacing from source time to final time | [Production review](references/production-and-review.md); speech joins: [audio](references/audio-production.md) |
+| Media | Cover the relevant beats with acquired, inspected assets before full composition; carry their intended use into motion and review | [Media acquisition](references/real-media.md) |
 | Motion | Staging, movement and transitions that express the scene's purpose | [Motion skill](../editorbrain-motion/SKILL.md) |
-| Sound | Voice alignment, music/SFX selection and mixing within the audio choices | [Audio](references/audio-production.md) |
-| Review | Evidence-backed findings against the actual output and its requirements | [Production review](references/production-and-review.md) |
+| Sound | Intact speech and final-time alignment; independently honor voice, music and SFX, auditioning the actual mix | [Audio](references/audio-production.md) |
+| Review | Compare meaning, reference mechanisms, preferences and perceptual quality with the actual output; return localized defects | [Production review](references/production-and-review.md) |
 
 All reuse the same resolved snapshot and current scene decisions. No guide,
 component or provider default can independently change the message, required
@@ -46,6 +46,14 @@ reason and affected beats; ask the user only if their intent or authorization
 remains unclear. Update the existing direction and invalidate affected checks.
 A review finding starts a correction; it does not silently redefine preferences.
 
+Use one compact handoff in the existing direction: context version, affected beat,
+intended message, inspected reference/resource, source interval versus final-time
+cue, decision and remaining check. Include only fields relevant to that task.
+Montage owns the cut map; motion and sound use its current final time. A timing
+change invalidates dependent captions, animation and SFX cues, not the whole
+creative direction. Share the changed interval and recheck its joins and downstream
+timing. Do not create five parallel plans or require five agent calls.
+
 ## Load context selectively
 
 Use `projects list` when needed and `pull --project <id>` for immediate context; never default to `--all`. Discover additional documents by a narrow prefix and read on demand. Library media remain remote until a specific editing question needs them. Read compact results first; omitted entries and truncation are not proof of completeness.
@@ -75,7 +83,10 @@ Choose production media by what the scene claims. For real people, places, histo
 Carry useful media choices into the scene plan and verify actual use: allowed is
 an option, preferred guides selection, and explicitly requested imagery must be
 delivered or have a specific blocker. Do not confuse reading preferences with
-fulfilling them, or a JavaScript renderer with an images-off preference.
+fulfilling them, or a JavaScript renderer with an images-off preference. Use the
+media guide for visual support even without factual claims. Resolve useful gaps
+across the story before full composition; do not count one opening image as
+coverage of unrelated beats. Reuse the existing plan, not a second media plan.
 
 ## Execute and review
 

package/skill/editorbrain/SKILL.md

@@ -15,17 +15,21 @@ When the user asks to save an edit as a style, create a new style or improve an
 
 ## Start here, including a first installation
 
-For factual subjects or real demonstrations, inspect authentic footage/images from permitted sources before designing substitutes; use user material or available web tools as allowed. For illustrative scenes, choose code/AI when it fits. The [real-media guide](references/real-media.md) covers the distinction; it is separate from searching EditorBrain for editing techniques.
+Before composing an edit with visual support, use the [media acquisition guide](references/real-media.md), including for fully animated videos. Cover the relevant beats with acquired and inspected user/web/generated resources as appropriate. Resolved/workflow `mediaAcquisition`, when available, turns the effective choices into planning guidance; it is not proof of searches or tool access. Searching EditorBrain for editing techniques is a separate job.
 
 1. Read the bundled [AGENTS.md](AGENTS.md) once for the editorial contract. Do not assume the host loads this nested file automatically.
 2. If no workspace is ready, use [first edit](references/first-edit.md). For visual onboarding inside this agent, load [onboarding](references/onboarding.md) only then; discover command availability before use. Verify connection, discover or create the active project, and prepare its context without overwriting existing files. Read [CLI and MCP](references/cli-mcp.md) only for the commands needed now.
-3. Read the selected project's `project.json`, brief, direction and the brand/style files it names. Resolve effective tokens and inspect available editing tools. Use `check_workflow` (CLI `editorbrain workflow check`) for creative direction, review preference, scoped memory and personal integrations. If creative configuration is pending, complete only those categories through [onboarding](references/onboarding.md) before editing. Declared access is not a working connection; check the needed provider in this session and read [integrations](references/integrations.md) only when using or configuring one. If `audioProduction` is present, honor its voice/SFX/loudness choices; read [audio production](references/audio-production.md) when needed. Use `context.mediaPreferences` for saved image/motion choices; fetch only needed recipes with `get_media_style` / `media style <id> --style-version <version>` (see [media preferences](references/media-preferences.md) when adapting them). Compare workflow version and `contextVersion` at later checkpoints; fetch changed context before acting. Do not load every project or library document.
+3. Read the selected project's `project.json`, brief, direction and the brand/style files it names. Resolve effective tokens and inspect available editing tools. Use `check_workflow` (CLI `editorbrain workflow check`) for creative direction, review preference, scoped memory and personal integrations. If creative configuration is pending, complete only those categories through [onboarding](references/onboarding.md) before editing. Choose the resource route before checking funds: personal integrations/native host tools do not require EditorBrain creative credits; built-in tools do. Never switch paid routes silently. On a blocker, explain the next step with a verified link and one compatible alternative; use returned recovery guidance. Declared access is not a working connection; check the needed provider in this session and read [integrations](references/integrations.md) only when using or configuring one. If `audioProduction` is present, honor its voice/SFX/loudness choices; read [audio production](references/audio-production.md) when needed. Use `context.mediaPreferences` for saved image/motion choices; fetch only needed recipes with `get_media_style` / `media style <id> --style-version <version>` (see [media preferences](references/media-preferences.md) when adapting them). Compare workflow version and `contextVersion` at later checkpoints; fetch changed context before acting. Do not load every project or library document.
 4. Inspect the actual script/video yourself. Understand its argument, goal, audience, tone, rhythm, usable resources and brand restrictions. For unfamiliar multi-clip material or technical render checks, use [local production](references/local-production.md) as needed. Read compact results and fetch details only to answer a specific question. Declare what you could inspect: script, frames, motion, audio and coverage. If you cannot access a modality, keep the limitation explicit; never invent it from a filename.
 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.
+6. For a new or materially changed direction, use [editorial families](references/editorial-families.md) to load only the relevant method; a fitting saved method or small correction can reuse its decisions. 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. 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.
 
+9. Deliver a visual HTML artifact in this chat with every new edit and revised preview/final, unless the user asks otherwise. Use the [visual artifact protocol](references/production-continuity.md#visual-artifact-in-the-users-chat): black/white review interface, actual preview, localized comments and an explicit copy-to-chat handoff. Respect review mode; an artifact does not add a mandatory approval to direct editing. Do not substitute a long text response or assume every host supports inline playback.
+
+Read resolved `questionPolicy` before asking: essential asks only consequential missing information after inspecting material and preferences; collaborative offers up to three recommended choices; autonomous asks none, records reversible decisions and leaves indispensable inputs/permissions/review approvals pending for only the affected work. Current task instructions govern; preserve brand settings. Use the [consultation planner](references/onboarding.md#consultation-frequency) for unresolved needs. Creative direction, review and spending remain independent. In batches continue other eligible videos and summarize blockers together.
+
 ## 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. 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.

package/skill/editorbrain/references/audio-production.md

@@ -33,6 +33,17 @@ For a voice-led sequence, lock narration before final music and animation timing
 For music- or action-led work, use the timing anchor in the project direction;
 propose changes there if needed instead of imposing voice-led timing. Where supported, a [music composition plan](https://elevenlabs.io/docs/api-reference/music/compose) can use final section durations. Inspect the result: a requested drop may not occur as intended. RMS/onsets locate candidates; listening establishes musical intent and ducking. Do not require every cut to land on a beat.
 
+Use the montage's current cut map and name the timebase: source audio, shot-local
+or final timeline. Place accents against the event's audible attack, not merely
+the sound file's start. A requested SFX treatment needs fitting selected sounds
+and an actual mix, not just a cue list. If a useful sound is missing or omitted,
+record why. Audition relevant stems and the encoded mix: an effect that is clear
+alone may vanish under speech. Adjust gain, frequency, placement or selection so
+it supports the intended action without masking words. Density is not loudness;
+there is no universal gain or requirement to accent every cut. Protect the hook
+when requested. Music, added effects, narration and source ambience remain
+independent decisions; review exclusions in the actual mix, not track labels.
+
 ## Measure the delivered file
 
 In addition to `production check`, measure integrated loudness/true peak from the actual encoded/muxed deliverable:
@@ -49,4 +60,41 @@ When normalizing elsewhere, inspect actual processing mode: FFmpeg [loudnorm](ht
 
 ### Retakes and speech cuts
 
-ASR can collapse repeated takes into one phrase with an abnormally long word. Inspect suspicious durations and repeated starts in short source windows; retain one complete take. Build the cut from source timing, check quiet handles around each join and review the resulting audio before calling it clean. Do not trim solely to ASR boundaries or apply a fixed padding to every word. Re-transcribe the new cut for captions, normalize proper names against evidence, and explicitly report when listening review was unavailable. Technical audio checks alone do not certify intact speech.
+ASR can collapse repeated takes into one phrase with an abnormally long word.
+Inspect suspicious durations and repeated starts in short source windows; retain
+one complete take rather than both attempts or half a word from each. Compare the
+retained argument with the brief; montage decides substantive omissions.
+
+Build cuts from source timing, then audition each risky join with its neighboring
+phrase. Preserve consonant attacks and word tails; silence detection, fixed
+padding and ASR word boundaries alone cannot select a clean cut. Fades can remove
+a click but cannot restore a syllable cut away. Inspect long pauses in context
+instead of removing every breath or intentional hold.
+
+After trimming, reordering or speed changes, remap valid word cues through the
+actual cut/speed map and verify boundary words. Realign or re-transcribe when the
+mapping or transcript is unreliable, using the requested route; do not regenerate
+ASR for every harmless visual change. Normalize proper names against evidence
+without altering the spoken meaning. Report unavailable listening review;
+technical audio checks alone do not certify intact speech.
+
+## Event-aligned local SFX mix (next release)
+
+For code animation, declare the cue beside the visual event, then export one list
+in **final output seconds**. Remap composition time through the exact kept ranges;
+a cue in a removed range is omitted, not moved to the next cut. Never collect cues
+as a side effect of `draw(t)`; seeks must not duplicate them. Motion primitives
+expose disabled suggestions through `getMotionCues()`; these are not permission
+or actual audio. Respect current SFX density, exclusions and permitted sources.
+
+`production mix-events --voice voice.wav --cues cues.json --out .editorbrain-local/new-mix`
+accepts `{schemaVersion:1, clock:"output_seconds", cues:[{id,time,file,peak,reason}]}`.
+Files are relative to the JSON directory. `peak` is linear peak amplitude (e.g.
+0.06), not LUFS. Use an existing permitted SFX bank; no personal bank is distributed.
+The command aligns the decoded SFX peak to the event, keeps voice gain at 1, adds
+no music and rejects clipping rather than silently normalizing the voice. Trim
+unwanted tails in prepared source effects, not implicitly at delivery. Empty cues
+are allowed. Bounds: voice up to 10 minutes, each SFX up to 10 seconds, 300 cues.
+Listen to the rendered mix: audible attack can precede its maximum peak. The
+sample-peak check does not certify true peak/loudness; use the existing audio
+checks and review the final encoded video. New outputs never replace source audio.

package/skill/editorbrain/references/editorial-evidence.md

@@ -26,6 +26,10 @@ because a new session started.
 
 ## Cover the scene needs before narrowing
 
+Use [editorial families](editorial-families.md) when a new direction needs a
+method. Its recipes connect selected evidence to implementation; they do not
+replace the search or the user's chosen style.
+
 Use the current request to choose how much the direction may change. With
 **the user's saved style**, retain its defining grammar and adapt the scene.
 With **a specific reference**, retain its requested mechanisms and permitted

package/skill/editorbrain/references/editorial-families.md

@@ -0,0 +1,64 @@
+# Choose an editorial method
+
+Use after inspecting material and searching the edited-video library, when a new
+edit needs a method or a changed direction needs another one. A small correction,
+a saved method that already fits, or a standalone effect does not require a new
+family selection. The same agent uses these guides; no extra agents are required.
+
+| What the viewer needs | On-demand family guide | Method |
+|---|---|---|
+| See a process or its result | [Demonstration](family-demonstration.md) | Context → action → visible result |
+| Understand a person's argument | [Presenter](family-presenter.md) | Performance with semantic evidence |
+| See relationships change | [Animated](family-animated.md) | Before → action → after |
+| Follow a narrated thesis | [Essay](family-essay.md) | Argument, contrast, visual payoff |
+| Follow an authentic lived process | [Personal](family-personal.md) | Attempt, consequence and character |
+
+These five guides live inside the core skill and are read only when useful.
+The three installed skills remain editorbrain, editorbrain-formats and
+editorbrain-motion. Do not load every family or launch extra agents.
+A family suggests a broad method. When replicating a specific format, read its
+[format guide](../../editorbrain-formats/SKILL.md): its defining structure takes
+precedence over generic family recipes, under the user's resolved preferences.
+If a saved approved direction already fits, reuse it; no new classification is
+required. Existing family guide paths remain valid; there is no API classifier.
+Choose by communicative function and available material, not the industry or
+whether the video happens to contain a face. A hybrid can borrow a recipe for a
+particular beat without changing its whole direction. Open creative direction
+allows that choice; a requested faithful style retains its defining grammar.
+
+## One context and one record
+
+The [shared contract](../AGENTS.md#decision-ownership) and resolved project context
+remain authoritative. These guides do not introduce API modes, new preferences,
+mandatory layouts, media permissions or budgets. Keep the chosen method, relevant
+recipe, adaptation and actual evidence in the existing `direction.md`, alongside
+its context version. Reuse approved decisions for unaffected scenes.
+
+Source IDs below are discovery leads from analyzed edits, not inspected evidence
+for this project, guaranteed access, source-code locations or reusable assets.
+Use `search_from_brief` / `search brief` and `get_reference` / `library get` as
+available; follow returned documents and media handles. Inspect the relevant
+sequence, then record its actual hash/interval. If a seed is inaccessible, choose
+another authorized example that serves the same purpose; do not bypass grants.
+If none fits, follow the evidence guide's labelled original-direction fallback.
+Do not fetch every listed source. Read only the chosen family and useful recipe.
+
+## From recipe to a new edit
+
+Preserve the mechanism, replace its subject and recompute its timing from the
+new speech/action. Apply the [media acquisition method](real-media.md) to obtain
+and inspect resources before relying on them. A diagram can be authored in code;
+a claim about an actual interface needs authentic evidence or an explicit
+illustration label. A source's palette and SFX do not override user preferences.
+For animation, load [motion](../../editorbrain-motion/SKILL.md) only when needed;
+use its verified source code if it fits, or author the missing mechanism. Scraped
+reels are not original editable projects.
+
+For the demanding passage, compare a short render with the inspected reference
+sequence: did its visual mechanism survive, with this user's identity and
+message? Revise staging before extending an attractive but irrelevant layout.
+Follow the existing review mode, not a new approval gate. Technical validity is
+separate from creative acceptance. These methods are curated starting guides;
+transfer to new topics/brands still needs audiovisual evaluation. Save a reusable
+user style through [style creator](style-creator.md) when requested; do not write
+one customer's choices back into these shared guides.

package/skill/editorbrain/references/family-animated.md

@@ -0,0 +1,65 @@
+# Animated explanation: let the visual state carry meaning
+
+Use when authored visuals explain relationships, mechanisms or a visual universe.
+A presenter may appear, but does not determine the family. Follow
+[family selection and context](editorial-families.md). JavaScript is suitable when
+available; an engine choice does not mean every resource must be drawn in code.
+
+## Interface states and connections
+
+**Discovery leads:** `instagram:DdocHKLq7i0` (UI states, connected tasks and
+presenter/graphic exchange), `instagram:Ddpfq1_RYxj` (progressive prompt and proof).
+Inspect what changes in the interface, when relationships appear and how the next
+composition inherits context. A light background or meme is not part of the method.
+
+**Build:** State the relationship to explain, then define before/action/after
+states with actual entities and truthful labels. Keep an anchor object across the
+transition so motion communicates what changed: an input becomes an output, an
+item reaches its destination, or a rule affects several tasks. Draw connections
+when the relationship is introduced; animate traversal only if it communicates
+flow. Reveal text in meaningful units, allowing completed phrases to be read.
+Use camera/scale changes to focus the consequence rather than restarting a title
+slide for each sentence.
+
+**Adapt:** Look up the relevant motion mechanism after choosing its purpose; inspect
+and adapt available source through [authored scenes](../../editorbrain-motion/references/authored-scenes.md)
+or author it when no source fits. Reuse useful behavior, not the demo's labels,
+colors, data or global composition. Apply brand roles; keep authentic logos/UI
+faithful when permitted. Source real imagery for literal claims or meaningful
+examples. An invented UI is an illustration, never proof that a product did it.
+A reduced-motion choice can use clear state changes and holds without camera travel.
+
+**Check the passage:** Would the change still be understandable without its headline?
+Are connections and outcomes honest and legible? Does the transition carry meaning
+into the next scene? If the objects remain inert and only labels enter, stage the
+relationship itself. Do not add unrelated spinning elements to satisfy “dynamic”.
+Reference frames justify layout; review playback for timing and continuity.
+
+## Brand collage
+
+**Discovery lead:** `instagram:DbZDnSpyilk` (staggered moodboard, thematic stickers,
+density/release and passage into a real procedure). Inspect the full accumulation
+and the moment it clears, not only the densest frame.
+
+**Build:** Gather images/objects from the new subject that make the idea tangible.
+Choose a dominant resource and arrange supporting layers around its reading space.
+Stagger entries by the sequence of ideas, using scale or overlap to establish
+priority. Let resources interact through framing, masking or replacement where
+useful, then clear or simplify the stage for explanation or reveal. Link a promised
+result to a real procedure when the brief requires demonstration.
+
+**Adapt:** Acquire enough relevant media to support the chosen beats through the
+shared media guide; a permitted generator is not a completed acquisition. Use
+real product details for factual claims and generated/stock resources only within
+the allowed role. The original's sticker treatment and grid are optional; recompose
+for the user's identity and delivery ratio. Animate layer entrances when sufficient;
+do not claim internal illustration animation based on a still. When new generation
+is unavailable or not authorized, use allowed inspected assets or revise the visual
+plan without quietly substituting a generic presentation.
+
+**Check the passage:** Is there a clear focal point and a reason for each resource?
+Can the key idea be read at delivery size? Does density change with the argument?
+Compare a short rendered passage before extending the scene. SFX, narration and
+music use the common audio policy, not inferred sounds from the reference. Validate
+motion and sound on the actual result; these source-derived recipes are starting
+methods, not certified transfers or fixed timelines.

package/skill/editorbrain/references/family-demonstration.md

@@ -0,0 +1,66 @@
+# Demonstration: make the process visible
+
+Use for steps, a feature explanation, or a meaningful input/output comparison.
+Follow [family selection and context](editorial-families.md); read the recipe that
+fits the beat. A tutorial need not become a series of numbered title cards.
+
+## Chapters with evidence
+
+**Discovery leads:** `instagram:DdC3fPzsfUh` (chaptered process),
+`instagram:Dbevx4zRSkd` (UI detail), `instagram:DduRLiMiv3o` (presenter + interface).
+Search the actual need: e.g. “show where the action happens, zoom its result”.
+Inspect the transition from context to detail and back, not only the chapter still.
+
+**Build:** Identify the real action, the visible control/object and the result that
+proves this step. Show enough context to locate it, enlarge the relevant region
+when the explanation needs detail, then hold the outcome long enough to understand.
+Use an annotation beside the target, not over it. Introduce a chapter only when
+it orients the viewer; derive chapter count from the task. Bridge steps with a
+retained object, action or spoken idea rather than repeated decorative bumpers.
+
+**Adapt:** Source a readable capture or an honest customer demonstration. If only
+an illustrative UI is available, label its role and avoid claiming a successful
+real execution. Reframe the UI for the delivery ratio before choosing presenter
+placement. With fixed-layout preferences, change the evidence window rather than
+moving the person. For no presenter, the interface/action can carry the sequence.
+Chapter holds and zooms follow this narration and reading time, not source seconds.
+
+**Check the passage:** Can a viewer identify the action and its result without
+already knowing the software? Are controls, numbers and captions legible at final
+size? Does the zoom preserve orientation? Listen across cuts for missing words.
+If the sample consists of labels with no visible process, acquire better evidence
+or revise the explanation before finishing the montage.
+
+## Input → result
+
+**Discovery leads:** `instagram:Ddb0qB1ArrV` (constant product with prompt/result),
+`instagram:DcuJnb6JUUK` (gesture-led comparison), `instagram:Dcggcv6xgAn`
+(diagnosis and visible fix). Inspect both states and the handoff between them.
+
+**Build:** Establish the original and name the change that matters. Preserve an
+identifiable subject, crop, scale or comparison position so the viewer can see
+what changed. Reveal the operation when it is relevant, then replace or align
+its result at the verbal/gesture cue. Let the changed feature be seen before the
+next variant. Clear competing elements when stating the takeaway.
+
+**Adapt:** Choose split view, a matched replacement or successive full frames from
+the material and screen size; split view is not mandatory. Comparisons must remain
+fair: do not improve lighting, crop or product attributes and imply that one tool
+caused every change. For an abstract result, make an explicitly illustrative state
+change. Short input cards may animate, but rendering a mock prompt is not evidence
+of a real tool run. Preserve the user's real wording, language and chosen CTA.
+
+**Check the passage:** Is the same thing being compared? Is the improvement actually
+visible, rather than only claimed by text? Do both states receive enough reading
+time? If visual continuity is lost, match composition or retain an anchor. If the
+claim lacks evidence, narrow the claim or label the illustration; more motion
+cannot repair it. Sound accents follow [audio production](audio-production.md)
+and the effective choices, including silence.
+
+## Make the operation observable
+
+For a before/after design change, preserve the same material and show the actual
+property changing (position, contrast, scale, selection). A crossfade to a finished
+result alone may hide how it was achieved. Keep labels honest: an authored canvas
+demonstration is not a recorded run of a third-party editor. At final delivery
+size, check that the changed detail is legible without requiring full-screen zoom.

package/skill/editorbrain/references/family-essay.md

@@ -0,0 +1,40 @@
+# Narrated essay: images develop an argument
+
+Follow [family selection](editorial-families.md). Use when reflection, a thesis or
+a question leads the sequence. A tutorial with essential controls remains a demo.
+
+## Argument, contrast and returning motif
+
+**Discovery leads:** `instagram:DY0ZmQevH2J`, `instagram:Dasq8-6tbt9`,
+`instagram:DZqs_AHJc5G`. Inspect an image-to-type-to-image passage and its eventual
+resolution. Their cinematic material is not licensed stock for a customer edit.
+
+**Build:** Identify thesis, complication and resolution in the actual narration.
+Give each image a role: literal evidence, analogy, human consequence or transition.
+Acquire appropriate real media for factual claims; label reconstruction/metaphor
+when confusion is possible. A generated desk can illustrate indecision, but cannot
+prove an actual person's actions. Let an opening object return changed in context.
+Use a typography takeover for a meaningful turn, then release the screen to imagery.
+
+**Adapt:** Scene scale, contrast, density and pace follow the argument and voice.
+A quiet shot may need a longer hold than a sharp antithesis. Preserve enough of a
+phrase to understand it; text enters in complete meaning units, never broken
+syllables. Use the user's typography and palette for graphics; authentic footage
+keeps its colors unless the project explicitly permits grading. Do not copy source
+movie clips, celebrity claims, music, word count or black/white aesthetic by default.
+
+**Check:** Does each shot explain the adjacent phrase? Is the final image a payoff
+rather than another unrelated background? Are asserted facts supported and quoted
+words accurate? Inspect cuts against the actual waveform/word timings. A blank
+frame can be an intentional reading hold; record it rather than filling it with
+ornament. If the visual logic disappears when captions are removed, acquire more
+specific imagery or restructure the sequence. Music is independent from SFX and
+silence is valid. Follow [audio production](audio-production.md).
+
+## Cinematic type as punctuation
+
+Use a selective word/phrase to turn the argument, not a permanent title over a
+stock loop. Source leads above and `instagram:DZJQm-MgeFL` illustrate changes of
+scale and image/type relationships. Recompose around actual subjects and social
+safe areas. Layering behind a silhouette is optional and must preserve reading;
+no background-removal capability means choosing another composition.

package/skill/editorbrain/references/family-personal.md

@@ -0,0 +1,40 @@
+# Personal story: keep the lived process
+
+Follow [family selection](editorial-families.md). Use when the creator's experience
+or recurring challenge is the story. Do not convert an informational voiceover
+into a first-person claim that the person never made.
+
+## A tangible process with a payoff
+
+**Discovery leads:** `instagram:DYV-3gEty9u` (object/process and human character),
+`instagram:DdKae1xzRao` (personal aspiration, shifting scale and kinetic emphasis).
+Inspect an opening, a process passage and its actual payoff, not only their titles.
+
+**Build:** Inventory genuine moments: decision, attempt, obstacle, correction and
+result. Find the causal thread in source footage/transcript. Keep a recognizable
+object or goal across shots so the viewer knows what is being attempted. Use a
+handheld/POV angle for the actual action; cut back to the person when their reaction
+matters. Compress real repetitive work where authorized, while preserving the
+normal-speed moment that demonstrates success or failure.
+
+**Adapt:** Paper notes, grids, hand-drawn marks and casual type are possible grammar,
+not mandatory decoration. Reflow around faces/hands and retain authentic room,
+object and product colors. A multi-angle grid should reveal distinct parts of the
+same process, not repeat one camera angle four times. Stagger entrances only when
+it improves reading. If the creator wants fixed layout or restrained motion, use
+purposeful cuts instead. Do not invent a setback, success, cost or confession to
+force the arc. An unfinished attempt may honestly end with the next question.
+
+**Check:** Can the viewer name what was attempted and what happened? Does the
+payoff follow from shown footage rather than a text claim? Preserve wanted speech
+and don't cut word attacks/tails. Check retimes against visible action. Keep a
+blooper only when tone and consent fit; no compulsory sales CTA. Distinguish this
+episode's result from a future-series promise. Never reuse a source creator's
+personal story as the customer's own testimony.
+
+## Series continuity without a repeated template
+
+A consistent opening gesture, small episode marker, typography or returning object
+can identify a series. Reuse that grammar and accepted user feedback; derive each
+episode's scene order and pacing from what happened. Save approved style decisions
+through [style creator](style-creator.md), not into the shared family skill.

package/skill/editorbrain/references/family-presenter.md

@@ -0,0 +1,67 @@
+# Presenter explanation: stage the idea around the person
+
+Use when a person's argument is the spine of the video. Follow
+[family selection and context](editorial-families.md). Preserve the argument and
+performance; support is not a requirement to cover the face or decorate every line.
+
+## Integrated collage
+
+**Discovery leads:** `instagram:DZXtFEbKxdb` (argument-led collage and presenter in
+scene), `instagram:DbtWJOztrTO` (semantic imagery with floating narrator),
+`instagram:DbWkY9ZSXtQ` (list leading to a demonstration). Inspect successive
+compositions and the point where images accumulate, replace one another or clear.
+
+**Build:** Give the beat a visual job: context, evidence, metaphor or result.
+Choose and acquire an image/clip that performs that job before designing its frame.
+Position the narrator using its negative space; arrange background → person →
+foreground object only if occlusion explains a relationship. Build an accumulation
+when the idea genuinely adds examples; replace the image when the idea changes.
+Release density when the face or a conclusion should regain attention.
+
+**Adapt:** Layout follows what must remain visible: real interface, face, gesture,
+object and captions. A full rectangle or split screen may fit better than a cutout;
+a circle is not a default improvement. Honor fixed-layout and background-removal
+choices. If a cutout helps, review hair, hands and lower-body edges in motion;
+poor segmentation calls for a different layout. Use subject-relevant imagery,
+not the source reel's mountain, counter, famous face, colors or fixed panel count.
+If no B-roll is wanted, use the allowed graphics or performance; do not reinterpret
+that preference as permission for decorative imagery.
+
+**Check the passage:** Can the viewer explain why this specific resource appears
+at this phrase? Is the person large enough when their expression matters? Does
+movement guide attention without hiding evidence? Compare the rendered layout
+changes to the inspected sequence. If only colors and headings changed, restore
+the mechanism with appropriate resources instead of adding generic boxes.
+
+Recheck captions after **every layout change**, not only on the opening frame.
+A caption inside social safe areas can still cover a mouth after the presenter
+moves into the lower half. Reserve reading space in that composition and wrap
+long phrases into readable lines instead of silently shrinking the font. Choose
+caption breaks within the retained speech; exclude words beyond a shortened cut.
+
+## Contrast and case
+
+**Discovery leads:** `instagram:DbFcdquAiZ1` (antithesis → case → reframing),
+`instagram:Dcz0PDfJxs8` (brand case with authentic posts),
+`instagram:DZJQm-MgeFL` (quantity/quality argument with archive and depth type).
+Inspect how a case enters, takes focus and returns to the narrator's conclusion.
+
+**Build:** Identify the difference the script actually supports. Make alternatives
+visible with comparable examples; give the important case enough scale and time
+to understand its action. Move from broad contrast to specific evidence, then
+return to the person's interpretation. A keyword can enter with the relevant
+idea; it should not substitute for showing the case. Use foreground/depth text
+only when reading and the person's silhouette remain clear.
+
+**Adapt:** Distinguish actual posts, footage and data from a designed analogy.
+Choose images through [media acquisition](real-media.md), keeping provenance and
+permissions. Generated metaphors cannot prove factual outcomes. In a restrained
+brief, one fair comparison may do the work; in a richer brief, vary evidence and
+scale with the argument. Preserve required points, not an imposed source duration.
+Do not convert every ending into a sales CTA or import the source's claims.
+
+**Check the passage:** Does the case answer the question, and does the conclusion
+follow from it? Could both alternatives be read? Are eyes, hands and captions
+unobstructed? When the case needs movement, a poster is insufficient: use the
+relevant clip or acknowledge the limitation. Keep approved montage timing and
+update affected graphics/audio if a cut changes; use the shared review workflow.

package/skill/editorbrain/references/first-edit.md

@@ -13,7 +13,7 @@ Use this only when the user's environment or project is not ready. Do not re-onb
 
 ## Make defaults meaningful
 
-Inspect the current request and material first. Populate the existing brief and `project.json.script` from the user's actual content, not placeholder copy. Establish goal, audience and destination from context; ask only for consequential missing choices. Keep unspecified brand colors/fonts unset rather than inheriting reference colors or the developer's personal brand. Any provisional visual choice belongs in the project direction until the user makes it reusable. Keep adaptive style files free of a predetermined layout, engine, component or technique. First-use setup must not turn an onboarding favorite into the required format of every video.
+Inspect the current request and material first. Populate the existing brief and `project.json.script` from the user's actual content, not placeholder copy. Establish goal, audience and destination from context; apply questionPolicy to consequential missing choices; autonomous records reversible assumptions and leaves indispensable inputs pending without questions. Keep unspecified brand colors/fonts unset rather than inheriting reference colors or the developer's personal brand. Any provisional visual choice belongs in the project direction until the user makes it reusable. Keep adaptive style files free of a predetermined layout, engine, component or technique. First-use setup must not turn an onboarding favorite into the required format of every video.
 
 Use the selected brand's `brand.md`, `design.md`, `tokens.json`; the style's `style.md`, `effects.md`, `music.md`; and the project's `brief.md` and `direction.md`. The generated output profile is editable: 9:16/30fps is a starter, not a requirement for every video. Discover the user's actual target and available tools before rendering. Read the workspace file map when editing schemas or selecting another style.