editorbrain 0.4.1 → 0.6.0

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "editorbrain",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "EditorBrain editorial knowledge, portable workspaces and skills for AI video agents",
   "type": "module",
   "license": "UNLICENSED",
   "bin": {
-    "editorbrain": "bin/editorharness.mjs",
-    "editorharness": "bin/editorharness.mjs"
+    "editorbrain": "bin/editorbrain.mjs"
   },
   "files": [
     "bin",

package/skill/{editorharness → editorbrain}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: editorharness
-description: Use EditorBrain (formerly Editor Harness) 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 or Editor Harness, requests its library or asks to follow a saved preset.
+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.
 ---
 
 # EditorBrain
 
-The public product is EditorBrain. The compatible CLI command, skill name and folder paths remain `editorharness`; do not invent an `editorbrain` command. Web: https://editorbrain.com. API/MCP: https://api.editorbrain.com/mcp.
+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.
 
 Convert reference evidence into an appropriate edit for this project. Reading the library starts the work; quality is demonstrated in the delivered video.
 

package/skill/{editorharness → editorbrain}/references/cli-mcp.md

@@ -1,6 +1,6 @@
 # CLI and MCP: read, retrieve, save
 
-Use the connected MCP schema and `editorharness help` to confirm the installed contract. Examples below describe the 0.4.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.6.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.
 
@@ -9,18 +9,18 @@ API/MCP: `https://api.editorbrain.com/mcp`. The host must connect this server se
 An existing account normally starts with:
 
 ```sh
-editorharness status
-editorharness pull --dir ./my-videos
-editorharness skill install --dir ./my-videos --agent both
+editorbrain status
+editorbrain pull --dir ./my-videos
+editorbrain skill install --dir ./my-videos --agent both
 ```
 
-If unauthenticated, `editorharness login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: that host needs the configured workspace bearer credential through its secret mechanism.
+If unauthenticated, `editorbrain login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: register the MCP URL without a bearer header and authorize through the host’s OAuth login. Choose the same workspace in the consent page. Existing bearer-key connections remain compatible; do not overwrite one during setup.
 
-Skill installation is offline and independent of login. It creates `.agents/skills/editorharness/` for Codex and `.claude/skills/editorharness/` for Claude. Open the target folder in the agent and explicitly ask it to read the installed `SKILL.md` if automatic discovery has not refreshed. The skill directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
+Skill installation is offline and independent of login. It creates `.agents/skills/editorbrain/` for Codex and `.claude/skills/editorbrain/` for Claude. Open the target folder in the agent and explicitly ask it to read the installed `SKILL.md` if automatic discovery has not refreshed. The skill directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
 
 Existing root `AGENTS.md`/`CLAUDE.md` are preserved. Read the install result's instruction paths and conflict reports. A preserved root guide does not mean the native skill failed; a conflicting existing skill needs a deliberate merge, not an overwrite. Do not replace the user's custom instructions to finish setup.
 
-For a separate local workspace, `editorharness init --dir ./new-video --brand <id> --style <id> --project <id>` creates portable context and installs guidance. Do not initialize over a pulled workspace to reset it. `pull` and `push` synchronize documents, not the installed native skill folders or local render media.
+For a separate local workspace, `editorbrain init --dir ./new-video --brand <id> --style <id> --project <id>` creates portable context and installs guidance. Do not initialize over a pulled workspace to reset it. `pull` and `push` synchronize documents, not the installed native skill folders or local render media.
 
 ## Reading the project
 
@@ -34,13 +34,13 @@ MCP sequence:
 Use the local files after a successful `pull` when working through CLI. Commands:
 
 ```sh
-editorharness validate --dir ./my-videos
-editorharness resolve <project-id> --dir ./my-videos
-editorharness assets list --limit 200
-editorharness assets download <sha256> --out ./media/clip.mp4
+editorbrain validate --dir ./my-videos
+editorbrain resolve <project-id> --dir ./my-videos
+editorbrain assets list --limit 200
+editorbrain assets download <sha256> --out ./media/clip.mp4
 ```
 
-`assets list` returns `nextCursor`; continue with `--cursor` when needed. MCP `list_assets({})` returns the newest 100 assets, not necessarily the full collection. Project `media.json` is the primary source for project-specific IDs. Asset tags passed to recommendations describe declared resources, not tool-verified contents.
+`assets list` returns `nextCursor`; continue with `--cursor` when needed. MCP `list_assets` also returns `nextCursor`; pass it as `cursor` to retrieve the next page (default 100, maximum 1000). Project `media.json` is the primary source for project-specific IDs. Asset tags passed to recommendations describe declared resources, not tool-verified contents.
 
 ## Selecting a method and examining examples
 
@@ -58,16 +58,16 @@ Discover current argument schemas before calling:
 CLI counterparts for discovery/documents:
 
 ```sh
-editorharness styles list
-editorharness styles recommend <project-id> --dir ./my-videos
-editorharness library search "comparison"
-editorharness library get <video-id>
-editorharness library get <video-id> --document <returned-path>
+editorbrain styles list
+editorbrain styles recommend <project-id> --dir ./my-videos
+editorbrain library search "comparison"
+editorbrain library get <video-id>
+editorbrain library get <video-id> --document <returned-path>
 ```
 
 Recommendations and direction drafts use the saved remote project, require a non-empty script and check that local source context matches it. After `init` or local edits, validate and successfully `push` the intended project context before those calls. Do not discard unsynced local changes to silence a context mismatch. An offline draft can be written by the agent from available evidence without claiming a remote recommendation ran.
 
-The current CLI document command retrieves the latest version; it does not expose a hash pin. For exact historical retrieval use the MCP `sha256` argument, or the authenticated reference-document REST route with its `sha256` query parameter. Do not label an unpinned read as pinned. Keep the actual returned hash in the production record.
+Pin historical evidence with `editorbrain library get <video-id> --document <path> --sha256 <source-hash>`, or MCP `read_reference_document` with `sha256`. CLI checks the returned content hash. Without a pin, the latest version is retrieved; keep the returned hash.
 
 ### Complete enough evidence
 
@@ -88,8 +88,8 @@ Access is scoped to the current workspace's reference grant and credential. A kn
 `draft_direction` proposes an initial method and techniques. Inspect its pending requirements and transfer status, complete the per-beat decisions using evidence and the actual material, then implement the user's requested output. Available CLI:
 
 ```sh
-editorharness direction draft <project-id> --dir ./my-videos --out ./direction-draft
-editorharness export <project-id> --dir ./my-videos --adapter neutral --out ./handoff
+editorbrain direction draft <project-id> --dir ./my-videos --out ./direction-draft
+editorbrain export <project-id> --dir ./my-videos --adapter neutral --out ./handoff
 ```
 
 `export_project({projectId,adapter})` supports `neutral`, `hyperframes` and `remotion`. It returns plans for an external rendering agent/engine; it does not create a video. Inspect the engine's real capabilities before committing to an effect.
@@ -97,9 +97,30 @@ editorharness export <project-id> --dir ./my-videos --adapter neutral --out ./ha
 Save through local portable documents plus `push`, or MCP `write_document` with the revision returned by the last read and the actual schema. To create a new document, use `expectedRevision: 0`; to update an existing one, use its current read revision. Do not guess a revision or force over a conflict; reread, reconcile and retry only if still authorized. Keep generated production notes small enough for the document limit (128 KiB per document); do not duplicate every raw catalog response into a customer workspace.
 
 ```sh
-editorharness validate --dir ./my-videos
-editorharness resolve <project-id> --dir ./my-videos
-editorharness push --dir ./my-videos
+editorbrain validate --dir ./my-videos
+editorbrain resolve <project-id> --dir ./my-videos
+editorbrain push --dir ./my-videos
 ```
 
 `push` is not a media upload. Use `assets upload <file>` for authorized production files within current limits and then record returned IDs/hashes. Keep large renders/evidence in the appropriate media store, with permanent identifiers in the project. Preserve old revisions and disclose unsynchronized local work if saving fails.
+
+
+## Recovery and diagnostics (CLI 0.6.0)
+
+Use `editorbrain version` to discover the installed release. Run `editorbrain doctor --dir <folder> --agent codex|claude|both` before troubleshooting; `--offline` deliberately skips credentials and remote checks. Doctor is read-only. Its `mcpClient: not_verified` is not a claim that the host is connected. A customized skill is reported as a warning, not replaced automatically.
+
+Before reconciling sync problems, use `push --dry-run` or `pull --dry-run`. Read `conflicts` and the planned paths. A preview neither writes nor reserves revisions. Never use a separate workspace to evade a binding mismatch.
+
+Errors include `code`, `hint`, `retryable` and the legacy text `error`. `AUTH_REQUIRED` needs user authorization, `ACCESS_DENIED` needs the right permission, `SYNC_CONFLICT` needs reconciliation, and `WORKSPACE_MISMATCH` requires the correct separate folder. `WORKSPACE_BUSY` means another CLI operation owns `.editorbrain-operation.lock`; do not auto-delete it. After a crash, verify no process is using the folder before removing a leftover lock.
+
+GET requests use bounded retries and respect Retry-After. Writes are not retried automatically: after a network error, inspect remote state before repeating them. Do not treat `retryable` as permission for an unbounded loop. HTTP error bodies are not printed. The MCP now provides matching structuredContent and text; consume either without counting them as separate results. Writing a document is declared mutating and may update existing content even though revision history is preserved.
+
+## Guided setup and OAuth (0.6.0)
+
+`editorbrain setup --dir ./mis-videos --agent codex --workspace <expected-id>` authorizes the CLI when necessary, pulls documents, installs the complete skill and registers an absent MCP connection. Use `claude` or `both` for other hosts. The expected ID is a check, never authorization. Setup preserves existing MCP entries and customized guidance. Exit 2 means action is still required; inspect each step instead of repeating blindly. `--no-browser` defers MCP registration; `--skip-mcp` prepares only the CLI/skill.
+
+Codex can use `codex mcp login editorbrain`; Claude Code completes OAuth from `/mcp`. Native host configuration is not proof of an authenticated MCP. Call `workspace_info` inside the host and compare it with CLI `status`. A read-only consent cannot save documents: ask for editing scope only when needed. Revoke OAuth connections from the app’s connection settings. CLI device credentials and MCP OAuth connections are separate.
+
+`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.

package/skill/{editorharness → editorbrain}/references/workspace-files.md

@@ -1,17 +1,17 @@
 # EditorBrain workspace files
 
-Use this reference when creating a project, changing branding or styles, resolving conflicting settings, or deciding where to save feedback. Technical paths and the CLI remain named `editorharness`; the public product is EditorBrain.
+Use this reference when creating a project, changing branding or styles, resolving conflicting settings, or deciding where to save feedback. Technical paths and the CLI remain named `editorbrain`; the public product is EditorBrain.
 
 ## Discover before editing
 
-Read `videos/<project-id>/project.json` first: its `brand`, `style` and `outputProfile` fields select the context. Discover IDs using the returned documents or local files. Folder names below are placeholders, not literal IDs. For a new local workspace use `editorharness init`; for an existing account use `pull`. Read the generated documents before changing their schema.
+Read `videos/<project-id>/project.json` first: its `brand`, `style` and `outputProfile` fields select the context. Discover IDs using the returned documents or local files. Folder names below are placeholders, not literal IDs. For a new local workspace use `editorbrain init`; for an existing account use `pull`. Read the generated documents before changing their schema.
 
 ```text
 AGENTS.md                         Codex entry point (existing instructions preserved)
 CLAUDE.md                         Claude Code entry point (existing instructions preserved)
-.agents/skills/editorharness/      Codex skill, contract and references
-.claude/skills/editorharness/      Claude Code skill, contract and references
-.editorharness/
+.agents/skills/editorbrain/      Codex skill, contract and references
+.claude/skills/editorbrain/      Claude Code skill, contract and references
+.editorbrain/
   brands/<brand-id>/
     brand.md                      Identity, audience, constraints
     design.md                     Composition and visual treatment (optional)
@@ -38,7 +38,7 @@ videos/<project-id>/
   reviews/                        Reviews tied to a particular delivered version
 ```
 
-The native skill folders are local instructions, not portable documents synchronized by `push`. Local media/render folders are not media uploads. `.editorharness/.sync.json` is CLI-managed sync state; do not edit it to bypass conflicts. An older valid workspace may omit the optional files and local production directories.
+The native skill folders are local instructions, not portable documents synchronized by `push`. Local media/render folders are not media uploads. `.editorbrain/.sync.json` is CLI-managed sync state; do not edit it to bypass conflicts. An older valid workspace may omit the optional files and local production directories.
 
 The resolver requires the selected brand's `brand.md`, `tokens.json`, `language.json`, `assets.json`; the selected style's `style.md`, `style.json`, `examples.json`; the selected output profile; and the project's `project.json`, `brief.md`, `direction.md`. Preserve them even when a declaration is empty. Additional guidance such as `adaptation-rules.json`, library indexes or memory may be present: read it explicitly when relevant. It is not automatically included in `resolve` merely because it exists.
 
@@ -76,6 +76,6 @@ Save reusable feedback at its stated scope: project-only changes in the project,
 
 ## Updating the installed skill
 
-Updating the global CLI does not replace skills already copied into a project. Run `editorharness skill install --dir <workspace> --agent both` and inspect `conflicts`, `preserved`, `warnings` and `readInstructions`.
+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.