venice-video-harness 2.11.0 → 2.11.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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
+
+- **README agent instructions rewritten around the published packages.** With
+  both `venice-video-harness` and `venice-video-mcp` on npm, the Hermes/OpenClaw
+  path is now a plain global install rather than a two-repo clone with
+  hand-written absolute paths. Added a "Quick start for Hermes and OpenClaw"
+  block, rewrote "Registering the MCP server" to lead with the published
+  `venice-video-mcp` bin (and an `npx -y venice-video-mcp` variant) while keeping
+  the clone + `HARNESS_BIN`/`HARNESS_PATH` path as a documented dev alternative,
+  and switched the companion-skills step to the on-PATH
+  `venice-video-mcp-install-skills` bin. Clarified that with both packages
+  installed globally you set none of the harness path variables — the MCP finds
+  `venice-video` on `PATH`. Softened the stale "npm latest trails this repo"
+  version-drift note. Docs only; no code change.
+
 ## 2.11.0 — 2026-08-05
 
 ### Added

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

@@ -41,8 +41,55 @@ knowledge reaches you, which is the single largest predictor of output quality.
 | Surface | How it runs | What you get | Use when |
 |---|---|---|---|
 | **Repo-resident agent** | Agent's cwd is a clone of this repo | Everything: `AGENTS.md` (47 rules, 20 anti-patterns), `.claude/commands/`, `.claude/agents/`, `.claude/skills/`, `.cursor/rules/` | Authoring and iteration — the best results by a wide margin |
-| **MCP** | `venice-video-mcp` shells out to this CLI | 7 action-discriminated tools, structured JSON responses, progress notifications, plus 4 companion skills carrying the pipeline order | Any agent that supports MCP but is not sitting in this repo |
-| **Bare global CLI** | `npm install -g`, shell tool, `--help` | The compiled CLI, this README, and the self-describing commands below (`agent-guide`, `pipeline`) | Last resort, but no longer knowledge-free — start with `venice-video agent-guide` |
+| **MCP** | `venice-video-mcp` (on npm) shells out to this CLI | 7 action-discriminated tools, structured JSON responses, progress notifications, plus 4 companion skills carrying the pipeline order | Any agent that supports MCP — Hermes, OpenClaw, Cursor, Claude — with no clone required |
+| **Bare global CLI** | `npm install -g`, shell tool, `--help` | The compiled CLI, this README, `AGENTS.md`, `.claude/skills/`, and the self-describing commands below (`agent-guide`, `pipeline`) | When your runner has a shell but no MCP — start with `venice-video agent-guide` |
+
+### Quick start for Hermes and OpenClaw (no clone, no absolute paths)
+
+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.
+npm install -g venice-video-harness venice-video-mcp --foreground-scripts
+
+# 2. Point the harness at a workspace and confirm the environment.
+export VENICE_API_KEY=vn_...
+export VENICE_VIDEO_WORKSPACE=~/VeniceVideos
+venice-video doctor          # checks API key, ffmpeg, ffprobe
+venice-video agent-guide     # the core operating rules, inside the binary
+
+# 3a. Hermes — register the MCP by its published bin (it is on PATH now):
+hermes mcp add venice-video --command venice-video-mcp
+hermes mcp test venice-video # confirm the handshake
+venice-video-mcp-install-skills --target hermes   # skills → ~/.hermes/skills/venice/
+
+# 3b. OpenClaw / any MCP runner — same idea, using whatever the runner's
+#     "add MCP server" command is, with command `venice-video-mcp` and the
+#     env below. Install its skills into the runner's skills dir:
+venice-video-mcp-install-skills --dir <that runner's skills dir>
+```
+
+When both are installed globally, the MCP finds `venice-video` on your `PATH`
+automatically — you do **not** need `HARNESS_BIN` or `HARNESS_PATH`. The only
+required env for the MCP process is `VENICE_API_KEY`, plus `VENICE_VIDEO_WORKSPACE`
+(or `HARNESS_WORKSPACE`) if you want projects somewhere other than the cwd. See
+[Registering the MCP server](#registering-the-mcp-server) for the details and the
+one case where you *do* set a path (pointing at a local build).
+
+OpenClaw's exact MCP-registration and skills-directory conventions are not yet
+verified here; the shapes above are what to adapt. `venice-video-mcp-install-skills
+--target openclaw` currently errors on purpose rather than guessing a path — pass
+`--dir` once you know it.
 
 **The bare-CLI trap, and how to check whether you are in it.** Through version
 **2.9.0** the npm package published only `dist`, `README.md`, `CHANGELOG.md`,
@@ -92,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.
+### Running the harness in a separate runtime (containers, remote backends)
 
-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)
-
-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
@@ -170,35 +197,53 @@ Because Venice bills at queue time, a killed render is **already paid for**. So:
 
 ### Registering the MCP server
 
+**Published package (recommended — no clone, no absolute paths).** The
+`venice-video-mcp` bin is on your `PATH` after a global install, and it finds the
+`venice-video` harness the same way:
+
 ```bash
+npm install -g venice-video-harness venice-video-mcp
+
 # Hermes Agent
-hermes mcp add venice-video --command node \
-  --args /ABS/PATH/venice-video-mcp/bin/venice-video-mcp.js
+hermes mcp add venice-video --command venice-video-mcp
 hermes mcp test venice-video     # confirm the handshake before relying on it
 
-# Cursor / Claude Desktop: see venice-video-mcp/examples/
+# Cursor / Claude Desktop / any runner that reads a JSON config:
+#   "venice-video": { "command": "venice-video-mcp", "env": { "VENICE_API_KEY": "vn_..." } }
+# or, with no global install at all, run it on demand:
+#   "venice-video": { "command": "npx", "args": ["-y", "venice-video-mcp"], "env": { … } }
 ```
 
-This path does not depend on a published release: pointed at a built clone, it
-runs whatever you have checked out, so it works ahead of npm.
+**Local build (development / running ahead of npm).** Point the server at a built
+clone instead. This runs whatever you have checked out:
+
+```bash
+hermes mcp add venice-video --command node \
+  --args /ABS/PATH/venice-video-mcp/bin/venice-video-mcp.js
+# plus HARNESS_BIN or HARNESS_PATH in the env, see below
+```
 
 Environment for the server process:
 
 | Variable | Purpose |
 |---|---|
-| `VENICE_API_KEY` | Required. Forwarded to the harness |
-| `HARNESS_BIN` | Absolute path to `dist/mini-drama/cli.js` in a built clone. **Set this** |
-| `HARNESS_PATH` | Absolute path to a built clone. Fallback only — see below |
-| `HARNESS_WORKSPACE` | Absolute path where projects are created. Must already exist |
-
-**Resolution order (fixed in `venice-video-mcp` 0.4.0).** The server now resolves
-the harness as `HARNESS_BIN`, then `HARNESS_PATH/dist/mini-drama/cli.js`, then a
-`venice-video` on `PATH`. An explicit `HARNESS_PATH` now outranks an ambient
-global install, because setting it is a statement of intent — the old order let a
-stale global (npm `latest` trails this repo) silently win over a clone you pointed
-at deliberately. The server also logs the resolved binary once to stderr
-(`[venice-video-mcp] harness: …`), so the choice is never silent. `HARNESS_BIN` is
-still the most explicit and is recommended when you have a specific build in mind.
+| `VENICE_API_KEY` | **Required.** Forwarded to the harness |
+| `HARNESS_WORKSPACE` | Where projects are created. Must already exist. Falls back to the cwd, which is rarely right for a GUI-launched runner — set it |
+| `HARNESS_BIN` | Optional. Absolute path to `dist/mini-drama/cli.js` in a built clone. Set only to pin a specific local build |
+| `HARNESS_PATH` | Optional. Absolute path to a built clone. Fallback for a local build — see below |
+
+With both packages installed globally you set **none** of the three harness paths:
+the server finds `venice-video` on `PATH`. You only reach for `HARNESS_BIN` /
+`HARNESS_PATH` when you deliberately want a local checkout instead of the published
+CLI.
+
+**Resolution order (fixed in `venice-video-mcp` 0.4.0).** The server resolves the
+harness as `HARNESS_BIN`, then `HARNESS_PATH/dist/mini-drama/cli.js`, then a
+`venice-video` on `PATH`. An explicit `HARNESS_PATH` outranks an ambient global
+install, because setting it is a statement of intent — the old order let a stale
+global silently win over a clone you pointed at deliberately. The server also logs
+the resolved binary once to stderr (`[venice-video-mcp] harness: …`) on the first
+tool call, so the choice is never silent.
 
 Every MCP response includes the exact command it ran, so you can confirm which
 binary answered:
@@ -211,12 +256,13 @@ If that shows a path under a global npm prefix when you meant to use a clone,
 `HARNESS_BIN` is missing.
 
 Then install its companion skills, which carry the pipeline order the tool
-descriptions deliberately leave out:
+descriptions deliberately leave out. From a global install the command is on
+`PATH` (use `node /ABS/PATH/venice-video-mcp/bin/install-skills.js …` for a clone):
 
 ```bash
-node /ABS/PATH/venice-video-mcp/bin/install-skills.js --global      # Claude/Cursor: ~/.claude/skills/
-node /ABS/PATH/venice-video-mcp/bin/install-skills.js --target hermes # Hermes: ~/.hermes/skills/venice/
-node /ABS/PATH/venice-video-mcp/bin/install-skills.js --dir <path>    # any other runner's skills dir
+venice-video-mcp-install-skills --global        # Claude/Cursor: ~/.claude/skills/
+venice-video-mcp-install-skills --target hermes  # Hermes: ~/.hermes/skills/venice/
+venice-video-mcp-install-skills --dir <path>     # any other runner's skills dir
 ```
 
 The four skills are `venice-mcp-pipeline` (request-to-tool-call mapping and the
@@ -236,9 +282,9 @@ venice-video doctor             # API key, ffmpeg, ffprobe
 venice-video status -p <dir>    # pipeline stage + the next command to run
 ```
 
-**Version-drift check is not optional.** The published npm `latest` trails this
-repo. Documentation for an unreleased version describes flags the installed
-binary rejects:
+**Version-drift check is not optional.** Releases can lag commits, so the
+published npm `latest` may trail this repo. Documentation for a version newer
+than your installed binary describes flags it rejects:
 
 ```bash
 $ venice-video new --intelligence kimi-k3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venice-video-harness",
-  "version": "2.11.0",
+  "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",