editorbrain 0.7.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.7.0 help
+npx editorbrain@0.9.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.7.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

@@ -103,6 +103,7 @@ function validateDocument(path, content) {
   if (isProject) {
     for (const key of ["id", "brand", "style", "outputProfile"]) if (typeof doc[key] !== "string" || !identifier.test(doc[key])) add(`${key} must be a valid identifier`);
     if (!object(doc.intent) || !nonempty(doc.intent.topic) || !nonempty(doc.intent.goal)) add("intent requires topic and goal");
+    if (doc.reviewMode !== void 0 && !["direct", "directions", "sample"].includes(doc.reviewMode)) add("reviewMode must be direct, directions or sample");
     if (doc.script !== void 0 && typeof doc.script !== "string") add("script must be text");
     if (doc.overrides !== void 0) {
       if (!object(doc.overrides)) add("overrides must be an object");
@@ -326,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) {
@@ -542,7 +543,7 @@ var Client = class {
     for (let attempt = 0; attempt < 3; attempt++) {
       let response;
       try {
-        response = await this.fetcher(`${this.url}${path}`, { method, headers, body: options.body === void 0 ? void 0 : JSON.stringify(options.body), redirect: "error", signal: AbortSignal.timeout(2e4) });
+        response = await this.fetcher(`${this.url}${path}`, { method, headers, body: options.body === void 0 ? void 0 : JSON.stringify(options.body), redirect: "error", signal: AbortSignal.timeout(Math.min(18e4, Math.max(1e3, options.timeoutMs ?? 2e4))) });
       } catch {
         if (readOnly && attempt < 2) {
           await this.runtime.sleep(250 * 2 ** attempt + this.runtime.random() * 100);
@@ -776,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"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2"], "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" }
@@ -1361,6 +1362,9 @@ editorbrain push [--dir folder] [--dry-run]
 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]
 editorbrain library media <video-id> --sha256 media-hash --out file
@@ -1388,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", ...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("--")) {
@@ -1735,6 +1739,66 @@ async function main() {
     }
     throw new Error("Use narrative search [query] or narrative get <video-id>.");
   }
+  if (command === "workflow" && subcommand === "check") {
+    const client = new Client(await config(args));
+    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");
+    let script, assetId = str(args, "asset");
+    const readInput = async (path, max) => {
+      const handle = await open4(resolve4(path), constants4.O_RDONLY | constants4.O_NOFOLLOW);
+      try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > max) throw new Error(`Input must be a regular file of at most ${max} bytes.`);
+        return await handle.readFile();
+      } finally {
+        await handle.close();
+      }
+    };
+    if (videoPath && assetId) throw new Error("Use --video or --asset, not both.");
+    if (scriptPath) {
+      script = new TextDecoder("utf-8", { fatal: true }).decode(await readInput(scriptPath, 64e3));
+      if (script.length > 16e3) throw new Error("Script must contain at most 16000 characters.");
+    }
+    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.");
+    if (assetId && !/^[a-f0-9]{64}$/.test(assetId)) throw new Error("--asset requires an owned production asset SHA-256.");
+    if (videoPath) {
+      const bytes = await readInput(videoPath, 12 * 1024 * 1024);
+      const mimeType = { ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm" }[extname(videoPath).toLowerCase()];
+      if (!mimeType) throw new Error("Use MP4, MOV or WebM.");
+      assetId = await sha256(bytes);
+      const uploaded = await client.media(`/v1/assets/${assetId}?name=${encodeURIComponent(basename(videoPath))}`, { content: bytes, mimeType });
+      if ((await uploaded.json()).sha256 !== assetId) throw new Error("Upload hash mismatch.");
+    }
+    if (!script && !assetId && !str(args, "project")) throw new Error("Provide --script, --video, --asset or --project with a saved script.");
+    output(await client.request("/v1/search/edit", { method: "POST", timeoutMs: 18e4, body: { script, assetId, projectId: str(args, "project"), requirements: str(args, "requirements") ?? "", availableAssets: (str(args, "assets") ?? "").split(",").filter(Boolean), mode, reviewMode } }));
+    return;
+  }
   if (command === "library") {
     const client = new Client(await config(args));
     if (subcommand === "search") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editorbrain",
-  "version": "0.7.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,8 @@ 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.
-- A literal search is not a quality ranking. Recommendations use explicit rules and declared resources; they do not inspect footage or prove fit. Review their reasons, limitations and required assets against the actual project.
+- 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.
 - Check coverage, truncation and pagination. Retrieve the relevant remaining pages or source document before generalizing to an entire reference. Do not claim complete analysis from a partial tool response.

package/skill/editorbrain/SKILL.md

@@ -1,19 +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
 
-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.
+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.
 
-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.
+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.
 
-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.
 
@@ -132,3 +132,18 @@ Codex can use `codex mcp login editorbrain`; Claude Code completes OAuth from `/
 `editorbrain narrative search [query] --kind hook --channel visual` finds candidates. `narrative get <video-id> --sha256 <document-hash> --event-offset 0 --relation-offset 0 --limit 50` pages through one pinned narrative document; follow returned offsets. Missing narrative coverage stays explicit.
 
 `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.
+
+
+## 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 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_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
 ```
@@ -79,3 +80,13 @@ 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.
+
+
+## Review preference
+
+`videos/<id>/project.json` optionally stores `reviewMode`: `direct`, `directions`, or
+`sample`. Omit it to inherit the workspace default saved in the web app. The current
+explicit user instruction takes precedence. Read the effective value with
+`check_workflow` / `editorbrain workflow check`; local files alone cannot reveal a
+new web preference. Store received versions and scoped approvals in `direction.md`.
+Brand colors/fonts and editing effects/music remain in their existing files.