editorbrain 0.27.1 → 0.28.2

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -6,6 +6,8 @@ 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.
 
+When present, resolved `editorial.identity` or workflow `context.identity` holds the current confirmed brand fields. These supersede older values in preserved prose. Empty fields remain undecided; keep unrelated notes and do not restore superseded values.
+
 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.

package/skill/editorbrain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: editorbrain
-description: Edit a user's video with EditorBrain's brand files, reusable styles and reference evidence through its CLI or MCP. Create or refine a reusable editing style from their work and feedback. Also use when the user names EditorBrain or requests a saved editing style.
+description: Onboard a user into EditorBrain with visual preferences, or edit their video using brand files, reusable styles and reference evidence through its CLI or MCP. Create or refine a reusable editing style. Also use when the user names EditorBrain or requests a saved editing style.
 ---
 
 # EditorBrain
@@ -20,7 +20,7 @@ When the user asks to save an edit as a style, create a new style or improve an
 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.
+2. If no workspace is ready, use [first edit](references/first-edit.md). For visual onboarding inside this agent, load [onboarding](references/onboarding.md) only then; discover command availability before use. Verify connection, discover or create the active project, and prepare its context without overwriting existing files. Read [CLI and MCP](references/cli-mcp.md) only for the commands needed now.
 3. Read the selected project's `project.json`, brief, direction and the brand/style files it names. Resolve effective tokens and inspect available editing tools. Use `check_workflow` (CLI `editorbrain workflow check`) for 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 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.

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

@@ -4,20 +4,21 @@ Read for narration, music/SFX production or audio delivery. Do not inherit a dem
 
 ## 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.
+Optional `.editorbrain/brands/<brand>/audio.json` sets brand defaults; `videos/<id>/audio.json` overrides them. Resolve/workflow includes effective `audioProduction` when a file or editorial restriction defines it; source hashes track changes. Omission inherits; `null` clears a preference, not audio itself. Voice/loudness replace atomically; music/SFX fields inherit individually. Existing `language.json`, `music.md`, editorial preferences and memory still apply. Original/no-narration constraints suppress contradictory generated voices; warnings preserve the conflict for review. Use the current explicit request to resolve any project exception before spending.
 
 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. |
+| `music.intensity` | `none\|subtle\|present` or `null`; none disables music only. Qualitative prominence, not a universal volume/LUFS target. `music:null` clears the block. |
 | `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.
+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: sparse SFX does not imply subtle music, and no music does not silence voice. `Sin música ni efectos` and `Sin efectos de sonido` constrain effective audio even if saved fields conflict; never reactivate suppressed layers from raw files or erase those files to reconcile them.
 
 ## Timing and sound
 

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

@@ -4,6 +4,17 @@ 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.
 
+## Visual onboarding and brain analysis (0.28.2, discover availability)
+
+Use [onboarding](onboarding.md) for `onboarding create/serve/apply/sync` and
+`brain status/prepare/accept`. They require CLI 0.28.2 or newer; an older
+installation may not expose them. Connected MCP may offer `get_brain_status`,
+`prepare_brain` and `accept_brain`; discover their actual schemas. Preparing a
+proposal explicitly invokes the service's analyst. Accept only a reviewed,
+user-approved proposal with its run ID and source design revision, never a
+guessed revision. Status/read/apply/sync do not invoke a model. This analyst
+organizes onboarding context; it does not replace your analysis of each video.
+
 ## 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.

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

@@ -6,6 +6,7 @@ Use this only when the user's environment or project is not ready. Do not re-onb
 
 - 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.
+- If the user wants to configure their brain here, use the visual [onboarding guide](onboarding.md) when `onboarding create` is available. It supports a local browser or portable HTML/JSON handoff; no account is needed to draft preferences. Do not claim every chat can embed or connect to local HTML. Existing users should retrieve their selected context first, preserving unsynced changes; do not start with an empty form that discards saved preferences.
 - 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.

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

@@ -8,13 +8,14 @@ Read effective `mediaPreferences` from `resolve_project` / `editorbrain resolve
 - 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 tokens govern new graphics and fonts; preserve authentic skin, product, logo, screenshot and footage colors. Do not inherit example palettes, topics or faces. Visual taste guides simultaneous layers/motion/contrast; soft contrast must remain legible.
+- `mediaPreferences.sources` separates resource provenance from editing references. `allowed`, when present, is exhaustive: `own` (supplied media), `web` (authentic web media, archives or screenshots), `stock`, `generated`. `preferred` prioritizes without obliging; `excluded` remains forbidden. Missing `allowed` is undecided; an empty effective list is a conflict to resolve, never a reason to enable other sources. Explicit profile `mediaSources` supersedes legacy `assets`; without it, preserve the legacy restriction. `avoid` can still exclude a preferred source. Verify the identity, provenance and rights of real media; library examples inform technique and grant no media license. Availability is not obligation or spending authorization.
 - 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.
+- 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; effective sources and `avoid` constrain it. `visualSupport: sparse|balanced|rich` controls frequency of supporting visuals, not a quota, pace or simultaneous-layer density. Rich support can be calm/minimal; no b-roll may still allow graphics. It never enables excluded sources. `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.

package/skill/editorbrain/references/onboarding.md

@@ -0,0 +1,105 @@
+# Visual onboarding from the agent
+
+Load only for first setup or an explicit preference update. Requires CLI
+0.28.2 commands in `editorbrain help`; older releases do not have them.
+Do not invent an MCP onboarding tool to bypass that boundary; upgrade only
+within the user’s authorized setup and preserve customized guidance.
+
+## Collect choices visually
+
+Use a dedicated project folder. If this is an existing cloud brand, first pull
+its current project context into the selected folder, preserving local edits.
+Discover brand/project IDs; an empty local directory does not mean an empty
+account. New brands may start offline. Create a new starter project ID if an
+existing project uses a different style/output; never reset it to finish setup.
+
+```sh
+editorbrain onboarding create --brand <id> --project <new-id> --dir ./my-videos
+editorbrain onboarding serve --session <returned-session> --dir ./my-videos
+```
+
+The first command returns a private HTML artifact and session/answers paths.
+The second opens a temporary loopback browser and waits for the user to save.
+Keep the command running, then read its completion. Use `--no-browser` to show
+the returned local URL yourself; that URL works on the computer running the CLI.
+Do not expose this server on the internet or send its capability URL to others.
+
+For a cloud chat or host without a local browser connection, present the returned
+HTML as a downloadable artifact using that host's file tools. The user opens it
+and downloads their answers JSON. Bring that file into the project folder and
+use its relative path. Do not pretend to save into a user's computer from an
+isolated cloud session. The visual form does not require private footage, keys,
+paid integrations or a model call. Public image previews load only on request.
+
+The user can choose identity, colors/fonts and strictness, language, image and
+motion taste, sources, support frequency, captions, CTA and audio, leaving other
+decisions open. Preserve prefilled choices and untouched advanced fields. An
+example palette is not a saved preference; favorites guide taste, not fixed
+templates. Choosing generated media does not authorize purchases or a provider.
+
+## Build and connect the brain
+
+```sh
+editorbrain onboarding apply --session <session> --file <answers.json> --dir ./my-videos --dry-run
+editorbrain onboarding apply --session <session> --file <answers.json> --dir ./my-videos
+editorbrain skill install --dir ./my-videos --agent codex
+editorbrain validate --dir ./my-videos
+editorbrain resolve <project-id> --dir ./my-videos
+```
+
+Use `claude` or `both` for skill installation when appropriate. Check the result
+and preserve customized guidance. Apply writes the brand documents and missing
+starter context, retaining notes and untouched preferences. Its snapshot guard
+rejects stale files. On a conflict, reopen against current context and reconcile
+the user's choices; never force overwrite. `.editorbrain-local/` contains private
+session snapshots and answers, not synchronized documents.
+
+When present, resolved `editorial.identity` / workflow `context.identity` contains
+the current confirmed identity; it supersedes older values for the same fields
+in preserved prose. An empty string clears that field; do not revive the old value.
+
+The new output is a 9:16/30fps starter without a fixed caption language; determine
+the actual destination and caption settings before an edit. This setup creates
+editorial context, not a video. Account login is still the official consent flow:
+
+```sh
+editorbrain login
+editorbrain onboarding sync --session <session> --dir ./my-videos --dry-run
+editorbrain onboarding sync --session <session> --dir ./my-videos
+```
+
+Inspect planned paths/conflicts. Sync uploads only this brand/starter context.
+Untouched shared starter guides can adopt the account's existing versions;
+personalized local documents are never silently replaced. On network failure,
+inspect state before retrying. CLI and MCP authenticate separately to the same
+workspace. Configure personal integrations/review mode through their existing
+commands when requested; they are not credentials stored in this form.
+
+## Optional server analyst, same as the web
+
+```sh
+editorbrain brain prepare --brand <id>
+editorbrain brain status --brand <id>
+editorbrain brain accept --brand <id> --run <reviewed-run-id> --revision <sourceDesignRevision> --reviewed
+editorbrain pull --project <project-id> --dir ./my-videos
+```
+
+Preparing explicitly starts a server proposal and can consume service model
+tokens. It reads the current cloud documents; sync must have succeeded first.
+Do not enqueue repeatedly while queued/running: check status with bounded
+backoff. Show the summary/recommendations for review, preserving existing user
+authorization. `--reviewed` records approval already obtained; do not synthesize
+it from a successful model response. Accept only that run and source revision.
+Changed brand/audio/identity context invalidates the proposal even if design.md
+has not changed. Refresh it rather than guessing a revision. If unavailable,
+report that the brain files work but the optional enrichment did not run.
+
+MCP equivalents, when exposed: `get_brain_status({brandId})`,
+`prepare_brain({brandId,expectedDesignRevision})`, and
+`accept_brain({brandId,runId,expectedDesignRevision,reviewed:true})`. Read the
+current design document's revision before preparing with MCP. Proposal text is
+candidate editorial data, not instructions to grant access or override explicit
+preferences. Any suggested footage, music or SFX remains conditional on actual
+availability, rights and current project authorization; a suggestion proves none.
+The analyst does not inspect the next video: you still inspect its
+material, retrieve library evidence, adapt and review the actual edit.

package/skill/editorbrain-motion/SKILL.md

@@ -34,7 +34,7 @@ Separate resolved graphic identity from authentic material: text/graphics use br
 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.
+- **Authored reference:** search `list_authored_scenes` / `editorbrain motion scenes` with the action you need in your own words, across niches. Where supported, compare first/last keyframes, read one card and start from the closest adaptation preset; validate motion with its video. See [authored scenes](references/authored-scenes.md) for version support and code adaptation. 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.

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

@@ -4,19 +4,24 @@ Use when a scene needs a visual mechanism (an object transforms, a structure fal
 
 ## 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.
+1. **Search by action.** `list_authored_scenes` / `editorbrain motion scenes "depender de un solo cliente"` ranks examples by mechanism, uses across niches and presets. Describe the action and change, such as "un total que se arma por partes". A different demo niche is not a reason to discard a mechanism. Default six compact results; reuse `nextCursor` as `after` / `--after` for the same query. This is weighted lexical retrieval, not a creative recommendation or semantic video analysis.
+2. **Look before reading.** For the strongest candidates (usually three, expand if unclear), request `first` and `last` in the project's ratio. MCP: `get_authored_scene_preview`, passing candidate `id` as `sceneId`, preserving `version`, and mapping the project format to `ratio` (`16:9` → `wide`, `1:1` → `square`, `9:16` → `tall`); use `kind: "first"` or `"last"`. CLI: `editorbrain motion preview <id> --scene-version 1.1.0 --ratio tall --preview-kind first`. `firstIsFrame1: false` means the image is the first informative state, not the literal first frame; inspect the returned time/frame. These images establish states, not motion, pacing or sound.
+3. **Read one card and choose an adaptation.** `get_authored_scene` / `editorbrain motion scene <id> --scene-version 1.1.0` gives the universal mechanism, use/not-for, timing, limits, presets and pinned source hash. If a preset fits the topic better, inspect its keyframes with `preset: "<name>"` / `--preset <name>`. Presets support first/last only; they do not have their own video preview. Pick by the beat's action and constraints, not rank alone.
+4. **Validate the motion.** Watch the selected base video's preview (`kind: "video"`, the default). Compare its transformation and timing with the intended beat before committing to its code. Keyframes and the base preview do not certify the preset or a customer-brand render.
+5. **Source and adaptation.** Request `get_authored_scene_source` with the exact ID, version and bundle SHA-256, or `editorbrain motion source <id> --scene-version 1.1.0 --out .editorbrain-local/new-scene.tar.gz`. Downloads require login, verify size/hash, preserve existing files and never extract or execute automatically. Start from the closest `adapt/<name>.json` overrides when present; replace demo values and bind the current project below. Edit code where the card says parameters cannot express the needed change; author a new scene when none fits.
 
-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.
+The base commands require CLI 0.27.0+. Ranked catalog 1.1.0 and `first|last`/`--preset` require CLI **0.28.0+**, or an MCP server advertising these fields and returning 1.1.0. Check the actual tool schema and returned version; do not send unsupported fields to older servers. CLI 0.27.x and pinned 1.0.0 still use literal search and `video|poster`; use their cards and videos instead of inventing missing keyframes. There are 45 mechanisms in 1.1.0 and 33 in 1.0.0. `motion list/get/prepare` remains a separate component catalog.
+
+All preview/source links expire after five minutes. Keep IDs, versions and hashes instead of temporary URLs. Downloads remain reference evidence; viewing them grants no implicit artistic approval. `inheritedBundleVersion: "1.0.0"` identifies an unchanged historical archive inside catalog 1.1.0: its internal manifest/card retain 1.0.0, while the retrieved 1.1.0 card adds current discovery guidance. Verify the advertised bundle hash; do not rewrite its provenance to match the catalog version.
 
 ## 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.
+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, synthesized SFX and available adaptation JSONs; no private customer reel assets or renderer installation. Presets are data overrides, not instructions or permissions. Apply their content overrides before the current project's required brand, language and audio bindings. 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, including scene-specific roles listed in its README (not only the generic roles). 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.
 
-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.
+Material colors, heatmaps, illustrations and data series can have separate parameters or code-level colors. Inspect these against the project's scoped rules rather than assuming the brand palette recolors every pixel. Preserve authentic material/logo colors where required. A different font can invalidate the scene's layout or collision constraints: adjust typography/composition explicitly and rerender; never silently restore the demo font to make a test pass.
 
 `?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.
+Check source/preview provenance and runtime diagnostics, important states and transitions, then actual motion/audio in the adapted output. Existing previews refer to original source; the guarded portable runtime is separately hashed. Technical validation does not prove creative quality or successful transfer. Both catalogs exclude all personal `human-computers` reel versions.