editorbrain 0.29.1 → 0.31.0

package/skill/editorbrain/references/search-brief.md

@@ -40,8 +40,22 @@ editorbrain search brief --file .editorbrain-local/my-video/search-brief.json --
 
 Search uses a mechanism query plus source meaning/constraints for styles, and specific event queries for details. It returns up to eight styles and six candidates per event query, with pinned source documents and retrieval ranks. These are candidates, not eight recommendations to show the user. Default `detail: "summary"` preserves fit constraints, ranks, IDs and source hashes while omitting full recipes. Read pinned documents only for the shortlisted examples. `detail: "full"` (CLI `--details`) returns full indexed payloads when needed, not additional search results; keep large responses in private local files. Check `evidenceCoverage` before assuming completeness. Embeddings may still use a provider; no source video upload or generative model analysis/review occurs in this path. Only the text needed for embeddings is sent to the embedding provider. Telemetry measures server calls, not your host agent's token consumption.
 
-Inspect the best few using `get_reference` / `library get`, then `view_example` for actual returned image hashes. Use `get_reference_media` for relevant motion/audio intervals. The search response supplies metadata/instructions; it does not automatically show images in the host. Keep evidence source hashes. Never fabricate media hashes, links or timestamps from a ranking.
+Survey the returned styles and event candidates by the needs they cover; then inspect selected examples using `get_reference` / `library get` and `view_example` for actual returned image hashes. Use `get_reference_media` for relevant motion/audio intervals. The search response supplies metadata/instructions; it does not automatically show images in the host. Keep evidence source hashes. Never fabricate media hashes, links or timestamps from a ranking.
 
-Choose based on narrative function, required brand rules, available resources, readability, tone and continuity. Record what you retain, adapt and omit, with a source hash and inspected interval for each borrowed mechanism. Identify newly designed choices separately. Choose a coherent direction, not a collage of the top results; use a fixed component only if its action and composition fit. No obligation to copy a whole reference style or add animation to each beat. If there is no fit, say so and refine one mechanism query while keeping constraints; avoid endless searches or claiming the top score proves quality. Broaden beyond the subject when transferable techniques exist in other niches.
+Newer services include a bounded leading rule for style coherence/adaptation and event `preserve`/`change`, alongside exclusions. `omittedFields` also names partially returned arrays: these cues are not complete recipes. For the selected direction, read its pinned analysis and inspect the relevant sequence before implementing; never treat a short description such as “light cards” as the whole style. Older services may omit positive cues entirely: follow `readSource` instead of interpreting absence as no adaptation guidance.
+
+Before turning the shortlist into a design, use [editorial evidence](editorial-evidence.md) to record the inspected mechanism, its project beat and preference-aware adaptation. This is the primary editing library; motion examples complement the resulting direction.
+
+Choose based on narrative function, required brand rules, available resources, readability, tone and continuity. Different beats can borrow different mechanisms from several styles while sharing one identity. Record what you retain, adapt and omit, with a source hash and inspected interval for each borrowed mechanism; identify newly designed choices separately. Use a fixed component only if its action and composition fit. No obligation to copy a whole reference style or add animation to each beat. If a consequential need remains uncovered, refine that mechanism query while keeping constraints; stop when the needed evidence is usable rather than searching indefinitely. Broaden beyond the subject when transferable techniques exist in other niches.
+
+For example, a fast faceless tutorial may need spatial type for the hook, an image
+collage to show overload, a legible real demonstration and an object-driven
+transition. Use the first request's style query for the overall direction and its
+two event queries for the most important distinct needs. A follow-up may cover
+the remaining gap with `mode: "events"`; retain the same inspected source and
+constraints. Do not invent a larger event array or treat `--details` as more
+candidates. Reuse valid evidence, cache overview sheets locally and open only the
+source intervals/code needed for the chosen mechanisms. A simple scoped edit may
+already have enough evidence and require no extra query.
 
 If this tool is absent, report the installed version limitation, inspect sources yourself and use explicit library lookup if useful. Do not silently upload material to the older server-analysis method. A video your host cannot inspect requires accessible media tools or a disclosed limited plan, not invented observations.

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/studio.md

@@ -1,6 +1,8 @@
 # EditorBrain Studio — optional creative tools
 
-Load this only when creating/transcribing a resource. Check `editorbrain help` or MCP tool discovery first: earlier clients/services may not support Studio. `studio catalog` / `studio_catalog` reports availability, ownership and creative credits. These credits are separate from library searches. Do not request provider keys or activate personal integrations for built-in tools.
+Load this only when creating/transcribing a resource. Check `editorbrain help` or MCP tool discovery first: earlier clients/services may not support Studio. `studio catalog` / `studio_catalog` reports availability, per-tool `tools[].canSpend` and creative credits. Scribe accepts editing access; Prism/Vox/Aura require a workspace owner (including an owner’s editor-scoped connection). Readers cannot start jobs. On older servers without per-tool permissions, use the legacy catalog `canSpend` and report authorization failures. These credits are separate from library searches. Do not request provider keys or activate personal integrations for built-in tools.
+
+When the user explicitly requests Scribe or another tool, keep that choice. If unavailable, out of credits or unauthorized, report the specific blocker before changing methods; an existing local model is not an approved substitute. Continue independent work, but do not finalize speech cuts/captions from a fallback transcript as if the requested transcription had completed. Provider balance and EditorBrain credits are separate, and reconnecting cannot replenish either. A completed transcript still needs editorial review: preserve intended ideas and verify speech joins against the source.
 
 ## MP4 → Scribe
 

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

@@ -111,3 +111,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-motion/SKILL.md

@@ -17,20 +17,30 @@ 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. 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.
 
-Design the visual action for this video's specific message before selecting a component. For authored motion, create the object relationships, staging and choreography the scene needs; changing labels and colors alone is not bespoke animation. Let composition evolve when the action needs it. A permanent title, illustration and list is an explainer layout, not the default for motion graphics.
+Design the visual action for this video's specific message before selecting a component. For authored motion, create the object relationships, staging and choreography the scene needs; changing labels and colors alone is not bespoke animation. Let composition evolve when the action needs it. A permanent title, illustration and list is an explainer layout, not the default for motion graphics. For any method, [motion craft](references/motion-craft.md) gives the four-line shot intent, starting values for timing, staging, transitions, camera, type and ratios, and common failures; the request, preferences, output profile, style, approved direction, brand tokens and measured readability override its numbers.
 
 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), reusing checks already performed.
+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/authored-scenes.md

@@ -5,10 +5,10 @@ Use when a scene needs a visual mechanism (an object transforms, a structure fal
 ## Retrieve only what you need
 
 1. **Search by action.** `list_authored_scenes` / `editorbrain motion scenes "depender de un solo cliente"` ranks examples by mechanism, uses across niches and presets. Describe the action and change, such as "un total que se arma por partes". A different demo niche is not a reason to discard a mechanism. Default six compact results; reuse `nextCursor` as `after` / `--after` for the same query. This is weighted lexical retrieval, not a creative recommendation or semantic video analysis.
-2. **Look before reading.** For the strongest candidates (usually three, expand if unclear), request `first` and `last` in the project's ratio. MCP: `get_authored_scene_preview`, passing candidate `id` as `sceneId`, preserving `version`, and mapping the project format to `ratio` (`16:9` → `wide`, `1:1` → `square`, `9:16` → `tall`); use `kind: "first"` or `"last"`. CLI: `editorbrain motion preview <id> --scene-version 1.1.0 --ratio tall --preview-kind first`. `firstIsFrame1: false` means the image is the first informative state, not the literal first frame; inspect the returned time/frame. These images establish states, not motion, pacing or sound.
-3. **Read one card and choose an adaptation.** `get_authored_scene` / `editorbrain motion scene <id> --scene-version 1.1.0` gives the universal mechanism, use/not-for, timing, limits, presets and pinned source hash. If a preset fits the topic better, inspect its keyframes with `preset: "<name>"` / `--preset <name>`. Presets support first/last only; they do not have their own video preview. Pick by the beat's action and constraints, not rank alone.
+2. **Look before reading.** For the strongest candidates (usually three, expand if unclear), request `first` and `last` in the project's ratio. MCP: `get_authored_scene_preview`, passing candidate `id` as `sceneId`, preserving `version`, and mapping the project format to `ratio` (`16:9` → `wide`, `1:1` → `square`, `9:16` → `tall`); use `kind: "first"` or `"last"`. CLI: `editorbrain motion preview <id> --scene-version <version> --ratio tall --preview-kind first`. `firstIsFrame1: false` means the image is the first informative state, not the literal first frame; inspect the returned time/frame. These images establish states, not motion, pacing or sound.
+3. **Read one card and choose an adaptation.** `get_authored_scene` / `editorbrain motion scene <id> --scene-version <version>` gives the universal mechanism, use/not-for, timing, limits, presets and pinned source hash. If a preset fits the topic better, inspect its keyframes with `preset: "<name>"` / `--preset <name>`. Presets support first/last only; they do not have their own video preview. Pick by the beat's action and constraints, not rank alone.
 4. **Validate the motion.** Watch the selected base video's preview (`kind: "video"`, the default). Compare its transformation and timing with the intended beat before committing to its code. Keyframes and the base preview do not certify the preset or a customer-brand render.
-5. **Source and adaptation.** Request `get_authored_scene_source` with the exact ID, version and bundle SHA-256, or `editorbrain motion source <id> --scene-version 1.1.0 --out .editorbrain-local/new-scene.tar.gz`. Downloads require login, verify size/hash, preserve existing files and never extract or execute automatically. Start from the closest `adapt/<name>.json` overrides when present; replace demo values and bind the current project below. Edit code where the card says parameters cannot express the needed change; author a new scene when none fits.
+5. **Source and adaptation.** Request `get_authored_scene_source` with the exact ID, version and bundle SHA-256, or `editorbrain motion source <id> --scene-version <version> --out .editorbrain-local/new-scene.tar.gz`. Downloads require login, verify size/hash, preserve existing files and never extract or execute automatically. Start from the closest `adapt/<name>.json` overrides when present; replace demo values and bind the current project below. Edit code where the card says parameters cannot express the needed change; author a new scene when none fits.
 
 The base commands require CLI 0.27.0+. Ranked catalog 1.1.0 and `first|last`/`--preset` require CLI **0.28.0+**, or an MCP server advertising these fields and returning 1.1.0. Check the actual tool schema and returned version; do not send unsupported fields to older servers. CLI 0.27.x and pinned 1.0.0 still use literal search and `video|poster`; use their cards and videos instead of inventing missing keyframes. There are 45 mechanisms in 1.1.0 and 33 in 1.0.0. `motion list/get/prepare` remains a separate component catalog.
 
@@ -24,4 +24,12 @@ Material colors, heatmaps, illustrations and data series can have separate param
 
 `?demo=1` is for inspecting the original reference only. Production requires complete project binding; missing fonts/assets, invalid theme/ratio and unsupported voice/music time scaling must fail rather than silently use a personal identity. Supplied scenes are opaque, not transparent overlays. Do not reinterpret one scene's fixed item count, timing or font as a universal EditorBrain requirement.
 
-Check source/preview provenance and runtime diagnostics, important states and transitions, then actual motion/audio in the adapted output. Existing previews refer to original source; the guarded portable runtime is separately hashed. Technical validation does not prove creative quality or successful transfer. Both catalogs exclude all personal `human-computers` reel versions.
+Check source/preview provenance and runtime diagnostics, important states and transitions, then actual motion/audio in the adapted output. Judge holds, text fit, ratio composition and opening/closing frames with this project's copy and timing using [motion craft](motion-craft.md); the demo's values do not establish them. Existing previews refer to original source; the guarded portable runtime is separately hashed. Technical validation does not prove creative quality or successful transfer. All catalogs exclude all personal `human-computers` reel versions.
+
+A catalog lookup alone is not visual adaptation. When a selected mechanism needs code-level adaptation, inspect its pinned source and explain what it contributes to this scene (e.g. camera travel, branching or information transforming into an output). Bind the user\'s material, timing, palette and layout preference. Complexity is justified by the explanation, not by a required number of effects. Do not equate recoloring the demo with editing the user\'s video.
+
+Catalog 1.2.0 requires CLI 0.30.0+ or an MCP server returning 1.2.0. Pass the `version` returned by each result in place of `<version>`; never upgrade a pinned result silently. There are 123 mechanisms in 1.2.0, 45 in 1.1.0 and 33 in 1.0.0. `inheritedBundleVersion` (1.0.0 or 1.1.0) identifies an unchanged archive: its internal manifest keeps that version while the retrieved card adds current discovery guidance. Verify its advertised hash and preserve its provenance.
+
+## Do not confuse discovery with automatic brand transfer
+
+The catalog selects mechanisms, not a universally fitted layout. Bind contrasting foreground/background pairs (including scene-specific roles such as `onAccent`); assigning the same approved color to every role can make text unreadable. Font changes and duplicate palette entries can require source/layout changes. Keep warning checks enabled. Recompose small labels, paths and glyph spacing instead of silently changing the user's font or ignoring a rejected render. Original preview approval does not approve a different brand, preset or format.

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

@@ -8,7 +8,14 @@ Start from the shot's specific visual action. Consult the compact [component lib
 
 A scene needs a meaningful state change: reveal a relationship, assemble a process, isolate evidence, compare alternatives or resolve a question. Decide what the viewer should notice before selecting a transition. A moving card is useful only when its change of position, scale or emphasis communicates that intention.
 
-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.
+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:
 
@@ -45,10 +52,15 @@ For a new temporal implementation, sample the same important state directly and
 
 ## Review the mechanism, then the export
 
-Use sparse beat frames to inspect composition and dense transition strips around risky intervals to inspect state changes, occlusion, overlap, easing and object persistence. Choose times from the actual motion; a universal sampling count can miss a fast defect. Check sufficient readable hold at the intended viewing size. Automated bounds can detect some clipping; they cannot establish legibility or editorial meaning.
+Use sparse beat frames to inspect composition and dense transition strips around risky intervals to inspect state changes, occlusion, overlap, easing and object persistence. Choose times from the actual motion; a universal sampling count can miss a fast defect. Check sufficient readable hold and text size at the intended viewing size; [motion craft](motion-craft.md) lists starting values and a review order. Automated bounds can detect some clipping; they cannot establish legibility or editorial meaning.
 
 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.

package/skill/editorbrain-motion/references/component-library.md

@@ -47,6 +47,6 @@ The output directory must be new. Preparation validates input before writing; it
 
 Open the HTML preview. For external frame capture use `?capture=1`, wait for `window.__ready`, fail on `window.__motionError`, and call `window.renderAt(seconds)` explicitly. Query `window.getMotionDiagnostics()` for measured text overflow and readiness. Capture `#stage` only at the project's actual dimensions; encode with the available renderer. `prepare` alone does not create an MP4.
 
-Read title, captions and transitions at final display size. Inspect meaning, pacing and hierarchy, not only bounds. Test actual requested ratios, long text and selected brand colors. A foreground/background contrast failure requires an intentional project decision, never silent recoloring. `motion: "reduced"` uses static states/cuts. The standalone preview starts paused; a custom autoplay wrapper must honor the viewer's reduced-motion preference.
+Read title, labels/details and transitions at final display size; [motion craft](motion-craft.md) gives starting values for their reading time and size. Inspect meaning, pacing and hierarchy, not only bounds. Test actual requested ratios, long text and selected brand colors. A foreground/background contrast failure requires an intentional project decision, never silent recoloring. `motion: "reduced"` uses static states/cuts. The standalone preview starts paused; a custom autoplay wrapper must honor the viewer's reduced-motion preference.
 
 Scenes are silent. Integrate approved voice, music or SFX separately on a shared timeline and review audible output. Save only the chosen component id/version, relevant bindings and continuation notes in the portable direction; keep code, embedded assets, frame strips and detailed QA local. Do not send embedded files or implementation source back through model context.

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

@@ -0,0 +1,79 @@
+# Motion craft
+
+Read when designing, adapting or reviewing an animated scene with any method. These starting values come from EditorBrain's own code-drawn library scenes and a few reference analyses, not yet validated on customer projects or phones; sound was checked only as data. They are judgment, not a template, effects checklist or quality score. The user's current request, effective media/audio preferences (including reduced or disabled motion and on-screen text density), the output profile, the selected style's `effects.md`, the approved direction, brand tokens and readability measured in this output override every number; a value outside a range is a reason to look, not an automatic defect.
+
+Pixels are per 1080 px short side at 30 fps; scale with resolution and halve per-frame values at 60 fps. Drift is the scale or position change over a hold, as a percentage of the frame.
+
+## Intent before look
+
+State four lines per meaningful shot before choosing a component, effect or palette:
+
+1. **Understand:** the sentence the viewer must get, with its real numbers.
+2. **Action:** the visible action that demonstrates it, such as an object performing the comparison.
+3. **Consequence:** what visibly changes because of it, in the same shot.
+4. **Exit:** the final state and what carries into the next shot.
+
+They sharpen the intention and action of the motion skill's shot description (entry, hold and exit still apply) and fit the [code motion](code-motion.md) record; they are not a schema. If the viewer would understand the sentence equally without the action, reconsider whether the motion is decoration and restage.
+
+Explanatory mechanism comes before surface treatment (palette, texture, glow); the selected style's own mechanisms still apply. For code/compositing, derive geometry, counters, labels, camera targets and cues from one data model ([code motion](code-motion.md) covers deterministic time) and recompute every figure. When a beat reads weak, change travel, scale, composition or timing before adding effects.
+
+**Honest data.** The data must demonstrate the claim (a difference of about 10 % or more, a threshold actually crossed) or the payoff changes; keep the before state credible. Map quantity to the visible dimension (area by √value), compare on one scale, clock and cost basis, and declare exaggerated or non-linear scales on screen. Leaders end at measured endpoints, emphasis follows the message target rather than the maximum, and data-dependent wording follows the computed values.
+
+## Starting values
+
+**Easing and springs.** No linear spatial motion: ease-out for entrances, in-out and arcs for travel; interpolate data values monotonically. Start springs from rest: no jump after a standstill (one fix capped that first step near 30 px) and no frame stepping several times its neighbors. A damping ratio ζ ≈ 0.8 gives about 1.5 % overshoot (convert to the engine's stiffness/damping/mass) over a 0.22–0.26 s main travel; large elements overshoot 2 % at most, and springs settle within their beat. Anticipate major moves with a 1–8 % counter-move (15–20 % for large rotations). Reveals take 0.18–0.45 s with a strong ease-out; related elements stagger 2–4 frames, secondary parts follow through 2–4 frames late, and edges on separate springs stretch and catch up. Squash only the hero, by 2 % at most. Large elements stay well under about 140 px per frame; above about 100 px per frame add directional blur (ghosts only on small objects, never over text). For exact endpoints, see [targeted motion review](../../editorbrain/references/motion-review.md).
+
+**Staging and holds.** One primary move and focal point at a time; dim the rest 40–60 % and start the next move at 80–90 % settled. Hold 0.4–0.8 s after intermediate payoffs and 1.5–2.5 s at the end of a standalone piece or before a hard end (under 1.2 s is a warning); a shot that hands off, or an insert under continuing voice, keeps its readable hold and designs its exit. Outside planned holds, over about 1 s with no readable change and nothing else carrying the beat (narration, action) is a dead-air candidate; keep holds alive with 0.5–2 % drift, never above 3 %, unless motion is reduced or disabled. Nothing appears, disappears or swaps for one unintended frame; deliberate cuts, stepped motion and reduced-motion states are exempt. Switch layers on time, never on a spring threshold. Keep full-frame flashes to three per second or fewer, timed in seconds; a count does not certify photosensitivity safety.
+
+**First and last frames.** Shots enter already in motion unless stillness is the design or motion is reduced. When the first frame may be seen alone (autoplay, preview, thumbnail), compose it with subject and title present. Do not reserve visible holes; bring later content in from an on-screen object or a motivated pull-back, and show an empty container only when its emptiness is the information (about 0.25–0.3 s). When a piece or beat closes, end on a designed state: scaffolding gone, deformations eased back.
+
+**Payoff.** Design a separate end-state layout, not the first layout minus elements: the answer at least as large as the setup figure, about twice its neighbors and legible at rest without a push. During action keep the protagonist near 25 % of frame height in 16:9 and 30–40 % in narrower ratios. A measuring gesture landing on the computed value makes a strong payoff; craft must not delay or shrink the answer.
+
+**Object-driven transitions.** Keep one protagonist and change its function: a row becomes a ticket, a total a stamp. Leave states accelerating: content out, container moves and settles, content in. Move the same object between layouts rather than fading one out and another in; replace busy crossfades and hue tweens with a wipe, mask or occluder starting at the cause. Causes precede effects: objects lead their labels, counters change when a visible carrier lands, a source shows the gap left behind, and a state a transition introduces persists until another removes it.
+
+**Camera.** Without style direction, push in on one subject and pull back to show the system; avoid moves that only add energy. Interpolate zoom in log space. Emphasis pushes start around 1.4–4.5 % and follows around 1.3–1.75×, lower in 9:16; if cropping would force a push below about 1.15×, dim the rest or scale the focal element instead. Pans stay under about 25 px per frame with continuous velocity and finish 0.15 s before cuts. At every hold, each label and title is wholly inside the safe margin or wholly off-frame; text that must not crop lives in screen space and crosses the frame edge only while moving. Start a beat once its element is framed.
+
+**Type as objects.** Unless the type is the action (kinetic type, beat-locked or word-synced words, line or letter mask reveals), move phrases or lines as blocks with one behavior each; text exits before its container moves and returns after it settles. Fit text at its final rendered size and font settings: shrink to the size floor (see Ratios), then two balanced lines, then a short alternate; never truncate a number. Same-role labels share the smallest fitted size, and anything placed or animated from a text block follows its measured line count. Size masks from measured ink with descender and accent room; test g, j, p, y, ¿, ¡, Á, É, Ñ and currency in the actual fonts, and never synthesize italics. Use tabular figures for changing numbers, one locale-aware formatter (no −0, singular and zero forms), no-break spaces before units, no orphaned units, and differences from the rounded values shown; rolling numbers show each value 0.25 s or more.
+
+**Text over imagery and color.** Choose the text color among the resolved brand text roles by measured contrast with the actual backdrop; if no permitted role passes, treat it as a project decision (see [component library](component-library.md)), never silent recoloring. Over footage or busy texture, small text gets a scrim, veil or knockout band, and HUD readouts or values in flight an opaque plate; a translucent plate must not show text behind it. Key text ends at 4.5:1 or more. Temporary dims, veils and ghosts exit before the hold; one accent per meaning. Derive shadows, highlights and flashes from the palette's luminance rather than fixed values.
+
+**Labels and drawn objects.** Place labels, stamps and resting props against everything printed (text, credit, HUD, moving props and their rest poses) at every beat and ratio. Anchor stamps to the object's drawn bounds, not a data level; no decorative impact covers primary text; leaders never cross text. Overlaps happen only in motion, for about 0.4 s or less. Name each hero object from a small grayscale still at its smallest size and ask what else it could be; give it defining cues (edge, binding, cap, sheen), one light direction and highlights that add light rather than desaturate; textures move with their object, and decorative strokes never look like data marks.
+
+**Copy and density.** About 3–4 words per beat, a new idea every 1.5–2 s, and each text fully visible 0.6 s plus 0.25 s per word beyond three; lengthen the shot, or cut copy when timing is locked to voice, rather than compress reading. These figures apply to graphic copy, not word-synced captions, and `onScreenText` sets the density. Leave 0.35 s between text events, let the outgoing line leave before the next enters, and give the last item of each sequence 0.4 s clean before a transition covers it. Individually read events need about 0.3 s each; when faster, or beyond about eight labeled items (about 35 anonymous tokens), show two or three slowly, then an aggregate. Text below the size floor is texture and carries no message. Scroll-first formats may need the answer within 1–2 s unless the brief's hook deliberately withholds it.
+
+**Sound-first timing.** When narration exists, lock it first (see [audio production](../../editorbrain/references/audio-production.md)) and anchor events to it; voice-synced text lands 0–5 frames after the word, never before (one measured reel). With SFX or music, derive cues from the motion's event list; for rhythmic or physical scenes without locked narration, a beat grid can lead, without every cut on a beat. Align each sample's measured peak or attack, not its file start: impacts on contact, whooshes at peak velocity, chimes and swells on the settle or resolve. Cluster trains above about 6–8 cues per second; gain follows magnitude. Respect exclusions; every SFX needs a visible cause, the scene must read muted, and aligned data still needs listening.
+
+**Ratios.** Recompose graphic layers per ratio from one model with identical beat times instead of cropping another ratio's render; reframing footage or cropping an asset inside the layout is fine. In 9:16, transpose the main axis rather than shrink; no band over about 15–20 % of the height stays empty beyond about 1 s. Carry moves under about 40 px in secondary cues (lean, tension, counters); a protagonist leaving a system travels about a third of the frame height. No hero state is a sliver beyond about 0.5 s, text never rotates 90° to fit, key actions stay in frame, and narrow ratios get gentler camera moves. The size floor is a font size at final on-screen scale of about 20 px in 16:9 and 1:1 and 22 px in 9:16 and other portrait ratios: a floor, not a target, confirmed at delivery size. Take platform UI zones from the output profile or destination.
+
+## Failure modes
+
+| Failure | Detect with |
+|---|---|
+| Text overflows, wraps badly or sibling sizes differ | Longest copy and maximum counts in every ratio |
+| Numbers contradict each other, the copy or the claim | Recompute derived figures and differences from visible operands |
+| Narrow ratios inherit the wide layout | Empty bands and margins on mid and last frames |
+| Labels, stamps or props land on text | Stills at every beat and rest pose in each ratio |
+| Moving values or labels cross text | Dense 10–30 fps strips over each flight |
+| Camera crops text at a hold | Label boxes against the safe margin at every hold |
+| Empty opening or unfinished ending | First and last frames alone at thumbnail size |
+| Rushed events or one-frame pops | Shortest event interval; frame-exact grids at state changes |
+| Dead air | Freeze scan, e.g. ffmpeg `freezedetect`, against planned holds |
+| Under-weighted payoff or misread object | One dominant element in the last seconds; grayscale silhouette at phone size |
+| Unmotivated effects | Glow, particles, blur-in or stock dashboard card without a cause |
+| Sound drifting from picture | Retime one event, compare cue and event frames, listen |
+| File size balloons | Size after the first render; unsettled motion tails, per-frame grain |
+
+Those effects are fine when the style, the user or a fitting component calls for them.
+
+## Self-review order
+
+1. Four lines, recomputed numbers, density arithmetic (count × interval fits the beat).
+2. Stills at every beat and mid-transition in each ratio, narrowest first, with zoomed crops of the smallest text.
+3. For parameterized or reused scenes, stress inputs: longest copy, extreme counts, descenders and accents, each applicable brand theme.
+4. Numeric checks where claims matter: text boxes, recomputed numbers, out-of-order seeks.
+5. Dense strips around transitions; every frame for events under 0.2 s.
+6. The whole export at delivery size, first and last frames included, listening to any audio.
+7. A fresh-context second pass, or a separate reviewer, on the final export's strips (tiles of 480 px or more, times inside the duration). Edge-cropped text is blocking; fix self-noted legibility or payoff weaknesses before reporting.
+8. Fix the cause (layout rule, data, timing) behind a defect; recheck that interval, the other ratios and the delivered whole.
+
+Record findings in the [code motion](code-motion.md) format and finish with [production and review](../../editorbrain/references/production-and-review.md). Clean engine diagnostics, where available, are necessary but not sufficient; passing checks is not artistic approval, and measured audio is not listened audio.