venice-video-harness 2.11.1 → 2.11.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.11.2 — 2026-08-05
+
+### Changed
+
+- **README: added `HERMES-AGENT-SETUP.md` and trimmed the ACP explainer.** A
+  paste-ready re-setup prompt for Hermes users on an old global install (which
+  shipped only the compiled CLI — no `AGENTS.md`, skills, or MCP) is now linked
+  from the Hermes/OpenClaw quick start. Removed the "ACP does not run the
+  harness" section — it was conceptual myth-busting, not setup or operating
+  guidance — and reworded the "separate runtime" section to stand on its own.
+  The operational runtime/long-render guidance is unchanged. Docs only.
+
 ## 2.11.1 — 2026-08-05
 
 ### Changed

package/HERMES-AGENT-SETUP.md

@@ -0,0 +1,56 @@
+# Setting up the Venice video harness on Hermes (existing / old install)
+
+For a Hermes user who already has an **old** `venice-video` (e.g. a stale global
+`2.6.0`) and wants to re-set-up and use it properly with the published packages.
+
+It upgrades the stale global, adds the MCP server (which almost certainly was
+never installed, since it wasn't on npm before), wires the companion skills, and
+makes the agent read the operating rules before it touches the gated pipeline.
+
+## The prompt to paste into Hermes
+
+```
+Set up the Venice video harness fresh and confirm it works, in this order:
+
+1. Install both packages globally at their latest versions:
+   npm install -g venice-video-harness@latest venice-video-mcp@latest
+   Then confirm the upgrade actually landed: `venice-video --version` must
+   report 2.11.x (an old global like 2.6.0 means the PATH copy didn't update —
+   fix PATH or the npm prefix before continuing).
+
+2. Check the environment: `venice-video doctor` (it verifies the Venice API
+   key, ffmpeg, and ffprobe). If it complains about the key, run
+   `venice-video setup`. Set a workspace you own:
+   export VENICE_VIDEO_WORKSPACE=~/VeniceVideos
+
+3. Register the MCP server by its published bin (no clone, no absolute paths):
+   hermes mcp add venice-video --command venice-video-mcp
+   Make sure the server's env has VENICE_API_KEY and HARNESS_WORKSPACE set,
+   then: hermes mcp test venice-video  (must handshake and list 7 tools).
+
+4. Install the companion skills into Hermes:
+   venice-video-mcp-install-skills --target hermes
+
+5. Before running any workflow, read the operating rules — the pipeline is
+   gated and some stages spend money at queue time:
+   venice-video agent-guide
+   venice-video pipeline --json
+   and read AGENTS.md at "$(npm root -g)/venice-video-harness/AGENTS.md".
+
+Report the version, doctor result, the MCP tool list, and confirm the skills
+are installed.
+```
+
+## Two things to know (the failure modes that make it look broken)
+
+- **The only values you must supply are real:** your Venice API key, and a
+  workspace path you own for `HARNESS_WORKSPACE`. Everything else is defaulted.
+- **If `venice-video --version` still shows the old number after step 1**, npm
+  installed into a different prefix than the `venice-video` on your `PATH`
+  (common with node version managers). The harness README's "Version-drift
+  check" and `venice-video update` both handle this; the quickest tell is
+  comparing `command -v venice-video` against `npm prefix -g`.
+
+After this, you drive it in plain language through Hermes (the MCP tools), or the
+agent runs the CLI directly — either way it now has the embedded `agent-guide`,
+the shipped `AGENTS.md`, and the Hermes skills, instead of guessing from `--help`.

package/README.md

@@ -50,6 +50,13 @@ Both packages are on npm, so an agent whose entire environment is a global
 install and a chat box has a complete, knowledge-bearing setup. Nothing here
 requires cloning a repo or hand-writing a path.
 
+> **Tried the harness or MCP before and got poor results?** Earlier global
+> installs shipped only the compiled CLI — no `AGENTS.md`, no skills, no MCP on
+> npm — so the agent was guessing from `--help`. That is fixed now.
+> [`HERMES-AGENT-SETUP.md`](HERMES-AGENT-SETUP.md) is a paste-ready prompt that
+> upgrades a stale global, registers the MCP, installs the Hermes skills, and
+> points the agent at the operating rules — run it once and re-set-up cleanly.
+
 ```bash
 # 1. Install both globally. The harness ships AGENTS.md + .claude/skills/;
 #    the MCP ships its 7 tools and 4 companion skills.
@@ -132,31 +139,11 @@ same core rules are installable as a skill for runners that pull skills from
 GitHub: `hermes skills install jordanurbs/venice-video-harness/venice-agent-guide`
 (and any of the other `.claude/skills/` by name).
 
-### ACP does not run the harness, and it does not provision a runtime
-
-ACP is the **Agent Client Protocol**, and it is worth being precise about the
-direction it points, because two different readings lead to two different setups.
-
-ACP connects an **editor (the client) to an agent**. The editor spawns the agent
-as a subprocess and speaks JSON-RPC to it over stdio, and the **editor supplies
-the working directory** — in Hermes's adapter, `session/new` receives `cwd` from
-the client and the agent adopts it. So ACP does not start a runtime, does not
-provision a sandbox, and does not move work off the workspace; it standardizes an
-editor driving an agent against a workspace the editor already has open. It is
-also stdio-only and local-trust by design, so there is no remote endpoint in the
-picture.
-
-That means the harness has no position in an ACP conversation. The harness is a
-**tool the agent calls**; ACP describes who calls the agent. The tool-side
-protocol is MCP, which already exists as a separate package. The two stack rather
-than compete: an editor drives your agent over ACP, and that agent drives the
-harness over MCP or a shell.
-
-### Running the harness in a separate runtime (this is the real question)
+### Running the harness in a separate runtime (containers, remote backends)
 
-Starting a fresh runtime to run long workflows off the main workspace is a real
-and useful capability — it is just not ACP. In Hermes it is the **terminal
-backend**, configured independently of any protocol:
+Running long renders off the main machine is a real and useful capability. In
+Hermes it is the **terminal backend**, configured independently of any agent
+protocol:
 
 ```yaml
 # ~/.hermes/config.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venice-video-harness",
-  "version": "2.11.1",
+  "version": "2.11.2",
   "description": "Standalone consistency-first video production CLI powered by the Venice API",
   "homepage": "https://github.com/jordanurbs/venice-video-harness",
   "repository": {
@@ -71,6 +71,7 @@
     "CHANGELOG.md",
     "LICENSE",
     "AGENTS.md",
+    "HERMES-AGENT-SETUP.md",
     ".claude/commands",
     ".claude/agents",
     ".claude/skills",