rivet-design 0.13.3 → 0.13.5

package/dist/utils/skills/cli-guidance.js

@@ -8,7 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_GUIDANCE_DESCRIPTION = exports.CLI_GUIDANCE_BODY = exports.CLI_GUIDANCE_VERSION = void 0;
-exports.CLI_GUIDANCE_VERSION = 14;
+exports.CLI_GUIDANCE_VERSION = 20;
 exports.CLI_GUIDANCE_BODY = `Rivet helps you **explore multiple design directions** for a web app. You drive it by running \`rivet\` CLI commands. Every command prints exactly one JSON envelope on stdout (\`{ schemaVersion, ok, command, data | error }\`), routes progress to stderr, and never prompts for input.
 
 **Exit codes:** 0 ok · 1 operation failed (see \`error.code\`) · 2 usage error · 3 auth required · 4 no server for the project · 5 \`rivet wait\` timeout (work still pending or running — not a failure; the envelope's \`state\` says which).
@@ -24,11 +24,12 @@ exports.CLI_GUIDANCE_BODY = `Rivet helps you **explore multiple design direction
 ## Commands
 
 - \`rivet open [--project <path>] [--agent claude|codex|cursor] [--rivet-port N] [--user-port N] [--framework nextjs|vite|cra|remix|svelte|static] [--entry <path>] [--no-browser] [--no-git]\` — start or attach the project's editor server (idempotent; returns \`editorUrl\`). It detects the app, attaches to an already-running dev server, or starts one from the app's standard \`dev\`/\`start\`/\`serve\` script when possible. Omit \`--no-browser\` for interactive work so the UI opens for the user.
-- \`rivet variants start --project <path> --instruction <text> [--briefs <json>] [--count N] [--element <selector>] [--fresh] [--target <sessionId>:<variantId>]\` — explore design directions. Agent invocations MUST pass one AI-authored brief per direction; \`briefs.length\` sets the count. Use \`--fresh\` for prompt-only 0-to-1 generation in a blank/new workspace; use \`--target\` to Vary an existing direction. Returns a \`workId\` immediately, plus \`nextAction\` when the host agent should implement the variants.
-- \`rivet variants complete <workId> --project <path> [--session <sessionId>] [--status succeeded|failed|cancelled] [--output <json>] [--error <message>]\` — report one host-agent work item complete after you edit its worktree.
+- \`rivet variants start --project <path> --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--element <selector>] [--files <json>] [--fresh] [--target <sessionId>:<variantId>]\` — explore design directions. Agent invocations MUST pass an AI-authored 1–3 word batch label through \`rivet_variants\` \`runLabel\` or CLI \`--run-label\`, plus one AI-authored brief per direction; \`briefs.length\` sets the count. Use \`--files\` for already-known project paths, \`--fresh\` for prompt-only 0-to-1 generation in a blank/new workspace, and \`--target\` to Vary an existing direction. Returns a \`workId\` and \`nextAction\` after workspace provisioning.
+- \`rivet variants complete <workId> --project <path> [--session <sessionId>] [--status succeeded|failed|cancelled] [--output <json>] [--error <message>]\` — report one host-agent work item complete after you edit its assigned workspace. Static artifacts are read from disk; do not send them through \`--output\`.
 - \`rivet wait <workId> --project <path> [--timeout <seconds>]\` — bounded block until a work id settles (exit 5 on timeout; re-issue or check status).
 - \`rivet status --project <path> [--watch]\` — session, resolved runner, active run, and the variants snapshot. \`--watch\` streams NDJSON.
 - \`rivet variants status --project <path>\` / \`rivet variants list --project <path> [--history]\` — inspect live or past directions.
+- \`rivet variants get <sessionId>:<variantId> --project <path>\` — retrieve one exact variant, including its local artifact path or diff, from a reference copied by the editor.
 - \`rivet variants commit <variantId> --project <path> [--session <id>]\` — send the chosen direction to the project.
 - \`rivet variants cancel <sessionId> --project <path>\` — cancel a running variants session.
 - \`rivet evidence capture --url <url>\` — rendered design evidence (root variables, element styles, fonts) for a reference URL.
@@ -38,20 +39,20 @@ exports.CLI_GUIDANCE_BODY = `Rivet helps you **explore multiple design direction
 
 ## Typical flows
 
-Before every agent-initiated variants start, author one or more direction briefs as \`[{"label":"…","body":"…"}]\`. Each \`label\` is an AI-authored direction title: 1–5 plain-English words naming what that direction concretely changes, not a vibe or numbered placeholder. Each \`body\` is a concise plain-English subtitle of at most 10 words describing that direction. Use one brief for a single visualization when the user wants Rivet's visualization framework without divergent ideas. For multiple directions, make every brief meaningfully different. Pass the array through the \`rivet_variants\` \`briefs\` field or CLI \`--briefs <json>\`, and omit \`--count\` because the array length is authoritative. Human-direct CLI calls may omit briefs and use Rivet's deterministic fallback.
+Before every agent-initiated variants start, author a 1–3 word batch label plus one or more direction briefs as \`[{"label":"…","body":"…"}]\`. The batch label summarizes the shared request and is passed through \`runLabel\` (MCP) or \`--run-label\` (CLI). Each brief \`label\` is an AI-authored direction title: 1–5 plain-English words naming what that direction concretely changes, not a vibe or numbered placeholder. Each \`body\` is a concise plain-English subtitle of at most 10 words describing that direction. Add an optional \`notes\` string per brief for richer implementation intent (design tokens, motion specs, constraints) — it is delivered verbatim to that direction's worker and never shown in UI chips. Use one brief for a single visualization when the user wants Rivet's visualization framework without divergent ideas. For multiple directions, make every brief meaningfully different. Pass the array through the \`rivet_variants\` \`briefs\` field or CLI \`--briefs <json>\`, and omit \`--count\` because the array length is authoritative. Human-direct CLI calls may omit the batch label and briefs and use Rivet's deterministic fallback.
 
 Existing app:
 1. \`rivet open --project <path> --caller-agent cursor --caller-model <model> --caller-session <id>\` → note \`editorUrl\`, \`sessionId\`, and \`resolvedRunner\`.
-2. Author three distinct title/subtitle briefs, then call \`rivet variants start --project <path> --instruction "try three hero layouts" --briefs '[{"label":"Split hero","body":"Moves supporting proof beside the primary call to action."},{"label":"Layered hero","body":"Stacks product imagery behind a compact centered headline."},{"label":"Product-led hero","body":"Lets the product preview dominate the opening composition."}]' --caller-agent cursor --caller-model <model> --caller-session <id>\` → note \`workId\`.
-3. If the start response has \`nextAction.action="complete_host_variant_work"\`, execute it immediately. Otherwise poll \`rivet status --project <path>\` until that \`nextAction\` appears. The work items are independent: when your host supports subagents or parallel tasks, spawn one worker per item, each editing only its own \`worktreePath\` according to \`briefLabel\`, \`briefBody\`, target, and project context. Follow the item's \`outputSchema\`.
-4. As each worker finishes, run \`rivet variants complete <workId> --project <path> --session <sessionId> --output '{"worktreePath":"<worktreePath>","changedFiles":["relative/path"]}'\`. If a worker cannot complete it, use \`--status failed --error <message>\`.
+2. Author a batch label and three distinct title/subtitle briefs, then call \`rivet variants start --project <path> --instruction "try three hero layouts" --run-label "Hero layouts" --briefs '[{"label":"Split hero","body":"Moves supporting proof beside the primary call to action."},{"label":"Layered hero","body":"Stacks product imagery behind a compact centered headline."},{"label":"Product-led hero","body":"Lets the product preview dominate the opening composition."}]' --caller-agent cursor --caller-model <model> --caller-session <id>\` → note \`workId\`.
+3. If the start response has \`nextAction.action="complete_host_variant_work"\`, execute it immediately. Otherwise poll \`rivet status --project <path>\` until that \`nextAction\` appears. Each work item carries a server-authored \`workerPrompt\` pointing at its briefing file — the full packet (direction, mode contract, boundaries, completion command). Follow \`nextAction.parallelism\` exactly: one item → follow its \`workerPrompt\` yourself in the current host; multiple items → spawn every worker in that same turn as background subagents, passing each item's \`workerPrompt\` VERBATIM as the entire worker prompt — compose nothing, and never re-plan or elaborate briefs before spawning. When \`nextAction.worker.agentType\` is set (Claude Code: \`rivet-worker\`, installed by \`rivet install\` with tuned model/effort defaults), spawn each worker AS that subagent type; fall back to your default subagent type only if it is not registered. For \`mode="vary"\` the workspace entry already contains the source direction's finished code: read it first, apply the requested delta with targeted \`Edit\` operations in place, and never rewrite or re-emit the full file — unchanged sections must remain untouched. For \`workspace.kind="artifact_directory"\` the deliverable is \`workspace.rootPath/workspace.entryPath\` (write it in full only when it starts empty, i.e. \`mode="create"\`); for \`workspace.kind="git_worktree"\`, edit the app under \`workspace.projectPath\`.
+4. The briefing file ends with the item's exact \`completeCommand\`: the worker runs \`rivet variants complete <workId> --project <path> --session <sessionId>\` itself as its final step, the moment its workspace is done. Completions are never held back or batched by the coordinator — and because workers self-report, the coordinator does NOT poll status while workers run: check \`rivet status\` once after workers return (or on a single ≥60s wakeup), only to confirm terminal states and surface failures. Rivet reads static HTML from \`workspace.entryPath\` and captures git-worktree changes itself. Do not send inline HTML or repeat project context in the completion payload. If the result says \`requeuedForRegeneration\`, poll status for the renewed lease, address its QA summary, and complete that item once more. If a worker cannot complete it, use \`--status failed --error <message>\`.
 5. Show the user the \`editorUrl\` to compare directions; \`rivet variants commit <variantId> --project <path>\` when they pick one.
 
-Fresh 0-to-1: create or use an empty directory, run \`rivet open --project <path> ...\`, author distinct briefs, then run \`rivet variants start --project <path> --fresh --instruction "build a SaaS landing page" --briefs '<json>' ...\`.
+Fresh 0-to-1: create or use an empty directory, run \`rivet open --project <path> ...\`, author a batch label and distinct briefs, then run \`rivet variants start --project <path> --fresh --instruction "build a SaaS landing page" --run-label "SaaS landing" --briefs '<json>' ...\`.
 
-Vary an existing direction: after status/list gives you \`sessionId\` and \`variantId\`, author distinct briefs, then run \`rivet variants start --project <path> --target <sessionId>:<variantId> --instruction "make this calmer" --briefs '<json>' ...\`.
+Vary an existing direction: after status/list gives you \`sessionId\` and \`variantId\`, author a batch label and two distinct delta briefs by default, then run \`rivet variants start --project <path> --target <sessionId>:<variantId> --instruction "make this calmer" --run-label "Calmer direction" --briefs '<json>' ...\`. Include \`--files '["src/known-target.tsx"]'\` when the relevant files are already known. Explicit briefs/counts remain authoritative.
 
-Rivet owns orchestration; the host agent owns implementation. Do not wait for Rivet to spawn a separate agent. When \`rivet variants start\`, \`rivet status\`, \`rivet_variants\`, or \`rivet_status\` returns \`nextAction.action="complete_host_variant_work"\`, complete those work items from the current host session. Prefer parallelism: use one subagent or parallel task per work item when the host supports it, because each item has an isolated worktree. Report each item with \`rivet variants complete\` or \`rivet_variants\` action \`complete\`.
+Rivet owns orchestration; the host agent owns implementation. Do not wait for Rivet to spawn a separate agent. When \`rivet variants start\`, \`rivet status\`, \`rivet_variants\`, or \`rivet_status\` returns \`nextAction.action="complete_host_variant_work"\`, complete those work items from the current host session. Avoid subagent startup for one item. For multiple items, spawn one background worker per isolated workspace in the same turn, and have each worker report its own completion immediately via its \`completeCommand\` (or \`rivet_variants\` action \`complete\`) — a variant's completion must never wait for its siblings.
 
 **Never cancel to unblock.** If \`variants start\` is rejected with \`start_in_flight\`, a start is still provisioning (status reports \`variants.starting: true\` — can take minutes); poll status and retry once it clears. If rejected with \`active_session\`, the user has live work: report the conflict and let them decide, or refine the active session with \`--target\`. Cancelling a session destroys the user's in-progress exploration — only do it when the user explicitly asks.`;
 /** One-line description used in host frontmatter/description fields. */

package/dist/utils/skills/cli-guidance.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-guidance.js","sourceRoot":"","sources":["../../../src/utils/skills/cli-guidance.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEU,QAAA,oBAAoB,GAAG,EAAE,CAAC;AAE1B,QAAA,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ieA4Cgc,CAAC;AAEle,wEAAwE;AAC3D,QAAA,wBAAwB,GACnC,yOAAyO,CAAC"}
+{"version":3,"file":"cli-guidance.js","sourceRoot":"","sources":["../../../src/utils/skills/cli-guidance.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEU,QAAA,oBAAoB,GAAG,EAAE,CAAC;AAE1B,QAAA,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ieA6Cgc,CAAC;AAEle,wEAAwE;AAC3D,QAAA,wBAAwB,GACnC,yOAAyO,CAAC"}

package/dist/utils/skills/cursor-rules.d.ts

@@ -4,7 +4,7 @@
  * (project scope is where Cursor reads rules files from; the user-scope
  * install writes the command allowlist instead).
  */
-export declare const CURSOR_RULES_VERSION = 46;
+export declare const CURSOR_RULES_VERSION = 47;
 export declare const CURSOR_RULES_FILENAME = "rivet.mdc";
-export declare const CURSOR_RULES_CONTENT = "---\ndescription: Rivet \u2014 explore multiple design directions for your web app (\"/rivet\", \"use rivet\", \"explore with rivet\", \"create variants of X\", \"show me options for X\", \"open rivet\", \"open the visual editor\"). Drive it with `rivet` CLI commands.\nalwaysApply: false\n---\n<!-- rivet-rules-version: 46 -->\n<!-- rivet-cli-guidance-version: 14 -->\n# Rivet\n\nRivet helps you **explore multiple design directions** for a web app. You drive it by running `rivet` CLI commands. Every command prints exactly one JSON envelope on stdout (`{ schemaVersion, ok, command, data | error }`), routes progress to stderr, and never prompts for input.\n\n**Exit codes:** 0 ok \u00B7 1 operation failed (see `error.code`) \u00B7 2 usage error \u00B7 3 auth required \u00B7 4 no server for the project \u00B7 5 `rivet wait` timeout (work still pending or running \u2014 not a failure; the envelope's `state` says which).\n\n**Identify yourself (handoff).** Add these flags to every invocation so Rivet can attribute work: `--caller-agent claude|codex|cursor`, `--caller-model <your model>`, and `--caller-session <your chat session id>` when you have one. Human-direct invocations omit handoff flags. Never wrap or chain `rivet` with other commands (`&&`, pipes) \u2014 plain invocations are what the host allowlist covers.\n\n**Project path.** Prefer explicit `--project <absolute path>` on every command so follow-up chats attach to the same workspace. For an existing app, pass its repo/app root. For a fresh app, create or use an empty directory first, then open Rivet there and start variants with `--fresh`.\n\n**Browser behavior.** For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for headless/background automation, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`.\n\n**MCP tools (opt-in).** If this host has Rivet MCP tools registered (`rivet_status`, `rivet_variants`, `rivet_design_context` \u2014 the user opted in via `rivet install --mcp`), prefer them over shelling out for status, variants, and design-context work: they drive the same control plane and return the same JSON envelopes, without per-call process cost. Lifecycle and auth stay CLI-only on purpose \u2014 `rivet open`, `rivet stop`, `rivet wait`, and `rivet login` have no MCP tools. There is no blocking/watch tool either: start work with `rivet_variants`; if the result contains `nextAction.action=\"complete_host_variant_work\"`, execute it yourself with parallel subagents when available.\n\n## Commands\n\n- `rivet open [--project <path>] [--agent claude|codex|cursor] [--rivet-port N] [--user-port N] [--framework nextjs|vite|cra|remix|svelte|static] [--entry <path>] [--no-browser] [--no-git]` \u2014 start or attach the project's editor server (idempotent; returns `editorUrl`). It detects the app, attaches to an already-running dev server, or starts one from the app's standard `dev`/`start`/`serve` script when possible. Omit `--no-browser` for interactive work so the UI opens for the user.\n- `rivet variants start --project <path> --instruction <text> [--briefs <json>] [--count N] [--element <selector>] [--fresh] [--target <sessionId>:<variantId>]` \u2014 explore design directions. Agent invocations MUST pass one AI-authored brief per direction; `briefs.length` sets the count. Use `--fresh` for prompt-only 0-to-1 generation in a blank/new workspace; use `--target` to Vary an existing direction. Returns a `workId` immediately, plus `nextAction` when the host agent should implement the variants.\n- `rivet variants complete <workId> --project <path> [--session <sessionId>] [--status succeeded|failed|cancelled] [--output <json>] [--error <message>]` \u2014 report one host-agent work item complete after you edit its worktree.\n- `rivet wait <workId> --project <path> [--timeout <seconds>]` \u2014 bounded block until a work id settles (exit 5 on timeout; re-issue or check status).\n- `rivet status --project <path> [--watch]` \u2014 session, resolved runner, active run, and the variants snapshot. `--watch` streams NDJSON.\n- `rivet variants status --project <path>` / `rivet variants list --project <path> [--history]` \u2014 inspect live or past directions.\n- `rivet variants commit <variantId> --project <path> [--session <id>]` \u2014 send the chosen direction to the project.\n- `rivet variants cancel <sessionId> --project <path>` \u2014 cancel a running variants session.\n- `rivet evidence capture --url <url>` \u2014 rendered design evidence (root variables, element styles, fonts) for a reference URL.\n- `rivet reference fetch <url>` \u2014 Pinterest / Are.na reference data via the user's connected account.\n- `rivet auth status` \u2014 signed-in state. If `authenticated: false`, tell the user to run `rivet login` themselves \u2014 never run login for them.\n- `rivet stop [--project <path>]` \u2014 stop the CLI-owned server.\n\n## Typical flows\n\nBefore every agent-initiated variants start, author one or more direction briefs as `[{\"label\":\"\u2026\",\"body\":\"\u2026\"}]`. Each `label` is an AI-authored direction title: 1\u20135 plain-English words naming what that direction concretely changes, not a vibe or numbered placeholder. Each `body` is a concise plain-English subtitle of at most 10 words describing that direction. Use one brief for a single visualization when the user wants Rivet's visualization framework without divergent ideas. For multiple directions, make every brief meaningfully different. Pass the array through the `rivet_variants` `briefs` field or CLI `--briefs <json>`, and omit `--count` because the array length is authoritative. Human-direct CLI calls may omit briefs and use Rivet's deterministic fallback.\n\nExisting app:\n1. `rivet open --project <path> --caller-agent cursor --caller-model <model> --caller-session <id>` \u2192 note `editorUrl`, `sessionId`, and `resolvedRunner`.\n2. Author three distinct title/subtitle briefs, then call `rivet variants start --project <path> --instruction \"try three hero layouts\" --briefs '[{\"label\":\"Split hero\",\"body\":\"Moves supporting proof beside the primary call to action.\"},{\"label\":\"Layered hero\",\"body\":\"Stacks product imagery behind a compact centered headline.\"},{\"label\":\"Product-led hero\",\"body\":\"Lets the product preview dominate the opening composition.\"}]' --caller-agent cursor --caller-model <model> --caller-session <id>` \u2192 note `workId`.\n3. If the start response has `nextAction.action=\"complete_host_variant_work\"`, execute it immediately. Otherwise poll `rivet status --project <path>` until that `nextAction` appears. The work items are independent: when your host supports subagents or parallel tasks, spawn one worker per item, each editing only its own `worktreePath` according to `briefLabel`, `briefBody`, target, and project context. Follow the item's `outputSchema`.\n4. As each worker finishes, run `rivet variants complete <workId> --project <path> --session <sessionId> --output '{\"worktreePath\":\"<worktreePath>\",\"changedFiles\":[\"relative/path\"]}'`. If a worker cannot complete it, use `--status failed --error <message>`.\n5. Show the user the `editorUrl` to compare directions; `rivet variants commit <variantId> --project <path>` when they pick one.\n\nFresh 0-to-1: create or use an empty directory, run `rivet open --project <path> ...`, author distinct briefs, then run `rivet variants start --project <path> --fresh --instruction \"build a SaaS landing page\" --briefs '<json>' ...`.\n\nVary an existing direction: after status/list gives you `sessionId` and `variantId`, author distinct briefs, then run `rivet variants start --project <path> --target <sessionId>:<variantId> --instruction \"make this calmer\" --briefs '<json>' ...`.\n\nRivet owns orchestration; the host agent owns implementation. Do not wait for Rivet to spawn a separate agent. When `rivet variants start`, `rivet status`, `rivet_variants`, or `rivet_status` returns `nextAction.action=\"complete_host_variant_work\"`, complete those work items from the current host session. Prefer parallelism: use one subagent or parallel task per work item when the host supports it, because each item has an isolated worktree. Report each item with `rivet variants complete` or `rivet_variants` action `complete`.\n\n**Never cancel to unblock.** If `variants start` is rejected with `start_in_flight`, a start is still provisioning (status reports `variants.starting: true` \u2014 can take minutes); poll status and retry once it clears. If rejected with `active_session`, the user has live work: report the conflict and let them decide, or refine the active session with `--target`. Cancelling a session destroys the user's in-progress exploration \u2014 only do it when the user explicitly asks.\n";
+export declare const CURSOR_RULES_CONTENT = "---\ndescription: Rivet \u2014 explore multiple design directions for your web app (\"/rivet\", \"use rivet\", \"explore with rivet\", \"create variants of X\", \"show me options for X\", \"open rivet\", \"open the visual editor\"). Drive it with `rivet` CLI commands.\nalwaysApply: false\n---\n<!-- rivet-rules-version: 47 -->\n<!-- rivet-cli-guidance-version: 20 -->\n# Rivet\n\nRivet helps you **explore multiple design directions** for a web app. You drive it by running `rivet` CLI commands. Every command prints exactly one JSON envelope on stdout (`{ schemaVersion, ok, command, data | error }`), routes progress to stderr, and never prompts for input.\n\n**Exit codes:** 0 ok \u00B7 1 operation failed (see `error.code`) \u00B7 2 usage error \u00B7 3 auth required \u00B7 4 no server for the project \u00B7 5 `rivet wait` timeout (work still pending or running \u2014 not a failure; the envelope's `state` says which).\n\n**Identify yourself (handoff).** Add these flags to every invocation so Rivet can attribute work: `--caller-agent claude|codex|cursor`, `--caller-model <your model>`, and `--caller-session <your chat session id>` when you have one. Human-direct invocations omit handoff flags. Never wrap or chain `rivet` with other commands (`&&`, pipes) \u2014 plain invocations are what the host allowlist covers.\n\n**Project path.** Prefer explicit `--project <absolute path>` on every command so follow-up chats attach to the same workspace. For an existing app, pass its repo/app root. For a fresh app, create or use an empty directory first, then open Rivet there and start variants with `--fresh`.\n\n**Browser behavior.** For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for headless/background automation, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`.\n\n**MCP tools (opt-in).** If this host has Rivet MCP tools registered (`rivet_status`, `rivet_variants`, `rivet_design_context` \u2014 the user opted in via `rivet install --mcp`), prefer them over shelling out for status, variants, and design-context work: they drive the same control plane and return the same JSON envelopes, without per-call process cost. Lifecycle and auth stay CLI-only on purpose \u2014 `rivet open`, `rivet stop`, `rivet wait`, and `rivet login` have no MCP tools. There is no blocking/watch tool either: start work with `rivet_variants`; if the result contains `nextAction.action=\"complete_host_variant_work\"`, execute it yourself with parallel subagents when available.\n\n## Commands\n\n- `rivet open [--project <path>] [--agent claude|codex|cursor] [--rivet-port N] [--user-port N] [--framework nextjs|vite|cra|remix|svelte|static] [--entry <path>] [--no-browser] [--no-git]` \u2014 start or attach the project's editor server (idempotent; returns `editorUrl`). It detects the app, attaches to an already-running dev server, or starts one from the app's standard `dev`/`start`/`serve` script when possible. Omit `--no-browser` for interactive work so the UI opens for the user.\n- `rivet variants start --project <path> --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--element <selector>] [--files <json>] [--fresh] [--target <sessionId>:<variantId>]` \u2014 explore design directions. Agent invocations MUST pass an AI-authored 1\u20133 word batch label through `rivet_variants` `runLabel` or CLI `--run-label`, plus one AI-authored brief per direction; `briefs.length` sets the count. Use `--files` for already-known project paths, `--fresh` for prompt-only 0-to-1 generation in a blank/new workspace, and `--target` to Vary an existing direction. Returns a `workId` and `nextAction` after workspace provisioning.\n- `rivet variants complete <workId> --project <path> [--session <sessionId>] [--status succeeded|failed|cancelled] [--output <json>] [--error <message>]` \u2014 report one host-agent work item complete after you edit its assigned workspace. Static artifacts are read from disk; do not send them through `--output`.\n- `rivet wait <workId> --project <path> [--timeout <seconds>]` \u2014 bounded block until a work id settles (exit 5 on timeout; re-issue or check status).\n- `rivet status --project <path> [--watch]` \u2014 session, resolved runner, active run, and the variants snapshot. `--watch` streams NDJSON.\n- `rivet variants status --project <path>` / `rivet variants list --project <path> [--history]` \u2014 inspect live or past directions.\n- `rivet variants get <sessionId>:<variantId> --project <path>` \u2014 retrieve one exact variant, including its local artifact path or diff, from a reference copied by the editor.\n- `rivet variants commit <variantId> --project <path> [--session <id>]` \u2014 send the chosen direction to the project.\n- `rivet variants cancel <sessionId> --project <path>` \u2014 cancel a running variants session.\n- `rivet evidence capture --url <url>` \u2014 rendered design evidence (root variables, element styles, fonts) for a reference URL.\n- `rivet reference fetch <url>` \u2014 Pinterest / Are.na reference data via the user's connected account.\n- `rivet auth status` \u2014 signed-in state. If `authenticated: false`, tell the user to run `rivet login` themselves \u2014 never run login for them.\n- `rivet stop [--project <path>]` \u2014 stop the CLI-owned server.\n\n## Typical flows\n\nBefore every agent-initiated variants start, author a 1\u20133 word batch label plus one or more direction briefs as `[{\"label\":\"\u2026\",\"body\":\"\u2026\"}]`. The batch label summarizes the shared request and is passed through `runLabel` (MCP) or `--run-label` (CLI). Each brief `label` is an AI-authored direction title: 1\u20135 plain-English words naming what that direction concretely changes, not a vibe or numbered placeholder. Each `body` is a concise plain-English subtitle of at most 10 words describing that direction. Add an optional `notes` string per brief for richer implementation intent (design tokens, motion specs, constraints) \u2014 it is delivered verbatim to that direction's worker and never shown in UI chips. Use one brief for a single visualization when the user wants Rivet's visualization framework without divergent ideas. For multiple directions, make every brief meaningfully different. Pass the array through the `rivet_variants` `briefs` field or CLI `--briefs <json>`, and omit `--count` because the array length is authoritative. Human-direct CLI calls may omit the batch label and briefs and use Rivet's deterministic fallback.\n\nExisting app:\n1. `rivet open --project <path> --caller-agent cursor --caller-model <model> --caller-session <id>` \u2192 note `editorUrl`, `sessionId`, and `resolvedRunner`.\n2. Author a batch label and three distinct title/subtitle briefs, then call `rivet variants start --project <path> --instruction \"try three hero layouts\" --run-label \"Hero layouts\" --briefs '[{\"label\":\"Split hero\",\"body\":\"Moves supporting proof beside the primary call to action.\"},{\"label\":\"Layered hero\",\"body\":\"Stacks product imagery behind a compact centered headline.\"},{\"label\":\"Product-led hero\",\"body\":\"Lets the product preview dominate the opening composition.\"}]' --caller-agent cursor --caller-model <model> --caller-session <id>` \u2192 note `workId`.\n3. If the start response has `nextAction.action=\"complete_host_variant_work\"`, execute it immediately. Otherwise poll `rivet status --project <path>` until that `nextAction` appears. Each work item carries a server-authored `workerPrompt` pointing at its briefing file \u2014 the full packet (direction, mode contract, boundaries, completion command). Follow `nextAction.parallelism` exactly: one item \u2192 follow its `workerPrompt` yourself in the current host; multiple items \u2192 spawn every worker in that same turn as background subagents, passing each item's `workerPrompt` VERBATIM as the entire worker prompt \u2014 compose nothing, and never re-plan or elaborate briefs before spawning. When `nextAction.worker.agentType` is set (Claude Code: `rivet-worker`, installed by `rivet install` with tuned model/effort defaults), spawn each worker AS that subagent type; fall back to your default subagent type only if it is not registered. For `mode=\"vary\"` the workspace entry already contains the source direction's finished code: read it first, apply the requested delta with targeted `Edit` operations in place, and never rewrite or re-emit the full file \u2014 unchanged sections must remain untouched. For `workspace.kind=\"artifact_directory\"` the deliverable is `workspace.rootPath/workspace.entryPath` (write it in full only when it starts empty, i.e. `mode=\"create\"`); for `workspace.kind=\"git_worktree\"`, edit the app under `workspace.projectPath`.\n4. The briefing file ends with the item's exact `completeCommand`: the worker runs `rivet variants complete <workId> --project <path> --session <sessionId>` itself as its final step, the moment its workspace is done. Completions are never held back or batched by the coordinator \u2014 and because workers self-report, the coordinator does NOT poll status while workers run: check `rivet status` once after workers return (or on a single \u226560s wakeup), only to confirm terminal states and surface failures. Rivet reads static HTML from `workspace.entryPath` and captures git-worktree changes itself. Do not send inline HTML or repeat project context in the completion payload. If the result says `requeuedForRegeneration`, poll status for the renewed lease, address its QA summary, and complete that item once more. If a worker cannot complete it, use `--status failed --error <message>`.\n5. Show the user the `editorUrl` to compare directions; `rivet variants commit <variantId> --project <path>` when they pick one.\n\nFresh 0-to-1: create or use an empty directory, run `rivet open --project <path> ...`, author a batch label and distinct briefs, then run `rivet variants start --project <path> --fresh --instruction \"build a SaaS landing page\" --run-label \"SaaS landing\" --briefs '<json>' ...`.\n\nVary an existing direction: after status/list gives you `sessionId` and `variantId`, author a batch label and two distinct delta briefs by default, then run `rivet variants start --project <path> --target <sessionId>:<variantId> --instruction \"make this calmer\" --run-label \"Calmer direction\" --briefs '<json>' ...`. Include `--files '[\"src/known-target.tsx\"]'` when the relevant files are already known. Explicit briefs/counts remain authoritative.\n\nRivet owns orchestration; the host agent owns implementation. Do not wait for Rivet to spawn a separate agent. When `rivet variants start`, `rivet status`, `rivet_variants`, or `rivet_status` returns `nextAction.action=\"complete_host_variant_work\"`, complete those work items from the current host session. Avoid subagent startup for one item. For multiple items, spawn one background worker per isolated workspace in the same turn, and have each worker report its own completion immediately via its `completeCommand` (or `rivet_variants` action `complete`) \u2014 a variant's completion must never wait for its siblings.\n\n**Never cancel to unblock.** If `variants start` is rejected with `start_in_flight`, a start is still provisioning (status reports `variants.starting: true` \u2014 can take minutes); poll status and retry once it clears. If rejected with `active_session`, the user has live work: report the conflict and let them decide, or refine the active session with `--target`. Cancelling a session destroys the user's in-progress exploration \u2014 only do it when the user explicitly asks.\n";
 //# sourceMappingURL=cursor-rules.d.ts.map

package/dist/utils/skills/cursor-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-rules.d.ts","sourceRoot":"","sources":["../../../src/utils/skills/cursor-rules.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAGjD,eAAO,MAAM,oBAAoB,8sRAShC,CAAC"}
+{"version":3,"file":"cursor-rules.d.ts","sourceRoot":"","sources":["../../../src/utils/skills/cursor-rules.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAGjD,eAAO,MAAM,oBAAoB,u+WAShC,CAAC"}

package/dist/utils/skills/cursor-rules.js

@@ -8,7 +8,7 @@ const cli_guidance_1 = require("./cli-guidance");
  * (project scope is where Cursor reads rules files from; the user-scope
  * install writes the command allowlist instead).
  */
-exports.CURSOR_RULES_VERSION = 46;
+exports.CURSOR_RULES_VERSION = 47;
 exports.CURSOR_RULES_FILENAME = 'rivet.mdc';
 const CURSOR_RULES_VERSION_MARKER = `rivet-rules-version: ${exports.CURSOR_RULES_VERSION}`;
 exports.CURSOR_RULES_CONTENT = `---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rivet-design",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "Local visual web development tool with AI-powered code modification",
   "main": "dist/index.js",
   "workspaces": [
@@ -46,6 +46,8 @@
     "bench:review": "node --import tsx benchmarks/review/server.ts",
     "bench:review:hosted": "BENCH_REVIEW_HOSTED=true BENCH_REVIEW_OPEN=false node --import tsx benchmarks/review/server.ts --hosted",
     "bench:list": "node --import tsx benchmarks/list.ts",
+    "bench:test": "node --import tsx --test benchmarks/*.test.ts benchmarks/agents/*.test.ts benchmarks/agents/prompts/*.test.ts benchmarks/review/*.test.ts",
+    "bench:typecheck": "tsc -p benchmarks/tsconfig.json",
     "smoke:cli": "node scripts/smoke-cli.mjs",
     "perf:cli": "node scripts/bench-cli.mjs",
     "check:pre-commit": "npx lint-staged && yarn build && cd src/ui && yarn typecheck && cd ../.. && cd src/proxy && yarn build && cd ../.. && cd desktop/renderer && yarn build && cd ../..",