editorbrain 0.8.0 → 0.9.0

package/README.md

@@ -5,13 +5,13 @@ Editorial references, brand context and portable video projects for Claude Code
 Inspect the CLI without configuring your agent:
 
 ```sh
-npx editorbrain@0.8.0 help
+npx editorbrain@0.9.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.8.0
+npm install -g editorbrain@0.9.0
 editorbrain login --url https://api.editorbrain.com
 editorbrain status --url https://api.editorbrain.com
 editorbrain projects list

package/bin/editorbrain.mjs

@@ -327,7 +327,7 @@ Describe identity, audience, non-negotiables and preferred visual/audio treatmen
     ".editorbrain/memory/preferences.json": json({ confirmed: [], note: "Only explicitly confirmed feedback becomes a reusable preference. Keep scope and evidence." }),
     [`videos/${project}/project.json`]: json({ id: project, brand, style, outputProfile: "vertical", intent: { topic: options.topic ?? "Define the subject of this video", goal: options.goal ?? "Explain the subject clearly" }, script: "", overrides: {} }),
     [`videos/${project}/brief.md`]: "# Brief\n\nDescribe the objective, audience, script or source video, constraints and available assets.\n",
-    [`videos/${project}/direction.md`]: "# Direction\n\nDIRECTION_PENDING\n\nRead the installed EditorBrain skill and its AGENTS.md. Inspect the actual script, media, brand and selected evidence. State the intended transfer: faithful preset, editorial family or inspiration. Connect each beat to its meaning, resource/action, composition, motion, real timing and verification. Distinguish observed evidence, inference and new design. Define layer treatments, justify source reuse, and review movement and SFX in the final render. Preserve reference hashes and project-scoped feedback. A plan is not an executed or verified edit.\n"
+    [`videos/${project}/direction.md`]: "# Direction\n\nDIRECTION_PENDING\n\nRead the installed EditorBrain skill and its AGENTS.md. Analyze the actual script and media yourself, read brand constraints, and retrieve candidates with search_from_brief. Inspect selected evidence and judge fit yourself. Save the inspected source coverage and the current review preference/version. State the intended transfer: faithful preset, editorial family or inspiration. Connect each beat to its meaning, resource/action, composition, motion, real timing and verification. Distinguish observed evidence, inference and new design. Define layer treatments, justify source reuse, and review movement and SFX in the final render. Preserve reference hashes and project-scoped feedback. A plan is not an executed or verified edit.\n"
   };
 }
 function canonicalDocumentPath(path) {
@@ -777,7 +777,7 @@ import { createHash } from "node:crypto";
 import { constants as constants2 } from "node:fs";
 import { lstat as lstat2, open as open2, readdir as readdir2, rename as rename2 } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-var previousSkillHashes = { "SKILL.md": ["9df2c89deeec30ddf556c359027efe1d90e6b4e9c08717cd8827e210b38a187f", "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "1b07de01698a0040b47ea0eddb1b017f70a69e81acd0bf9710647ca5e02f5125"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "666082653efc000f8a7cc5f1836c80bbdda5f0f57cdbbdcb393f2b84aeb93a01"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf"] };
+var previousSkillHashes = { "SKILL.md": ["9df2c89deeec30ddf556c359027efe1d90e6b4e9c08717cd8827e210b38a187f", "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9", "1e2fff65a1b303b18b2d65156bef6eb2439a19d77ba2a25b37bcb1819ff009e3"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "1b07de01698a0040b47ea0eddb1b017f70a69e81acd0bf9710647ca5e02f5125", "b5ee3439ff974c668755816149fab76899d7ad9266f63978b30fbc9b7d2cd640"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "666082653efc000f8a7cc5f1836c80bbdda5f0f57cdbbdcb393f2b84aeb93a01", "78b737796a8685b1135e0acb91b620c51845b62e31dba04eb51dd9dd38b41008"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf", "97053b092e0ff36e3cfb764095fcb4a4fca94e722567e774b53bc118279f40e5"] };
 var destinations = {
   codex: { directory: ".agents/skills/editorbrain", entryPoint: "AGENTS.md" },
   claude: { directory: ".claude/skills/editorbrain", entryPoint: "CLAUDE.md" }
@@ -1363,6 +1363,7 @@ editorbrain projects list
 editorbrain documents list [--prefix path]
 editorbrain documents get <path>
 editorbrain workflow check [--project id] [--previous-version hash]
+editorbrain search brief --file <editorial-brief.json> [--project id] [--mode styles|events|both] [--review direct|directions|sample]
 editorbrain search edit [--script file | --video file | --asset sha256 | --project id] [--requirements text] [--assets tag,tag] [--mode styles|events|both] [--review direct|directions|sample]
 editorbrain library search [query]
 editorbrain library get <video-id> [--document relative-source-path] [--sha256 source-hash]
@@ -1391,7 +1392,7 @@ function parseArgs(argv) {
   const positional = [];
   const flags = {};
   const booleans = /* @__PURE__ */ new Set(["help", "version", "offline", "dry-run", "key-stdin", "invite-stdin", "no-browser", "skip-mcp", "all"]);
-  const known = /* @__PURE__ */ new Set(["dir", "brand", "style", "project", "topic", "goal", "name", "adapter", "out", "url", "document", "mime", "label", "role", "limit", "cursor", "timeout", "assets", "capabilities", "duration", "agent", "workspace", "prefix", "sha256", "kind", "channel", "epistemic-status", "event-offset", "relation-offset", "script", "video", "asset", "requirements", "mode", "review", "previous-version", ...booleans]);
+  const known = /* @__PURE__ */ new Set(["dir", "brand", "style", "project", "topic", "goal", "name", "adapter", "out", "url", "document", "mime", "label", "role", "limit", "cursor", "timeout", "assets", "capabilities", "duration", "agent", "workspace", "prefix", "sha256", "kind", "channel", "epistemic-status", "event-offset", "relation-offset", "script", "video", "asset", "requirements", "mode", "review", "previous-version", "file", ...booleans]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -1743,6 +1744,26 @@ async function main() {
     output(await client.request("/v1/workflow/check", { method: "POST", body: { projectId: str(args, "project"), previousVersion: str(args, "previous-version") } }));
     return;
   }
+  if (command === "search" && subcommand === "brief") {
+    const path = str(args, "file");
+    if (!path) throw new Error("Provide --file with the editorial brief JSON after inspecting the actual material.");
+    const handle = await open4(resolve4(path), constants4.O_RDONLY | constants4.O_NOFOLLOW);
+    let brief;
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size < 1 || stat.size > 32e3) throw new Error("Brief must be a regular UTF-8 JSON file of at most 32000 bytes.");
+      brief = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await handle.readFile()));
+    } finally {
+      await handle.close();
+    }
+    if (!brief || typeof brief !== "object" || Array.isArray(brief)) throw new Error("Brief must be a JSON object. See the installed search-brief reference.");
+    const mode = str(args, "mode") ?? "both", reviewMode = str(args, "review");
+    if (!["styles", "events", "both"].includes(mode)) throw new Error("--mode must be styles, events or both.");
+    if (reviewMode && !["direct", "directions", "sample"].includes(reviewMode)) throw new Error("--review must be direct, directions or sample.");
+    const client = new Client(await config(args));
+    output(await client.request("/v1/search/brief", { method: "POST", timeoutMs: 9e4, body: { brief, projectId: str(args, "project"), mode, reviewMode } }));
+    return;
+  }
   if (command === "search" && subcommand === "edit") {
     const client = new Client(await config(args));
     const scriptPath = str(args, "script"), videoPath = str(args, "video");

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -25,7 +25,7 @@ editing question. Existing proposals or other project documents can be discovere
 Read [the workspace file map](references/workspace-files.md) for the full structure, required/optional files and token precedence. Start with `videos/<project-id>/project.json` to discover the selected brand, style and output profile. Read their actual files plus the brief and direction; do not assume that all documents under the workspace are included automatically by `resolve`.
 
 - Consult style packs for methods and the reference library for their execution. Search by communicative function as well as topic: comparison, demonstration, reveal, cumulative typography, collage, atmosphere, callback.
-- Start with `search_for_edit` / `editorbrain search edit`, supplying the actual script or owned video and the project ID for brand constraints. It analyzes new material before semantic retrieval and candidate review; inspect its uncertainty, source hashes, coverage and missing assets. Its model reading is not human verification. Legacy literal search and rule-based recommendations remain lookup tools, not equivalents to this content-first flow.
+- Analyze the actual source yourself, then call `search_from_brief` / `editorbrain search brief` with your editorial brief and project ID. See [search brief](references/search-brief.md). EditorBrain retrieves candidates; you judge fit and inspect visual evidence. A retrieval rank is not creative review. Do not automatically call the optional server-analysis path or upload source footage. Declared inspection and hashes are your record, not server verification.
 - Read `check_workflow` at the start, before proposals, before paid resource generation, and before the full render. Precedence: current explicit user request > project reviewMode > workspace default. Direct means proceed and review; directions means offer 2–3 fitting options with labelled library evidence; sample means show a representative customer-material frame or short clip and obtain approval. Do not require a new approval when the relevant version is already approved. Use a moving sample when rhythm or sound is what needs review. Save the workflow version and any approval with the project direction. A receipt acknowledges reading, not actual compliance.
 - Retrieve evidence to answer a concrete question. Use representative images for composition; intervals and source video for movement; the audio review and accessible audio for sound; narrative events and relations for hooks, development, payoff and CTA.
 - Read source documents using paths actually returned by the reference manifest. Pin hashes where supported. A script summary is not word-level alignment, and a provider candidate is not a verified measurement.

package/skill/editorbrain/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: editorbrain
-description: Use EditorBrain to edit a user's video, adapt an editorial style, find reference evidence, or manage brand and video project context through its CLI or MCP. Connect the project's actual footage, script and brand to editing decisions, then implement and review the result with the available editing tools. Also use when the user names EditorBrain, requests its library or asks to follow a saved preset.
+description: Edit a user's video with EditorBrain's brand files, reusable styles and reference evidence through its CLI or MCP. Inspect the actual script/media, retrieve relevant examples, adapt them, implement with available editing tools and review the result. Also use when the user names EditorBrain or requests a saved editing style.
 ---
 
 # EditorBrain
 
-The public product is EditorBrain. The npm package is `editorbrain`; `editorbrain` is the CLI command. Skill name and portable folder paths use `editorbrain`. Web: https://editorbrain.com. API/MCP: https://api.editorbrain.com/mcp.
+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.
 
-Convert reference evidence into an appropriate edit for this project. Reading the library starts the work; quality is demonstrated in the delivered video.
+## Start here, including a first installation
 
-Before selecting a style, use `check_workflow` (CLI: `editorbrain workflow check`) and `search_for_edit` (CLI: `editorbrain search edit`) with the actual script or owned production video and project ID. Respect the returned review mode: direct editing, a choice of directions, or approval of a customer-material sample. Check the preference version again before costly generation and full rendering; a web change cannot interrupt a running tool. Honor current explicit user instructions and existing approval. If these tools are unavailable, report the version limitation and inspect material and evidence explicitly; literal search is not an equivalent quality ranking.
+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. 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. 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. 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.
+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.
 
-1. Read the bundled [AGENTS.md](AGENTS.md) before using the workflow. It is this skill's editorial contract; do not assume your host auto-loads it.
-2. Read [CLI and MCP](references/cli-mcp.md) when connecting, locating documents, retrieving reference media or saving work. Discover the installed CLI help and connected MCP tool schemas; they take precedence over examples for version-specific arguments.
-3. Read [Workspace files](references/workspace-files.md) when configuring a brand/style, creating projects, resolving preferences, saving feedback or upgrading an installed skill.
-4. Read [Production and review](references/production-and-review.md) when translating a style into scenes, generating assets, implementing motion/audio, or evaluating an edit.
+Use [workspace files](references/workspace-files.md) when changing branding/styles or saving feedback. Keep `design.md`, `effects.md` and `music.md` editable at their own scopes; they guide coherent choices, not identical edits for every topic. Preserve customized instructions and previous versions. Fetch further evidence only to answer a concrete editing question.
 
-Honor the user's requested scope. A consultation needs a supported answer; a direction request needs a usable plan; an editing request needs implementation and review, not just an exported JSON. Continue authorized work without requiring approval at every stage. If a needed tool or asset is unavailable, state the exact limitation and complete independent work.
-
-EditorBrain supplies brand context, styles and a curated evidence library. The agent uses the project's available editing/rendering tools to produce video. Neither a recommendation nor an export certifies a finished edit.
+Public web: https://editorbrain.com. CLI/package/skill: `editorbrain`. MCP: https://api.editorbrain.com/mcp. Source analysis by you, library retrieval by EditorBrain, selection and execution by you. A retrieved reference, export or model opinion does not certify render quality.

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

@@ -1,6 +1,6 @@
 # CLI and MCP: read, retrieve, save
 
-Use the connected MCP schema and `editorbrain help` to confirm the installed contract. Examples below describe the 0.7.0 customer workflow; older installations may lack the skill installer or reference-media tool. Do not invent commands from historical architecture documents.
+Use the connected MCP schema and `editorbrain help` to confirm the installed contract. Examples below describe the 0.9.0 customer workflow; older installations may lack the skill installer or reference-media tool. Do not invent commands from historical architecture documents.
 
 API/MCP: `https://api.editorbrain.com/mcp`. The host must connect this server separately; installing a skill does not register or authorize MCP.
 
@@ -134,35 +134,16 @@ Codex can use `codex mcp login editorbrain`; Claude Code completes OAuth from `/
 `editorbrain library media <video-id> --sha256 <media-hash> --out <new-file>` downloads an authorized frame/audio/video and verifies its hash (90 MiB maximum). It will not overwrite an existing file. Downloading is not reviewing: inspect it with available visual/audio tools and record the intervals actually checked. Neither CLI nor MCP ingest customer references.
 
 
-## Content-first search and web preferences (0.8+)
+## Agent-led search and web preferences (0.9+)
+
+Inspect the actual source yourself, then read [search brief](search-brief.md) for the request schema.
 
 ```sh
 editorbrain workflow check --project my-video
-editorbrain search edit --script ./script.txt --project my-video --mode both
-editorbrain search edit --video ./analysis-proxy.mp4 --project my-video
+editorbrain search brief --file ./videos/my-video/plans/search-brief.json --project my-video
 editorbrain workflow check --project my-video --previous-version <returned-hash>
 ```
 
-MCP equivalents: `check_workflow` and `search_for_edit`. Use their current schemas.
-A topic alone is insufficient. A project may supply its saved script; passing a video
-uploads that selected production asset to the workspace, then sends it to the configured
-analysis provider. This is customer material, not a new library reference. No automatic
-scraping, FFmpeg installation, asset generation or rendering occurs.
-
-Video inputs currently accept MP4/MOV/WebM up to 12 MiB and 24,000 analysis input tokens.
-For a larger source, prepare a complete analysis proxy with the available media tools;
-keep the original and record duration/coverage. If using excerpts, disclose omitted
-content. Never treat coarse model timing as frame-accurate or inferred sound as verified.
-Scripts accept up to 16,000 characters. Search may take longer than a literal lookup.
-
-Results include source hashes, observed/inferred limitations, applicable evidence,
-missing resources, current workflow version and per-stage elapsed time/token usage.
-A null token count means the provider did not report it, not zero. Follow pinned
-source paths and retrieve needed example media; do not enumerate the entire library.
-If no fit exists, disclose the gap rather than fabricate a matching style. Source,
-reference access or preference changes during a search invalidate that result.
-
-Web preferences are pulled at checkpoints, not pushed into arbitrary agent chats.
-`check_workflow` records a receipt; it cannot stop a tool already running. After a
-version change, reconcile the next step and relevant approval with the current user
-instruction. Do not repeat approval just because an unrelated preference changed.
+MCP equivalents: `check_workflow` and `search_from_brief`. Search returns candidate evidence; you inspect it, compare applicability, choose and implement. It does not upload or re-analyze your source video. Older `search_for_edit` / `search edit` remains compatible as an explicitly chosen server-analysis option; it is not the default and must not be an automatic fallback.
+
+Web preferences are pulled at checkpoints, not pushed into arbitrary agent chats. A receipt acknowledges reading; it cannot stop a running tool. Reconcile relevant changes before the next step. Respect existing scoped approval. Server timing/token telemetry excludes the host agent's own work.

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

@@ -0,0 +1,27 @@
+# First edit: from an empty folder to reviewed output
+
+Use this only when the user's environment or project is not ready. Do not re-onboard an existing project.
+
+## 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.
+- 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.
+
+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.
+
+## Keep a resumable editing record
+
+Save only what helps the next session:
+
+- `videos/<id>/plans/search-brief.json`: your current inspected-source brief for retrieval, including source hashes when available. This is local working data, not automatically synced context.
+- `videos/<id>/direction.md`: selected reference IDs/document hashes, rejected conflicts if useful, adaptations, per-beat decisions, required assets, review preference/version and scoped approval. This portable document is synchronized explicitly.
+- `assets/`, `plans/`, `renders/`, `reviews/`: local production files. Create them when needed. Local paths are not cloud uploads; never persist temporary media URLs or credentials.
+- A final review identifies the actual file/hash and what was checked: story, visual composition/motion, text, audio and technical delivery. Record unchecked modalities. Promote feedback to a shared brand/style only at its intended scope.
+
+The first edit follows the same quality contract as later edits: actual source inspection → brief → evidence → adaptation → implementation → final review. These are responsibilities, not a mandatory number of scenes or effects. A small revision may reuse current evidence; a materially changed source or brief needs refreshed reasoning and relevant retrieval.

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

@@ -0,0 +1,44 @@
+# 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.
+
+```json
+{
+  "source": {
+    "kind": "script",
+    "summary": "A creator compares two ways to organize a desk, then demonstrates the chosen layout.",
+    "inspected": ["script"],
+    "coverage": "Full supplied script read; no footage or audio supplied.",
+    "sha256": [],
+    "excerpt": "Optional short passage preserving the actual argument, not a rewritten claim."
+  },
+  "goal": "Make the difference between the two layouts understandable",
+  "audience": "People working from a small home office",
+  "tone": "Practical and calm",
+  "pacing": "Hold comparisons long enough to read; accelerate simple setup steps",
+  "availableAssets": ["User-supplied script"],
+  "missingAssets": ["Footage demonstrating both layouts"],
+  "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"]
+}
+```
+
+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.
+
+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.
+
+```sh
+editorbrain search brief --file videos/my-video/plans/search-brief.json --project my-video --mode both
+```
+
+`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.
+
+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.
+
+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

@@ -34,6 +34,7 @@ videos/<project-id>/
   media.json                      Production asset metadata (optional)
   assets/                         Local production media
   plans/                          Local plans and implementation notes
+    search-brief.json              Agent analysis for retrieval (local, not auto-synced)
   renders/                        Rendered files
   reviews/                        Reviews tied to a particular delivered version
 ```