editorbrain 0.30.0 → 0.32.0

package/skill/editorbrain/references/storage-and-previews.md

@@ -6,6 +6,10 @@ command availability first; older CLI versions do not include these commands.
 Keep source footage and masters local unless the user asks to upload them.
 `storage status` / MCP `storage_status` reports actual workspace capacity and
 reservations. The current upload limit is 90 MiB **per file**, separate from quota.
+Compare the actual file bytes with capacity minus used and reserved bytes before
+uploading. If it does not fit, inspect eligible cleanup candidates or prepare a
+smaller copy without sacrificing necessary legibility. Do not change a plan/quota
+or bypass protected files. Cleanup still follows the authorization below.
 
 For review, prepare a separate small copy:
 ```sh
@@ -21,10 +25,18 @@ conversion. Never overwrite or delete the original to save space.
 When sharing is authorized, upload the inspected copy with `assets upload <file>
 --purpose preview --source-sha256 <original-hash>`. Use its **own** hash when
 registering a review/sample. Do not present preview verification as master QA.
+`--source-sha256` is optional and must identify different source bytes; omit it
+when uploading the already prepared file without a distinct source asset.
 New final uploads use `--purpose final`; absent purpose protects as original.
 Re-uploading identical bytes reuses the previous category; it cannot relabel a
 protected master as removable. There is no automatic server compression.
 
+Prefer H.264/AAC MP4 for ordinary web/mobile review; preserve special formats only
+when the deliverable needs them. After registering the sample, open its actual
+project page in the correct workspace and verify visible playback and time
+progression. A successful upload, loaded metadata or local decode does not prove
+the hosted player works. Report devices or audio review not actually tested.
+
 Cleanup is optional and separate from editing. Show exact names, sizes and IDs,
 obtain explicit approval, then owners may use `storage cleanup --ids <sha>,<sha>
 --confirm` (max 20), or the web storage panel. Only unused previews/temporaries can

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
@@ -111,3 +113,27 @@ See [memory and review](memory-and-review.md) for memory schemas, version restor
 ## Optional audio production context
 
 Brand `audio.json` and project `audio.json` are selected optional sources, validated and hashed by resolve/pull, exposed as `audioProduction` in resolved/workflow context, and included in handoffs. See [audio production](audio-production.md) only when configuring voice, SFX banks/exclusions or loudness. They contain portable IDs and preferences, not provider credentials or machine-specific paths. Existing projects need no migration. Detailed provenance and QA reports stay private in `.editorbrain-local/` and are read on demand; merely creating a JSON under `videos/` does not add it to resolved context.
+
+## Creative decision ownership
+
+The optional editorial profile field `creativeDirection` in brand `design.md`
+is `automatic` or `guided`; `project.json.creativeDirection` overrides it for
+that video. `resolve`, workflow context and `editorialSnapshot.creativeDirection`
+return the effective mode and its source (`project`, `brand`, or `implicit`).
+Omission preserves legacy guidance, never silently opts a brand into automatic.
+The current explicit task still governs; project changes do not overwrite the
+brand. Both modes inspect library evidence and adapt to the actual material.
+Automatic fills unspecified aesthetics; guided starts from saved choices.
+Neither overrides required tokens, media/audio restrictions, language, review
+or spending. This field does not replace `freedom` (visual consistency),
+`motionSelection` (motion taste), or `reviewMode` (when to ask for review).
+
+`creativePreferencesReviewed` in the same profile records explicit category
+confirmations (including deliberate delegation). The shared guide lists valid
+categories. Partial onboarding intake updates accumulate them; `null` clears
+them. Populated preference fields do not imply confirmation. Effective direction
+includes `configuration: {status, pending}`; explicit guided brands must finish
+pending categories through [onboarding](onboarding.md) before editing. Automatic
+and legacy unspecified brands do not require that checklist. A project override
+does not enroll or complete brand onboarding; an automatic exception skips that
+checklist for the selected video without deleting the saved brand state.

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.

package/skill/editorbrain-motion/SKILL.md

@@ -17,13 +17,21 @@ Read the sibling [EditorBrain contract](../editorbrain/AGENTS.md) once in the ac
 
 Use `resolve_project` / `editorbrain resolve <id>` and `check_workflow` / `editorbrain workflow check` for current context. Reuse valid results already obtained. Read `tokens`, `tokenSources`, warnings, conditional `context.memory.confirmed`, effective `mediaPreferences` and the current member's integration checkpoint. Compare workflow `version` and `contextVersion` at existing checkpoints before proposals, paid generation and full rendering; fetch only changed relevant context. Do not add another approval cycle or reload every guide.
 
-Apply the implemented token precedence: skip `example` tokens; apply style tokens, then brand tokens over matching style tokens, then reasoned project overrides. Changing an effective `required` token requires an intentional, user-supported exception with `overrideRequired: true`. Adapt incompatible techniques; never silently substitute a required color/font. Read [workspace files](../editorbrain/references/workspace-files.md) when resolving conflicts or saving changes. Examples, demos and provider defaults supply no customer palette, typography or preferences. Apply confirmed memory at its stated scope; prose memory cannot bypass required tokens.
+Use the resolved identity without applying a second precedence order. The shared
+[decision ownership](../editorbrain/AGENTS.md#decision-ownership) governs this
+specialty; [workspace files](../editorbrain/references/workspace-files.md) owns
+token precedence and explicit project exceptions. Consult it for conflicts or
+changes. Adapt techniques to the effective constraints. Proposed changes to the
+story, identity or approved timing return to the project direction with their
+reason before dependent work; examples and provider defaults cannot authorize them.
 
 Read [media preferences](../editorbrain/references/media-preferences.md) when interpreting saved choices. Honor exclusions, disabled categories and authorized exceptions; do not force disabled motion. `motionSelection` governs scene selection; `motionProduction` governs production preference, independently. A `code` preference does not authorize a paid AI fallback. Fetch only the selected recipe/version. Before generation, verify the session tool/model and existing spending authorization using [integrations](../editorbrain/references/integrations.md). Declared access or a preference is not a working connection.
 
 ## Design and execute the scene
 
-For a real subject or demonstration, establish the authentic media first using the host's image/video search, browser and user footage. Follow [real media and evidence](../editorbrain/references/real-media.md) when sourcing. Code-based production can composite real photos, captured interfaces and footage; it does not require drawing every element. Animate around inspected evidence; a code animation or generated likeness cannot substantiate a real person, event or product behavior. Abstract explanations and labelled illustrations can still start with authored/generated motion.
+In a full-video edit, reuse the direction and inspected **edited-video references** that explain why this scene needs animation. If they are missing for a new or changed direction, follow [editorial evidence](../editorbrain/references/editorial-evidence.md) before choosing motion. Motion search supplies implementation mechanisms, not evidence that the whole edit fits. For a standalone animation, explicit template request or scoped correction, work from the relevant brief and existing evidence without imposing a new full-video search.
+
+For a real subject or demonstration, establish authentic media from permitted sources first, using user footage and available web tools as allowed. Follow [real media and evidence](../editorbrain/references/real-media.md) when sourcing. Code-based production can composite real photos, captured interfaces and footage; it does not require drawing every element. Animate around inspected evidence; a code animation or generated likeness cannot substantiate a real person, event or product behavior. Abstract explanations and labelled illustrations can still start with authored/generated motion.
 
 Describe each meaningful shot through its intention, visible entry state, action/change, readable or perceptible hold, and exit state. Connect timing to the actual voice, action or music when used. Use the project's existing plan; keep detailed shot records local. There is no required shot count, effect, provider, pilot or sound layer.
 
@@ -31,6 +39,8 @@ Design the visual action for this video's specific message before selecting a co
 
 Separate resolved graphic identity from authentic material: text/graphics use brand roles; footage, skin, product colors, screenshots and logos retain their authentic identity unless the approved direction changes them. Distinguish real interface states from labelled illustrative UI. Preserve the selected style's mechanism while adapting subject, layout and timing.
 
+Before authoring substantial code motion, make a bounded `motion scenes` lookup for the required action and inspect a promising mechanism, if accessible. This is source research for code production, not a competing engine or a requirement to use a template. Reuse valid research during corrections. A bad preset claim may need new copy while its visual mechanism remains useful; reject mechanisms that do not fit.
+
 Choose a feasible method per shot, respecting production preferences:
 
 - **Code/compositing:** read [motion with code](references/code-motion.md) for precise states, typography, diagrams, interfaces or repeatable transitions.
@@ -39,13 +49,22 @@ Choose a feasible method per shot, respecting production preferences:
 - **Generated clips:** read [generated motion](references/generated-motion.md) for material/character consistency, organic movement and continuity.
 - **Hybrid:** use both where needed; keep exact text, values, logos, interface states and continuity-critical objects under explicit control.
 
-Use the engine/provider's real capabilities and relevant skill. The component preparer supplies editable HTML scenes, not an encoded video or generation API. Rendering still uses the available local tools. Test difficult mechanisms when uncertainty warrants it, reusing existing approval.
+For a fully animated/faceless piece with a feasible code route, a JavaScript
+composition can coordinate the whole sequence on one deterministic master clock,
+including photos, generated imagery, footage, masks, camera and audio cues.
+Plan the changing scenes and their handoffs, not a fixed slide layout with every
+element fading in. An encoder such as FFmpeg exports/mixes the result; it does not
+choose its motion. Respect an explicitly chosen engine and use other tools where
+they solve a real production need. Code availability alone does not establish
+that this route is best for every user or that its output is good animation.
+
+Use the engine/provider's real capabilities and relevant skill. The component preparer supplies editable HTML scenes, not an encoded video or generation API. Rendering still uses the available local tools. When the edit prioritizes elaborate motion or faithful transfer, render its most demanding short passage before extending that approach to the whole piece. Compare the actual action, staging, readable holds and transitions with the inspected reference; fix lost mechanisms before adding decoration. This internal check reuses existing approval, including direct mode, and does not require a new customer decision.
 
 ## Review and preserve
 
 Review important states and transition strips, then actual motion and relevant audio. Recompose and verify each requested ratio. SFX remain optional and must respect exclusions; timeline cues or meters do not prove audibility. For substantial motion/audio work use [production and review](../editorbrain/references/production-and-review.md) and the review order in [motion craft](references/motion-craft.md), reusing checks already performed.
 
-Check whether the viewer can tell what changed and why from the animation itself. If removing the moving graphic leaves the explanation unchanged, reconsider whether the motion is only decoration. Do not treat passed font, bounds, seek or encoding checks as artistic approval.
+Check whether the viewer can tell what changed and why from the animation itself. If removing the moving graphic leaves the explanation unchanged, reconsider whether the motion is only decoration. Compare the sequence with the inspected mechanisms and any applicable user-approved quality sample using [production review](../editorbrain/references/production-and-review.md). Do not treat passed font, bounds, seek or encoding checks as artistic approval.
 
 Tie findings to output hash/version and time; distinguish observed, inferred and designed decisions. Frames cannot establish motion, and silent inspection cannot establish sound quality. Report uninspected modalities explicitly. After a local correction, recheck affected events and the delivered whole.
 

package/skill/editorbrain-motion/references/code-motion.md

@@ -10,6 +10,13 @@ A scene needs a meaningful state change: reveal a relationship, assemble a proce
 
 Use short text as part of the action where appropriate: a request can become a constraint, a duration can become a calendar interval, or a word can become a visible boundary. Preserve object identity and show the consequence of each action. Design anticipation, action and a perceptible hold around the beat, rather than dividing every scene into equal steps. Camera moves, masks, deformation and light/dark changes are options, not a required effects checklist. [Motion craft](motion-craft.md) gives the shot intent, starting values and common failures.
 
+Let media participate in the action: an image may fill the frame, become an
+object inside a larger system, then reveal a detail. For example, separate
+information fragments can gather into a summary that carries into the next
+beat. This illustrates a mechanism, not required imagery. When two scenes share
+an object, match its crop, bounds, anchor and state at the handoff; otherwise a
+continuous camera move can hide an accidental jump. Inspect adjacent frames.
+
 Use a compact shot record when the existing plan lacks this detail:
 
 | Field | What to record |
@@ -49,6 +56,11 @@ Use sparse beat frames to inspect composition and dense transition strips around
 
 Recompose each requested ratio: adjust hierarchy, line breaks, staging, asset crop and trajectory as necessary. Generate evidence from each output, since a horizontal pass does not validate a vertical crop. Watch the final export for continuity, pace and closure; listen if audio is present and the modality is available. Follow the shared [production review](../../editorbrain/references/production-and-review.md) for delivery checks.
 
+Compare editorial quality there as well: successful seeks, easing functions and
+font bounds do not show that the scene explains its message or meets a relevant
+approved sample. Review the composite, including imagery and occlusion, not just
+isolated text boxes or the source code.
+
 Keep localized findings concise: `output hash/version → time/interval → observed defect → evidence → correction`. A contact sheet plus transition strips and playable output can be a local review artifact; no particular HTML format or helper is required. Preserve editable sources, asset hashes, engine details and final timing locally. Recheck the modified interval and final delivery without reopening approved unrelated scenes.
 
 For frame boundaries and supplied geometry, read [targeted motion review](../../editorbrain/references/motion-review.md). It provides an optional CLI sampling plan and collision candidates; it does not replace watching motion.