editorbrain 0.12.0 → 0.18.0

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -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.

package/skill/editorbrain/SKILL.md

@@ -15,7 +15,7 @@ When the user asks to save an edit as a style, create a new style or improve an
 
 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. 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.

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

@@ -4,6 +4,15 @@ 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.
 
+## 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:

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