editorbrain 0.18.0 → 0.27.1

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -6,7 +6,7 @@ Turn EditorBrain evidence into decisions suitable for this user, execute the req
 
 Start with `videos/<project-id>/project.json`, its brief/direction and the brand, style and output profile it selects. Discover IDs instead of assuming names. Understand goal, audience, language, format and available tools; preserve preferences and authorized exceptions. Resolve minor choices yourself; ask only about consequential uncertainty and continue independent work while waiting.
 
-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.
+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.
 
 For a scoped revision, reuse the approved direction and still-valid source observations. Inspect what changed; do not reopen style choices, search again, analyze every original or request another approval without a relevant change. Recheck the new delivery rather than applying an old render's review to new bytes.
 
@@ -32,12 +32,16 @@ Retrieve documents using paths from the reference manifest and pin hashes where
 
 Keep distinct: **observed/measured** with source/location; **inferred** with uncertainty; **designed for this project** as an intentional choice. Never invent evidence to complete a plan.
 
+Choose production media by what the scene claims. For real people, places, history, products, news or demonstrations, inspect available user footage and search the web for authentic images, video or screenshots **before generating substitutes or building a generic code-only scene**. Use Claude/Codex's available web image/video search and browser tools; archive connectors are optional supplements, not the limit of internet search. View the asset and verify that its subject, date and context match the beat. Search results are leads, not reviewed media or reuse permission. For an invented, abstract or deliberately illustrative scene, code/AI can be the appropriate first choice. Label a recreation when it could be mistaken for evidence. Read [real media and evidence](references/real-media.md) for acquisition and provenance. EditorBrain's reference library teaches editing; it is separate from finding authorized production footage.
+
 ## Execute and review
 
 Connect each meaningful beat to message, viewer perception, resource/action, composition, motion, timing and verification. Brand and brief govern adaptation; reference colors are not customer defaults. Reuse footage when it serves continuity, comparison or a callback; extra cuts and different hashes alone do not establish variety. No universal scene count, source quota, effect, music or SFX is required.
 
 Use the available engine's actual capabilities. Exports are handoffs, not renders; no particular paid provider is required. For substantial uncertainty, read [production and review](references/production-and-review.md): test the difficult mechanism, inspect generated assets, anchor timing to actual material and check sensitive events. A pilot is not an automatic permission gate; trivial changes need no new pilot.
 
+When the task needs an animated scene, load [editorbrain-motion](../editorbrain-motion/SKILL.md) with the same resolved project context. Its production method cannot replace brand tokens, selected style, scoped memory, exclusions or review preference. Do not load specialized skills for unrelated work.
+
 Review the final artifact end to end for editorial meaning, perceptual clarity and technical delivery. Listen to relevant audio/SFX in the final mix; scheduling and meters cannot prove audibility. Automated checks/models contribute limited evidence. Record unavailable modalities instead of marking them passed. Tie every review to the output version/hash and recheck changes and the delivered whole.
 
 ## Preserve scope and provenance

package/skill/editorbrain/SKILL.md

@@ -7,18 +7,24 @@ description: Edit a user's video with EditorBrain's brand files, reusable styles
 
 You are the editor. EditorBrain supplies the harness: persistent brand/style/project files, a searchable evidence library and a workflow for turning that evidence into a finished edit. You analyze the customer's material and judge the references; no second model needs to repeat your creative decisions.
 
+## Specialized work, loaded when needed
+
+For animated scenes, motion graphics or generated character/object motion, use the sibling [editorbrain-motion](../editorbrain-motion/SKILL.md). Pass the active project and already resolved context; it adds production technique, not another creative direction. Skip it for ordinary cuts, static graphics or sync/install tasks. User memory belongs in scoped brand/style/project files; shared skills describe methods, and library examples supply evidence. Never copy example colors into the customer's identity.
+
 ## Create or update a reusable style
 
 When the user asks to save an edit as a style, create a new style or improve an existing one, read [style creator](references/style-creator.md). Reuse the current production's evidence and feedback; saving a style does not require editing another video. The guide covers defining the method, adapting it to new material, resource manifests, checks and versioned saves. Keep personal decisions in that user's style, not in this installed skill. For ordinary editing with an existing style, continue below.
 
 ## Start here, including a first installation
 
+For factual subjects or real demonstrations, search and inspect authentic web images/video or user footage before designing substitutes; use the host's available search/browser tools. 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.
+
 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). 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 review preference, scoped memory and personal integrations. 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. 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 review preference, scoped memory and personal integrations. 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. For a scoped revision, reuse the approved direction and still-valid source observations/evidence; do not repeat retrieval or reopen style choices unless the brief, material or needed mechanism changed. When evidence is needed, use `search_from_brief` (CLI `editorbrain search brief --file <brief.json>`) with your analysis and project ID. Read [search brief](references/search-brief.md) for its schema. Search editorial mechanisms as well as the subject. The server returns evidence candidates using embeddings; it does not analyze the source again or certify fit. `search_for_edit` is an optional older server-analysis path, only when explicitly requested; never silently fall back to it.
-6. Compare the candidates yourself. View the relevant reference frames; inspect intervals and audio when movement or sound matters. Select what fits the actual material, explain adaptations and missing resources, and save the direction with source hashes. Similarity is not approval; reject weak matches instead of forcing them.
+5. For a new edit with no chosen style, keep composition and techniques open until source inspection and reference comparison. Saved favorites guide taste; they do not preassign a format. Search the communicative need, not a guessed template. For a scoped revision, reuse the approved direction and still-valid source observations/evidence; do not repeat retrieval or reopen style choices unless the brief, material or needed mechanism changed. When evidence is needed, use `search_from_brief` (CLI `editorbrain search brief --file <brief.json>`) with your analysis and project ID. Read [search brief](references/search-brief.md) for its schema. Search editorial mechanisms as well as the subject. The server returns evidence candidates using embeddings; it does not analyze the source again or certify fit. `search_for_edit` is an optional older server-analysis path, only when explicitly requested; never silently fall back to it.
+6. Compare the candidates yourself. View the relevant reference frames; inspect intervals and audio when movement or sound matters. Create the direction from the actual material and inspected evidence: what the viewer should understand, what changes on screen and why. Retain, adapt or omit techniques per beat; an authored scene or a simple cut is valid. Save the concise decision and source hashes in direction.md. Legacy pack drafts and reusable components are optional tools, not the default creative route. Similarity is not approval; reject weak matches instead of forcing them.
 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. Implement with available editing/rendering tools, then inspect the final artifact and save scoped feedback. An editing request needs the edit, not only a plan. Read [production and review](references/production-and-review.md) for complex motion, audio or transfer QA. Report any dimension you could not verify.
 

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

@@ -0,0 +1,42 @@
+# Audio for this user's edit
+
+Read for narration, music/SFX production or audio delivery. Do not inherit a demo's voice, sound bank or loudness target.
+
+## Portable preferences
+
+Optional `.editorbrain/brands/<brand>/audio.json` sets brand defaults; `videos/<id>/audio.json` overrides them. Resolve/workflow context includes `audioProduction` only when configured; source hashes track changes. Omission inherits; `null` clears. Voice/loudness replace atomically; SFX fields inherit individually. Existing `language.json`, `music.md`, editorial preferences and memory still apply. If narration choices conflict, reconcile using the current explicit request before spending, rather than silently selecting another voice.
+
+Fields (optional except `schemaVersion:1`):
+
+| Field | Values |
+|---|---|
+| `voice` | `{mode:"original"}` or `{mode:"none"}`; generated voice requires `{mode:"catalog"\|"cloned",provider,voiceId}`. Never infer a cloned voice. |
+| `sfx.library` | `{bankId:"my-sounds"}`. Resolve with local tools; keep actual directory/map paths in private local files. An ID does not prove access. |
+| `sfx.generation` | `allowed\|forbidden`; preference does not authorize spending or verify tool access. |
+| `sfx.density` | `none\|sparse\|moderate\|dense`; qualitative, not a sound quota. |
+| `sfx.hookWithoutEffects` | Boolean for this user's opening treatment. |
+| `loudness` | `{targetIntegratedLufs,toleranceLu,maxTruePeakDbtp}`; no universal target. |
+
+Inspect a configured sound bank's actual inventory/approved map and prefer fitting assets. If missing, explain the unavailable binding and use an allowed alternative. Library presence alone does not forbid generation; explicit exclusions do. A no-SFX preference or forbidden generation must not trigger synthesized fallback clicks/whooshes. Do not borrow another member's folder. Music and SFX remain separate decisions.
+
+## Timing and sound
+
+Keep correctly spelled display/subtitle text separate from synthesis pronunciation hints. Use the requested language, glossary and approved voice. Verify provider access/current capability and listen to uncertain pronunciations when possible. ASR agreement does not certify pronunciation.
+
+ElevenLabs [speech with timing](https://elevenlabs.io/docs/api-reference/text-to-speech/convert-with-timestamps) supplies character alignment; group it into word cues against the returned audio, distinguishing original/normalized text. Missing alignment remains missing. After trimming pauses, reordering or speed changes, remap cues through those edits or realign the final narration. A silence threshold identifies candidates, not mandatory cuts.
+
+Lock narration before final music and animation 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.
+
+## Measure the delivered file
+
+In addition to `production check`, measure integrated loudness/true peak from the actual encoded/muxed deliverable:
+
+```sh
+editorbrain production audio-check --file ./renders/final.mp4 --out .editorbrain-local/my-video/audio-v1.json
+```
+
+Without a target it measures only (`not_evaluated`). For an explicit requirement, add `--profile .editorbrain-local/my-video/audio-profile.json` containing `schemaVersion:1` and `loudness` copied from the intended project requirement. Optional `limits:{timeoutMs,maxOutputBytes}` bounds execution. The command does not auto-load a project, normalize, overwrite or upload. It measures each audio stream, hashes the artifact and rechecks stability. Use the saved full report for streams omitted from compact output. Silent/unmeasurable loudness, absent audio, missing tools or interrupted decoding cannot prove a successful audio delivery. Intentionally silent videos need no loudness check; `voice.mode:none` alone does not forbid music.
+
+Exit 1: target failure. Exit 2: incomplete measurement. Exit 0: measurements completed, possibly without a target. Meters do not certify intelligibility, voice identity, sync or SFX audibility. Listen if the host has that modality; otherwise disclose what remains unchecked. Do not assume an agent can never listen regardless of available tools.
+
+When normalizing elsewhere, inspect actual processing mode: FFmpeg [loudnorm](https://ffmpeg.org/ffmpeg-filters.html#loudnorm) can fall back from linear to dynamic normalization. Re-measure the final AAC/MP4 after gain/limiting/normalization; a source WAV's result does not certify the delivery. For suspected drift, inspect cues and source/final envelopes in the relevant interval; music/compression can weaken correlation and a numeric lag alone is not proof of audible sync. File-size/bitrate/mobile-preview limits belong to the output brief.

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

@@ -4,6 +4,10 @@ Use the connected MCP schema and `editorbrain help` to confirm the installed con
 
 API/MCP: `https://api.editorbrain.com/mcp`. The host must connect this server separately; installing a skill does not register or authorize MCP.
 
+## Reusable motion (CLI 0.20+; discover MCP availability)
+
+`editorbrain motion list [query]` returns compact component metadata; `motion get <id> --component-version 1.0.0` returns one recipe. MCP equivalents are `list_motion_components` and `get_motion_component` when present in the connected server. `motion prepare --file scene.json --project ID --out .editorbrain-local/new-scene` binds current local project tokens and prepares editable HTML without model calls. It does not encode an MP4. Load the sibling `editorbrain-motion` skill and its component-library guide only for this work; ordinary edits need no extra motion context.
+
 ## Personal integrations (0.13+)
 
 `check_workflow` includes active integration preferences. For configuration use
@@ -26,7 +30,7 @@ editorbrain skill install --dir ./my-videos --agent both
 
 If unauthenticated, `editorbrain login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: register the MCP URL without a bearer header and authorize through the host’s OAuth login. Choose the same workspace in the consent page. Existing bearer-key connections remain compatible; do not overwrite one during setup.
 
-Skill installation is offline and independent of login. It creates `.agents/skills/editorbrain/` for Codex and `.claude/skills/editorbrain/` for Claude. Open the target folder in the agent and explicitly ask it to read the installed `SKILL.md` if automatic discovery has not refreshed. The skill directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
+Skill installation is offline and independent of login. CLI 0.19+ installs sibling `editorbrain/` and `editorbrain-motion/` skills under `.agents/skills/` for Codex and `.claude/skills/` for Claude. Read the core first; load motion only for animated scenes. Open the target folder in the agent and explicitly follow the returned instruction path if automatic discovery has not refreshed. The core directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
 
 Existing root `AGENTS.md`/`CLAUDE.md` are preserved. Read the install result's instruction paths and conflict reports. A preserved root guide does not mean the native skill failed; a conflicting existing skill needs a deliberate merge, not an overwrite. Do not replace the user's custom instructions to finish setup.
 
@@ -64,7 +68,8 @@ editorbrain assets download <sha256> --out ./media/clip.mp4
 Discover current argument schemas before calling:
 
 - `list_style_packs`: methods, techniques, fit and requirements.
-- `recommend_styles`: candidates for the saved project, using actual resources and capabilities.
+- `search_from_brief`: primary retrieval after source inspection; compare references and author the direction yourself. See [search brief](search-brief.md).
+- `recommend_styles`: optional legacy pack shortlist based on literal rules and declared resources, not a creative analysis of the material or all saved preferences.
 - `search_styles`: literal search for reference aliases, authors, topics and editorial devices; try alternative terms when useful. No result is not proof that a technique is absent from the library.
 - `get_reference({videoId})`: profile, script summaries, examples, document manifest and authorized media inventory.
 - `read_reference_document({videoId,path,sha256})`: exact source document version when a hash is supplied. Take `path` from the returned document manifest; optional files and provider names vary by reference.
@@ -106,10 +111,10 @@ Access is scoped to the current workspace's reference grant and credential. A kn
 
 ## Draft, produce and save
 
-`draft_direction` proposes an initial method and techniques. Inspect its pending requirements and transfer status, complete the per-beat decisions using evidence and the actual material, then implement the user's requested output. Available CLI:
+Normally author direction.md from inspected material, resolved preferences and retrieved evidence; no pack selection is needed. `draft_direction` is only an optional scaffold for a deliberately selected catalog pack (`selectedStyle` / `--style`). It cannot choose a pack for you or assign beat techniques automatically. It does not validate the full editorial context: reconcile exclusions, taste and memory from resolve/check_workflow before using a scaffold. Do not run it merely because the user left style open. Available CLI:
 
 ```sh
-editorbrain direction draft <project-id> --dir ./my-videos --out ./direction-draft
+editorbrain direction draft <project-id> --style <deliberately-selected-pack> --dir ./my-videos --out ./direction-draft
 editorbrain export <project-id> --dir ./my-videos --adapter neutral --out ./handoff
 ```
 

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

@@ -5,13 +5,14 @@ Use this only when the user's environment or project is not ready. Do not re-onb
 ## Establish a working workspace
 
 - Discover the installed CLI (`editorbrain version`, `editorbrain help`) and MCP tools. If absent, follow the official app's installation prompt; do not invent a package or install a rendering engine without need.
+- Try installed commands individually before inspecting an installer. A denied directory scan or compound shell command does not establish that the CLI is absent or every command is forbidden. Respect the denied scope; use a separately permitted CLI/MCP operation, or report the exact operation that remains blocked. Do not reinstall or request broad shell access based only on that denial.
 - For an existing account, authenticate if necessary, discover projects and use `editorbrain setup --dir <folder> --agent codex|claude|both --project <id>`. Confirm MCP `workspace_info` and CLI `status` name the same workspace. Browser consent needs the user; configuration alone is not authentication.
 - If no project exists, `editorbrain init --dir <new-folder> --brand <brand-id> --style <style-id> --project <project-id>` creates context and installs the harness. Authenticate before synchronization. Validate, inspect `push --dry-run`, then push that intended context. Never use init to reset a pulled project. Do not confuse an empty local draft with a remotely saved project.
 - Existing root AGENTS.md/CLAUDE.md and customized skills are preserved. Read install results and any conflict; use the returned skill path explicitly if needed. Installation is not proof the host has read it.
 
 ## 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.
+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.
 
 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.
 

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

@@ -70,3 +70,7 @@ Profile fields: `expected` (width, height, fps, durationSeconds), `tolerance` (f
 The command decodes the file, records its hash and reports technical findings. Read `complete`, `technicalStatus`, individual check states and coverage; a disabled check is `not_checked`, not passed. Missing tools, truncated checks and timeouts cannot prove a clean render. Exit 0: the requested run completed without a technical failure, possibly with warnings. Exit 1: invalid input or failed technical requirement. Exit 2: incomplete inventory/check without a separate technical failure.
 
 A whole-mix sample peak is not loudness, true peak, speech intelligibility or SFX audibility. Narrative, aesthetics, text readability, motion and sound still need the agent's actual review. Keep human approval separate. Link review to the exact file/hash; after changing the output, its previous check no longer applies.
+
+## Targeted additional checks
+
+For authentic imagery, use the host web tools first and read [real media](real-media.md) for optional `media search` and `production evidence-check`. Unlike local inspection, `media search` sends the explicit query to public archive APIs, never local media. For final LUFS/true peak use [audio production](audio-production.md) and `production audio-check`. For boundary frames and declared geometry use [motion review](motion-review.md) and `production motion-check`. These are optional task-specific tools, not another mandatory checklist.

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

@@ -0,0 +1,35 @@
+# Targeted motion review
+
+Read for timing boundaries, source-image anchors or text collisions in authored motion. This is a local optional helper, not another rendering engine or a visual-quality score.
+
+```sh
+editorbrain production motion-check --file .editorbrain-local/my-video/motion-input.json --out .editorbrain-local/my-video/motion-review-v1.json
+```
+
+A minimal input to plan transition samples:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "editorbrain.motion-review-input",
+  "timing": {"durationSeconds": 8, "frameRate": 30, "cutTimesSeconds": [3.67]}
+}
+```
+
+It plans ±3 frames around the first frame at/after each cut, clips indices to the actual frame range and deduplicates them. Set `radiusFrames` for the risky transition, up to 30; at most 1000 cuts. For exact fractional rates use `frameRate:{"numerator":30000,"denominator":1001}`; decimal 29.97 is a different rate. Duration is half-open: no frame exists at the exact end. The report is a **sampling plan**; capture/view those frames using the actual renderer and save the expected scene/state. It never certifies a transition from timestamps alone.
+
+Optional `geometries` holds up to 12 independent frame/ratio observations. Each has `width`, `height`, `boxes:[{id,kind,x,y,width,height,boundsKind?,visible?}]` in stage pixels. Kind is `text|label|face|protected`; boundsKind is `ink|container|annotation`. Supply measured boxes after crop, scale and typography, not stale coordinates from an untransformed source. A declared face rectangle is a protected region, not automated identity recognition. This helper does not detect faces or measure text.
+
+Optional geometry `profile`:
+
+- `safeAreas:[{id,rect:{x,y,width,height},boxIds:["title"]}]` applies only to the listed boxes. Derive from this output, not a universal TikTok margin.
+- `intentionalOverlaps:[{boxIds:["title","caption"],reason:"Intentional shared treatment"}]` records deliberate overlap, not hidden mistakes.
+- `checkCollisions`, `tolerancePixels`, `minOverlapArea` tune the declared check. Unspecified safe areas impose no platform margins.
+
+Example observation: `{"width":1080,"height":1920,"boxes":[{"id":"title","kind":"text","x":100,"y":200,"width":600,"height":150,"boundsKind":"ink"},{"id":"subject","kind":"face","x":400,"y":250,"width":200,"height":300,"boundsKind":"annotation"}]}`. The overlap is a review candidate, not automatic permission to move/remove text. Recompose based on the scene. Distinguish actual glyph ink from container bounds, and check subtitles aren't needlessly repeating a headline. Keep time/output mapping beside each observation in your local review notes. Geometry checks cover declared frames, not the entire video or missing ratios.
+
+Default stdout is compact; full samples/findings live in `--out` or `--details`. No media upload, rendering, creative approval or automatic fixes. A zero exit code means the request was checked, even when candidates remain; read them. Invalid schema fails. Review each requested ratio with actual fonts and output-size readability.
+
+For implementation, clamp quantized local time after subtracting shot start; handle empty sequences before array indexing. Force easing endpoints to exact 0/1 without eliminating intended intermediate overshoot. Reassign shared Three.js clipping planes after cloning a material if planes must continue animating together. Helpers in the development core do not become globals inside serialized `toString()` factories; explicitly embed the needed implementation.
+
+A render queue may continue after an individual failure but must mark that job failed and return a failed overall exit status. Page/frame errors, missing captures and encoder failures cannot yield a verified pass. Keep the current attempt separate from earlier successful renders, close resources in finally, and write reports for stills too. Do not delete an earlier good delivery merely because a new attempt failed. Use short saved scripts for complex Python/Node work instead of shell-escaped multiline programs. Review flashing/inversions when used; simple counts are diagnostics, not photosensitivity certification.

package/skill/editorbrain/references/production-and-review.md

@@ -1,11 +1,17 @@
 # From reference to verified edit
 
+For factual imagery, use [real media and evidence](real-media.md): find authentic web/user images/video, inspect them and design around their content. For narration, sound preferences or final loudness checks, use [audio production](audio-production.md). Load only what the current work needs.
+
 Scale this workflow to the request. Reuse previous verified work when applicable. No fixed scene count, number of sources, SFX pattern, review duration or visual technique is required for every video.
 
+For animated scenes, use [editorbrain-motion](../../editorbrain-motion/SKILL.md) with the current resolved context. It adds code/generative motion methods and targeted temporal review; this reference remains the shared contract for the whole edit.
+
 ## Turn a style into mechanisms
 
 Record the requested transfer mode: faithful preset, editorial family, or inspiration. Describe its defining mechanisms with evidence and the allowed adaptation. For example, a reference may build a typographic composition through discrete states rather than generic sliding cards. Preserve that mechanism when faithful transfer is requested, while adapting words, brand and timing.
 
+When the selected reference exposes a `motion-takeaways.md` or equivalent mechanism analysis, read that specific document and verify relevant evidence. Turn its useful mechanisms into the scene's visual grammar; do not just copy the source layout.
+
 Separate the mechanism from one reference's subject, props and colors. A travel reveal and a product reveal may share an attention shift but need different imagery and pacing. Do not select a style just because the source performed well or belongs to the same niche.
 
 Use a compact plan such as:

package/skill/editorbrain/references/real-media.md

@@ -0,0 +1,51 @@
+# Choose and inspect production media
+
+Read when the video needs outside imagery, factual claims or demonstrated products. Reuse valid sources from the current edit; do not repeat searches for a small revision.
+
+## Decide before generating
+
+| What the viewer should see | Starting point |
+|---|---|
+| User working, speaking or demonstrating something | Inspect supplied footage and screen recordings; select the actual relevant interval. |
+| A real person, historic event, place, product or news story | Search authentic photos/video and primary pages using the host's web image/video search and browser tools. Search exact subject names, action, dates and context. |
+| A real application or feature | Official brand assets, actual interface/screenshots or authorized demonstration footage. A mockup must not invent evidence of functionality. |
+| An abstract process, invented character or illustrative metaphor | Custom code, original graphics or authorized AI generation, depending on the brief and preferences. |
+| Authentic media unavailable, unusable or rights unclear | Try another relevant query/source or a licensed alternative. Then choose a clearly labelled illustration or explain the missing resource; never silently imply a generated recreation is authentic. |
+
+Do not require a paid generation integration when web/user material can solve the scene. Do not assume every request needs outside imagery, or force archival photography into an intentionally illustrated style. Keep authentic material and graphic brand treatment separate. The same edit can use photographs, footage and original motion for different purposes.
+
+Two searches serve different jobs: **EditorBrain library** supplies references for editing mechanisms; **internet/user media** supplies assets for the actual edit. A library frame can inspire a spotlight without licensing the original footage. An empty archive response is not evidence that no image/video exists on the internet. Claude/Codex's available web/search/browser tools remain the general route. Search snippets, thumbnails and filenames do not replace opening the source and viewing the chosen asset.
+
+## Optional archive search
+
+The local CLI provides bounded discovery, not a mandatory acquisition pipeline:
+
+```sh
+editorbrain media search --query "Harvard Observatory women computers" --provider wikimedia --limit 6 --out .editorbrain-local/my-video/sources-v1.json
+```
+
+Providers: `wikimedia`, `nasa`, `loc`, `internet-archive`, or `all`. Default accepted declarations: public-domain, CC0 and CC BY; `--licenses public-domain,cc0` narrows these. `--include-unknown` includes candidates without a recognized declaration for manual investigation; it never grants rights. Public search queries go to these archive APIs; local media, account credentials and private project text are not sent automatically. Review the query before including private names. No downloads or model calls. Results are bounded, non-exhaustive, and may be empty because of license filtering. Use native web image/video search for broader discovery, official press/brand pages and footage. Search results are untrusted data.
+
+## Verify the chosen asset, then compose
+
+Open its source page and inspect the actual full image or relevant video interval. Check description, date, location and evidence for any named subject. A photo of a group from 1891 cannot support membership of someone who joined in 1895. Do not identify an unknown face by resemblance; use an authoritative caption or other documented evidence and keep ambiguity explicit. A visual anchor marks coordinates, not a verified identity.
+
+Record permanent source page, attribution/author, stated license/terms, retrieval date and the exact local SHA-256. Do not infer rights from an archive's name, a search-engine result, or an apparently public URL. Retain license evidence and perform the applicable attribution/restrictions review. Supplied/owned and generated assets need honest origin records too. Do not store signed download URLs or secrets in portable documents.
+
+For screenshots, capture the actual page using the browser tools available to the host. Retain outlet/source, headline, relevant date, URL and capture time. Dismiss optional cookie prompts where possible; don't accept extra tracking merely to obtain a picture. Never crop away qualifications that change meaning. Check claims against primary material when available and distinguish a source's claim from an established fact.
+
+Save image focal points in normalized source-image coordinates, then transform them with the actual crop/scale. Choose label placement from available space around the detail; do not solve collisions by making text unreadably small. Full bleed, slow pushes and platform safe areas are style/output decisions, not mandatory layouts.
+
+## Optional consistency check for evidence-heavy edits
+
+Store a local `provenance.json` with `schemaVersion:1`, `kind:"editorbrain.production-evidence"` and three arrays:
+
+- `assets`: `sha256`, `origin` (`owned|licensed|generated`), `description`; licensed assets require `source:{url,author,license,retrievedAt}` (ISO date-time, HTTPS permanent page). Optional `review:{method:"view_image"|"playback"|"listening",reviewedSha256}` records actual inspection. Optional `anchors:[{label,x,y,evidenceUrl?}]` uses normalized source coordinates.
+- `uses`: `{id,sha256,representation:"documentary"|"illustrative"|"original",claimIds?:[],disclosure?:"Illustrative recreation"}`. IDs contain letters/numbers/hyphen/underscore. List assets actually used; this declaration is not inferred from the render.
+- `claims`: `{id,text,status:"supported"|"disputed"|"unverified",sources:[{url,kind:"primary"|"secondary",evidence}]}`. Evidence is a concise supporting observation, not a fabricated quote. Include delivered claims even when spoken or shown as text without a media asset. A status is the agent's assessment.
+
+```sh
+editorbrain production evidence-check --inventory .editorbrain-local/my-video/inventory-v1.json --manifest .editorbrain-local/my-video/provenance.json --out .editorbrain-local/my-video/evidence-v1.json
+```
+
+Use the full inventory saved by `media inventory`; refresh it after media changes. This checker catches missing/hash-mismatched entries, generated imagery presented as documentary evidence and absent claim links; warnings identify unreviewed sources or unresolved claims. It does not browse, reopen files, verify identity, certify facts/rights or inspect the render. A declaration cannot replace those actions. Keep detailed records private and save only needed approved source summaries in the portable project.

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

@@ -1,6 +1,6 @@
 # Search from your own analysis (0.9+)
 
-Inspect the actual source before filling this brief. CLI reads the brief object from a UTF-8 JSON file (up to 32,000 bytes). MCP takes `{brief, projectId?, mode?, reviewMode?}`. The server validates shape, not whether you truly inspected the source; never present that validation as verification.
+Inspect the actual source before filling this brief. CLI reads the brief object from a UTF-8 JSON file (up to 32,000 bytes). MCP takes `{brief, projectId?, mode?, reviewMode?, detail?}`. The server validates shape, not whether you truly inspected the source; never present that validation as verification.
 
 ```json
 {
@@ -21,13 +21,16 @@ Inspect the actual source before filling this brief. CLI reads the brief object
   "hardConstraints": ["Preserve the user's required brand tokens; do not invent product claims"],
   "uncertainty": ["Cannot verify camera angles or sound before receiving footage"],
   "styleQuery": "Clear paired comparison, restrained labels, practical demonstration and visual payoff",
-  "eventQueries": ["Before-after comparison with aligned framing", "Reveal the final arrangement after setup"]
+  "eventQueries": [
+    {"query": "Before-after comparison with aligned framing", "channels": ["visual", "on_screen_text"]},
+    "Reveal the final arrangement after setup"
+  ]
 }
 ```
 
-Replace this example with observations for the real project. Required fields are shown; `source.excerpt` and `source.sha256` are optional. `kind` is `script`, `video` or `mixed`; `inspected` contains only actually inspected modalities from `script`, `frames`, `motion`, `audio`. A silent video can have inspected frames/motion with no audio. State sampled intervals and omitted coverage. Hashes identify local source files, do not grant access to any remote file and are not server-verified.
+Replace this example with observations for the real project. In hardConstraints put only actual requirements. Keep your proposed calendar, grid, metaphor or animation out of that list unless the user required it. For an open brief, start from what needs to be communicated; narrow to a mechanism after comparing references. A known, deliberately chosen technique or scoped revision can use a focused mechanism query directly. Required fields are shown; `source.excerpt` and `source.sha256` are optional. `kind` is `script`, `video` or `mixed`; `inspected` contains only actually inspected modalities from `script`, `frames`, `motion`, `audio`. A silent video can have inspected frames/motion with no audio. State sampled intervals and omitted coverage. Hashes identify local source files, do not grant access to any remote file and are not server-verified.
 
-Bounds: summary/styleQuery/excerpt up to 1,800 characters each; coverage 800; goal 600; audience 500; tone/pacing 400. Asset, constraint and uncertainty arrays have up to 12 entries of 400 characters each; use `[]` when empty. Up to two event queries of 1,000 characters each. These limits keep retrieval focused; preserve full production notes locally.
+Bounds: summary/styleQuery/excerpt up to 1,800 characters each; coverage 800; goal 600; audience 500; tone/pacing 400. Asset, constraint and uncertainty arrays have up to 12 entries of 400 characters each; use `[]` when empty. Up to two event queries of 1,000 characters each. An event query can be a string or `{query, channels}`. Optional channels are `visual`, `on_screen_text`, `spoken`, `audio`, `post_caption`; one matching channel is sufficient. For subtitle layout use `on_screen_text`/`visual`; a post description is `post_caption`, not the video's captions. Choose channels from the inspected need, not the reference title. Missing channels preserve broad search. A filtered empty result stays empty and is not silently broadened. Unknown timestamps still require inspection; a channel match is not evidence of exact timing. Older services may reject this object form: report the compatibility limitation and use a plain query with explicit manual channel review rather than claiming the filter applied. These limits keep retrieval focused; preserve full production notes locally.
 
 ```sh
 editorbrain search brief --file .editorbrain-local/my-video/search-brief.json --project my-video --mode both
@@ -35,10 +38,10 @@ editorbrain search brief --file .editorbrain-local/my-video/search-brief.json --
 
 `mode` is `styles`, `events` or `both` (default). Include projectId whenever the project is saved remotely; validate/push intended local context first. Inspect returned context and source hashes to catch stale local assumptions. Without projectId, constraints are only your declarations; do not claim the server resolved the customer's brand. Omit `reviewMode` to inherit the current preference; set it only to carry an explicit user instruction.
 
-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. 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.
+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.
 
-Choose based on narrative function, required brand rules, available resources, readability, tone and continuity. Record what you retain, adapt and omit. 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.
+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.
 
 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/workspace-files.md

@@ -10,7 +10,9 @@ Read `videos/<project-id>/project.json` first: its `brand`, `style` and `outputP
 AGENTS.md                         Codex entry point (existing instructions preserved)
 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
 .claude/skills/editorbrain/      Claude Code skill, contract and references
+.claude/skills/editorbrain-motion/  Claude Code animation skill, loaded when animating
 .editorbrain/
   brands/<brand-id>/
     brand.md                      Identity, audience, constraints
@@ -59,13 +61,16 @@ The implemented token resolution is:
 
 Token strengths are `required`, `preferred`, and `example`. An `example` is evidence, not an applied value. Read `resolve` output, `tokenSources` and warnings rather than guessing which setting won. Markdown instructions require the agent's interpretation; the resolver does not semantically reconcile every sentence for you.
 
+Token keys are flat semantic names, **not CSS properties**: 1–80 characters, starting with a lowercase ASCII letter, followed by lowercase letters, digits, `_`, `.` or `-`. Use `font_family` or `font.display`, not `fontFamily`; `font.display` is a literal key, not a nested object. `__proto__`, `constructor` and `prototype` are reserved. A value can be a string, finite number, boolean or array of strings. The same key grammar applies to style tokens and project overrides. Map semantic names explicitly to the chosen renderer; there is no automatic CSS or motion-brand binding.
+
 For example, a token rule inside the generated tokens document may be:
 
 ```json
-"accent": { "value": "#2277AA", "strength": "required" }
+"accent": { "value": "#2277AA", "strength": "required" },
+"font_family": { "value": "Inter", "strength": "preferred" }
 ```
 
-That color is illustrative, never a customer default. Preserve the document's `schemaVersion`, `id` and surrounding `tokens` object. To use a different style for one project, select its existing ID in `project.json`; do not overwrite a shared style that other projects use. To create a separate style, use `editorbrain styles create <id> --name "Name" --dir <workspace>` and follow [style creator](style-creator.md). It creates only a local draft; `styles check <id>` checks its structure and declared local resources without rendering or uploading anything.
+Those values are illustrative, never customer defaults. A font declaration does not install a font: verify the actual family/file and load it in the renderer. Preserve the document's `schemaVersion`, `id` and surrounding `tokens` object. To use a different style for one project, select its existing ID in `project.json`; do not overwrite a shared style that other projects use. To create a separate style, use `editorbrain styles create <id> --name "Name" --dir <workspace>` and follow [style creator](style-creator.md). It creates only a local draft; `styles check <id>` checks its structure and declared local resources without rendering or uploading anything.
 
 ## Scripts and media
 
@@ -83,7 +88,9 @@ Save reusable feedback at its stated scope: project-only changes in the project,
 
 Updating the global CLI does not replace skills already copied into a project. Run `editorbrain skill install --dir <workspace> --agent both` and inspect `conflicts`, `preserved`, `warnings` and `readInstructions`.
 
-If skill files differ, the installer keeps them. 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.
+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.
 
 
 ## Review preference
@@ -100,3 +107,7 @@ See [memory and review](memory-and-review.md) for memory schemas, version restor
 ## Private local production (CLI 0.12+)
 
 `.editorbrain-local/<project-id>/` contains optional inventory, source-use plans, samples and technical review reports. It is excluded from automatic workspace discovery, push/pull, resolution hashes and exports. See [local production](local-production.md) only when using those helpers. Text under `videos/` can synchronize, including `plans/` and `reviews/`; `assets/` and `renders/` are excluded. Store a deliberate short summary in `direction.md` for cross-session cloud context. Keep complete reports out of routine agent prompts.
+
+## 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.

package/skill/editorbrain-motion/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: editorbrain-motion
+description: >-
+  Create or refine animated video scenes in an EditorBrain project: motion graphics,
+  kinetic type, diagrams, generated clips or mixed-media sequences. Use when an
+  EditorBrain edit needs animation, including a direct request to animate a scene.
+  Does not apply to ordinary website or application UI animation outside video production.
+---
+
+# EditorBrain Motion
+
+Build motion that explains the message and preserves the user's resolved identity, style and production choices. Keep editable sources and review the output.
+
+## 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 selected brief, direction, brand, style and output profile; use [first edit](../editorbrain/references/first-edit.md) if no workspace is ready. Preserve an approved direction and still-valid observations during scoped revisions.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+- **Authored reference:** search `list_authored_scenes` / `editorbrain motion scenes` for a relevant visual mechanism, then read one card. Use [authored scenes](references/authored-scenes.md) only when inspecting or adapting its code. These examples complement video evidence and do not prescribe a template.
+- **Reusable component:** use when its action, composition and timing fit the intended beat, or the user requests that template. Search `list_motion_components` / `editorbrain motion list`, then fetch only the selected pinned recipe. Read [component library](references/component-library.md) to bind tokens and prepare locally. Otherwise author the scene; suitable sub-elements may still be reused. Do not load or rewrite a component's code for parameter-only changes.
+- **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.
+
+## 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.
+
+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.
+
+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.
+
+Keep source, prompts, detailed plans and review artifacts in `.editorbrain-local/<project-id>/`; save a concise continuation summary in `direction.md`. Preserve prior versions and scoped user feedback. Deliver the artifact, useful checks and unresolved limitations; instructions and technical passes do not certify a perfect render.

package/skill/editorbrain-motion/references/authored-scenes.md

@@ -0,0 +1,22 @@
+# Authored motion references
+
+Use when a scene needs a visual mechanism (an object transforms, a structure falls, a route untangles, data moves). These are optional reference implementations, not the default format for every video. Start with the intended message and action; author a new scene when the available mechanism does not fit.
+
+## Retrieve only what you need
+
+1. `list_authored_scenes` / `editorbrain motion scenes "dependencia"` searches literal intent, mechanism and niche (accent-insensitive); it is not semantic video search. Default six compact results. Use `nextCursor` as `after` / `--after` to continue the same query.
+2. `get_authored_scene` / `editorbrain motion scene word-structure --scene-version 1.0.0` loads one card: purpose, timing, parameter limits, what requires code changes, exact bundle hash. A similar niche alone does not establish fit.
+3. Inspect `get_authored_scene_preview` / `editorbrain motion preview <id> --scene-version 1.0.0 --ratio tall` (optional `--preview-kind poster`). Video and poster links expire after five minutes; downloads remain reference evidence, not a customer-brand render.
+4. Only when using its code, request `get_authored_scene_source` with the exact ID, version and bundle SHA-256; or `editorbrain motion source word-structure --scene-version 1.0.0 --out .editorbrain-local/word-structure.tar.gz`. CLI download needs login, verifies size/hash, preserves existing files, and does not extract or execute. MCP URLs expire; persist IDs/hashes instead.
+
+The CLI commands require 0.27.0 or later; use advertised MCP tools if the installed CLI is older. Existing `motion list/get/prepare` addresses a different, bounded component catalog.
+
+## Adapt, then review
+
+Read the downloaded README and selected card. Extract only the reviewed bundle into a new project-local directory. It includes one scene, runtime, fonts/licenses and synthesized SFX; no private customer reel assets or renderer installation. Use the current local engine/tooling to capture `window.renderAt(t)`. Do not run a missing renderer from an unrelated workspace.
+
+Map resolved project tokens explicitly to every color/font role through `window.__overrides.brand` before scripts load. Register actual font files with the correct weights/styles and rights. Respect exact required tokens and documented scoped exceptions. Set `sound.enabled` from current preferences; false mutes authored and derived cues, music and voice. Replace demo copy, quantities, language and fictional media; branding overrides alone do not personalize those values. Recompose each requested ratio and align beats to actual narration when present. Verify integration access and existing generation authorization before adding media.
+
+`?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. The 33 general mechanisms exclude all personal `human-computers` reel versions.

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

@@ -0,0 +1,54 @@
+# Motion with code and compositing
+
+Read for scenes implemented with code or editable compositing. Use the current project's effective tokens, shot plan and approved direction; this guide defines production properties, not a new tool API.
+
+Start from the shot's specific visual action. Consult the compact [component library](component-library.md) when an existing mechanism fits it; select one pinned recipe rather than loading every implementation. Reuse useful utilities without inheriting an unrelated title/list layout or fixed stage timing. Custom composition is the normal route when the message needs different objects, relationships or choreography.
+
+## Make the idea visible
+
+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 a compact shot record when the existing plan lacks this detail:
+
+| Field | What to record |
+|---|---|
+| Intention and evidence | Message; verified source or explicitly designed illustration |
+| Entry → action → exit | Visible states, object identities and continuity into adjacent shots |
+| Time | Voice/action cue, motion interval, readable hold and exit |
+| Layers | Authentic assets, controlled text/data/UI, masks and background |
+| Layout | Hierarchy, safe areas and changes needed for each requested ratio |
+| Check | The specific failure that would break understanding or the chosen mechanism |
+
+This is an optional local planning format, not an EditorBrain schema. Do not place unsupported fields into `project.json`, `media.json` or API payloads.
+
+Keep exact words, values, logos and demonstrated interface states editable. Obtain authentic UI/assets when the scene claims to demonstrate a real product. Mark invented interface states as illustrative; a logo or mockup does not prove a capability. Required fonts need verified available font files or an authorized exception, never an unnoticed renderer fallback.
+
+## Make time explicit
+
+Choose the available engine and inspect its current documentation/skill before implementation. Frame-based rendering, seek APIs and resource readiness differ by engine/version. Record the actual implementation; do not claim compatibility with a renderer that was not used.
+
+When the engine supports deterministic access, calculate visual state from an explicit frame/time and immutable shot data. Keep global versus shot-local time explicit. Conceptually:
+
+```text
+globalTime = frame / fps
+localTime = max(0, globalTime - shot.start)
+state = sceneAt(localTime, resolvedTokens, loadedAssets, layout, seed)
+```
+
+This is pseudocode, not a command or available function. Adapt it to the real renderer. Avoid playback history, wall-clock timers, unseeded randomness and incremental position updates as the source of render state. Preload assets and fonts before captures. Pin environment/dependency versions when exact image comparison matters; reproducible time alone does not ensure identical pixels across machines.
+
+Use one timeline for visual cues and any chosen audio cues. Recompute dependent timing when voice or source action changes. Sound remains optional; a shared cue aligns intent but does not establish perceived synchronization. Respect the effective music/SFX exclusions.
+
+For a new temporal implementation, sample the same important state directly and after out-of-order seeks in the same environment. Compare the output, not only whether the API returned successfully. Skip repeating this check for an unrelated copy change when the temporal implementation remains valid.
+
+## 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.
+
+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.
+
+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.