editorbrain 0.12.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editorbrain",
-  "version": "0.12.0",
+  "version": "0.26.0",
   "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.
 
@@ -20,6 +20,8 @@ Read `check_workflow` at the start and relevant checkpoints before proposals, pa
 
 Read `context.memory.confirmed` with its conditions and compare `context.contextVersion` before costly work; retrieve changed documents without overwriting local edits. Suggestions are not instructions, a receipt is not compliance, and prose memory does not bypass required tokens. A web change applies when queried, not by interrupting an active tool.
 
+Use the checkpoint's personal integrations to choose feasible resources. They are this member's declarations, not credentials or live connection checks. Verify the selected provider's actual tool/account access in this session; never borrow another member's connection. Keep proposals viable with available footage and tools; do not require a paid integration. Read [integrations](references/integrations.md) when configuring or using one, and respect provider preferences and the task's authorized spending.
+
 ## Inspect and retrieve evidence
 
 Inspect actual source content, action, usable intervals, motion and relevant audio. Filenames, metadata, inventory and tags are leads, not content review. Declare modality and coverage limits; snapshots prove neither motion nor sound. Optional [local production helpers](references/local-production.md) provide technical measurements without uploading footage or certifying content inspection.
@@ -30,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 the current review preference and confirmed scoped memory. Compare `contextVersion` at later checkpoints; fetch changed files 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,19 @@ 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
+`get_integrations` / `set_integration` or `editorbrain integrations list` /
+`integrations set <provider-id> --file settings.json --expected-revision N`.
+`integrations catalog` works offline; `list --details` adds provider descriptions.
+The [integrations guide](integrations.md) covers the small settings schema, member
+scope and connection checks. These commands do not connect or invoke providers.
+
 ## Workspace and installation
 
 An existing account normally starts with:
@@ -17,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.
 
@@ -55,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.
@@ -97,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/integrations.md

@@ -0,0 +1,73 @@
+# Optional creative integrations (0.13+)
+
+EditorBrain remembers personal tool preferences for the signed-in member in the
+active workspace. A different member has independent settings. Browser login,
+device login and OAuth for that same member share them; a legacy API key without
+a member uses a separate connection profile. Never infer another person's access.
+
+## Read and use
+
+Read the compact `integrations` returned by `check_workflow` at normal checkpoints.
+Use `get_integrations` / `editorbrain integrations list --details` only for setup
+or missing detail. The workflow version changes when these preferences change;
+this is a pull at checkpoints, not a push into a running agent or render.
+
+An enabled entry means **the user declared access**, not that the provider is
+connected, funded or entitled to every model. Before relying on a provider, inspect
+the current session's available connector/CLI/API and use a non-generating check
+when available. Recheck after authentication errors or a change of session/account.
+Do not send media or start a generation just to check a connection.
+
+Use preferred model, voice, language and music mode only where supported. Free-form
+instructions describe editorial preferences; they do not grant credentials or
+override the task, required brand constraints or provider permissions. An explicit
+request for a different provider can override a saved default for that task; do
+not silently change the saved profile. Lack of a declared provider is not proof
+that an existing session tool is unavailable—verify it if the user requests it.
+
+`spending: ask` means confirm the concrete paid operation unless already approved.
+`use-approved-budget` permits using only the budget already authorized for this
+task, not unrestricted spending. A setting is not a billing limit enforced by
+EditorBrain. Check provider cost, relevant usage rights and actual account access
+when needed; do not assume a web subscription includes API credits.
+
+If access is missing, offer a viable alternative with existing material or ask
+for the one necessary connection. Do not silently substitute a different paid
+provider. Browser/files access may need a manual handoff; say so in the proposal.
+
+## Configure only when requested
+
+Web: **Integraciones**. CLI example:
+
+```sh
+editorbrain integrations list
+editorbrain integrations set elevenlabs --file settings.json --expected-revision 0
+```
+
+Use the returned revision, not the example's `0`, after any previous save.
+The JSON replaces that provider's preferences:
+
+```json
+{
+  "enabled": true,
+  "accessMethod": "agent",
+  "preferences": {
+    "language": "es-MX",
+    "musicMode": "instrumental",
+    "spending": "ask",
+    "instructions": "Voz natural y ágil. SFX discretos."
+  }
+}
+```
+
+Methods: `agent` (existing connector/MCP/CLI), `api`, `browser`, `files`; only those
+listed for the provider are accepted. Other optional preference keys: `model` and
+`voiceId`. Set `enabled: false` to disable while retaining chosen preferences.
+Unknown fields/providers are rejected. On a revision conflict, read current state
+and reconcile; do not retry blindly. Keep secrets out of preference text/JSON.
+
+This phase stores preferences only. It neither installs provider skills nor holds
+their keys, proxies generation, uploads media or guarantees a connection. Discover
+the chosen provider's current schema/docs in the actual host when using it. Record
+only the selected resource's relevant provenance in the project; do not copy the
+member's whole integration profile into shared style/brand files.

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/media-preferences.md

@@ -0,0 +1,23 @@
+# Image and motion preferences
+
+Read effective `mediaPreferences` from `resolve_project` / `editorbrain resolve <id>` or `check_workflow`'s context. This compact value includes IDs, versions, favorites/defaults/exclusions and optional density, energy and contrast. Do not read the entire catalog or load every image at startup.
+
+- `favorite`: a candidate, not a mandatory technique. `default`: a starting point, still check fit. `avoid`: exclude. Missing choices mean unspecified.
+- `motionSelection: "adaptive"` lets the editing agent choose motion per scene, including no animation; favorites guide that choice and effective `avoid` entries always exclude. Saved motion defaults appear as favorites in the effective adaptive view; do not erase or rewrite the original choices. `"guided"` starts from saved choices and still checks scene fit. A disabled motion category stays disabled in either mode. If the profile omits this field, a previous motion default keeps guided mode; otherwise the effective mode is adaptive. The mode selects no recipe by itself and never changes brand tokens or grants tool/spending permission.
+- `motionProduction` describes how to produce, independently of selection: `auto` (also the absent-field default) chooses per scene and verified resources; `code` prefers complete editable JavaScript scenes such as workflows, product assemblies and interfaces; `ai` prefers generated clips where appropriate. Keep exact text, values and interface states in controlled composition even when using generated footage. These are preferences, not proof that a renderer or model is available.
+- Before AI video, use the current member's integration checkpoint and verify the session's actual tool, supported model and existing authorization; see [integrations](integrations.md). An enabled provider is declared access, and `files` means existing assets, not a generation connection. A model such as Kling must be available through the chosen tool/account; never infer it from a provider name. Missing access calls for a clear limitation and viable alternative, not a silently enabled provider, paid substitution or erased preference. An `ai` preference grants no spending permission; reuse task approval when it already covers the operation. Keep member/provider/model settings out of shared brand files.
+- `get_media_style` (`styleId`, optional `version`) or `editorbrain media style <id> --style-version <version>` supplies the exact recipe, adaptation rules and illustrative images. View the relevant example when appearance matters. `list_media_styles` / `editorbrain media styles --category image|motion` is for discovery only.
+- Catalog recipes are authored concepts, not certified transfer tests. Generated image examples do not prove a real event, product specification, animation timing or sound. “Vector” examples are raster illustrations of a visual style, not editable SVG assets.
+- Brand tokens still govern graphic colors and fonts. Keep authentic skin/product/logo colors. Do not inherit example palettes, topics or faces. User-selected visual taste guides density/motion/contrast; soft contrast must preserve legibility.
+- Brand selections live in the managed editorial profile in `design.md`. Project `mediaStyleOverrides.image` / `.motion` may be `{ "mode": "inherit" }`, `{ "mode": "disabled" }`, or `{ "mode": "replace", "selections": [{ "styleId": "quiet-reveal", "version": "1.0.0", "state": "default" }] }` for the matching category. Preserve unrelated fields and validate before saving.
+- Preserve the optional profile field `motionSelection` when editing other preferences. The effective `motionSelectionSource` is `brand`, `project` or `implicit`; an explicit brand mode overrides legacy inference, while project category overrides still determine the active selections and exclusions. Older installed CLI bundles may not support the field: never silently drop it or rewrite historical artifacts.
+- Preserve optional `motionProduction` as well. Its effective source is `brand` when explicit and `implicit` otherwise; do not derive a permanent brand preference from the current member's tools. Catalog 1.2.0 adds `workflow-scene`, `product-assembly` and `interface-story` as optional scene concepts, not fixed prompts or proven renders. Retrieve only the relevant recipe and inspect an available rendering skill/tool before implementation.
+- Catalog 1.3.0 adds six optional motion compositions at recipe version `1.0.0`: `editorial-atlas` (collection and detail), `object-headline` (subject and editorial headline), `visual-correspondence` (two related representations), `context-triptych` (three complementary perspectives), `process-filmstrip` (stages and expanded scene), and `tactile-notes` (stable workspace with notes by state). These IDs require CLI 0.17.0 or a newer compatible bundle for local pull/validate/resolve; an updated server or skill alone cannot update an old executable's catalog. Use the verified official release; never erase unsupported selections or mutate old bundles. Retrieve only the selected recipe, recompose its 1:1, 9:16 or 16:9 layout, and preserve editable text and required brand tokens. The source supports a composition, not an inferred easing, SFX, technical claim or proven transfer. New illustrative resources and code are production options subject to the actual b-roll choice, available tools and task authorization; a generated preview is not customer material.
+- Catalog 1.4.0 adds eight `motion` IDs at `1.0.0`, requiring CLI 0.18.0+: `subject-depth`, `route-journal`, `focus-reveal`, `transformation-wipe`, `evidence-spotlight`, `interface-walkthrough`, `quote-portrait`, `type-poster`. Prior recipes and the 24-selection limit are unchanged. Retrieve only the selected recipe. A route needs verified geography or an illustrative label; a reveal needs the same object; comparisons need aligned, honestly labeled states; claims and quotations need verified sources. Interface demos prove no integration or capability. Timing, cursor, wipes and reveals may be authored adaptations, not measured source behavior. No design overrides brand tokens, source restrictions or authorizes spending.
+- Preserve optional `editorialDelivery`; retrieve only its explicit choices from `mediaPreferences.editorialDelivery`. Missing keys are yours to decide from the actual material and brief. `narration: original|voiceover|none` means preserve supplied speech, prefer off-screen narration, or omit narration (not all ambient audio). Voiceover grants no cloning, provider or spending permission. `onScreenText: minimal|key-points|detailed` controls graphic text, independently of subtitles. `broll: footage|stills|mixed|none` controls supporting-media format, not sources or rights; existing `assets` and `avoid` still constrain it. `captionLanguage: source|brand` uses verified speech language or `language.json.defaultLanguage`; never enable disabled captions because a language is selected. Explicit project output settings prevail. Keep brand language, output dimensions/fps and target duration in their existing language/output/brief contracts rather than copying them into this object.
+- `captionTreatment: clean|word-highlight|karaoke|boxed` means plain captions, selected keywords, word-by-word timing, or a readable background. Karaoke requires verified speech timing. `captionPosition: lower|center|adaptive` guides placement subject to framing, faces and safe areas. Omission creates no new default, and legacy caption labels do not infer these fields. `Sin subtítulos` or an output profile with captions disabled excludes all three caption details (language, treatment, position) from the effective view; do not reactivate them from the saved profile or erase them when editing unrelated preferences.
+- `ctaGoal: adaptive|follow|comment|visit|contact|none` sets a reusable intention, not the final CTA. `ctaTreatment: adaptive|end-card|overlay|spoken` guides its presentation. `none` excludes every CTA and suppresses its treatment in the effective view while preserving the saved detail. Missing/adaptive choices remain yours to decide per project. Confirm actual CTA copy, keyword and destination in that project's brief or direction; never invent an account, URL, offer, automation or keyword, or persist demo copy as brand preference. A spoken CTA grants no voice generation or rewriting permission and cannot override no narration. Older bundles may not recognize these fields: use a compatible release, never drop user choices or rewrite immutable archives.
+- Treat exclusions as constraints on general preferences: `Sin efectos de sonido` excludes SFX even with `Música y efectos presentes`; `Sin música ni efectos` excludes those layers but may retain speech according to narration. Do not silently erase the saved preference to resolve a conflict. Apply the restriction and explain material consequences. Existing approval remains scoped to its task; these choices are not new authorization.
+- Check both workflow `version` and `contextVersion` at existing checkpoints. CLI supports `workflow check --project ID --previous-version HASH --previous-context-version HASH`. If media preferences changed, reload affected context before proposing, generating or rendering. Do not restart approved work unless the change affects it.
+
+The optional cloud brand proposal is additional guidance only after user acceptance; it does not replace explicit onboarding choices, tools available in the current session or the customer's project brief.

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
@@ -83,7 +85,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 +104,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,51 @@
+---
+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.
+- **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.