editorbrain 0.7.0 → 0.8.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.8.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.7.0
+npm install -g editorbrain@0.8.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");
@@ -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"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "1b07de01698a0040b47ea0eddb1b017f70a69e81acd0bf9710647ca5e02f5125"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "666082653efc000f8a7cc5f1836c80bbdda5f0f57cdbbdcb393f2b84aeb93a01"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf"] };
 var destinations = {
   codex: { directory: ".agents/skills/editorbrain", entryPoint: "AGENTS.md" },
   claude: { directory: ".claude/skills/editorbrain", entryPoint: "CLAUDE.md" }
@@ -1361,6 +1362,8 @@ 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 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 +1391,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", ...booleans]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -1735,6 +1738,46 @@ 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 === "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.8.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.
+- 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.
+- 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

@@ -9,6 +9,8 @@ The public product is EditorBrain. The npm package is `editorbrain`; `editorbrai
 
 Convert reference evidence into an appropriate edit for this project. Reading the library starts the work; quality is demonstrated in the delivered video.
 
+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) 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.

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

@@ -132,3 +132,37 @@ 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.
+
+
+## Content-first search and web preferences (0.8+)
+
+```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 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.

package/skill/editorbrain/references/workspace-files.md

@@ -79,3 +79,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.