@voltade/volty 0.1.17 → 0.1.19

package/dist/volty.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // bin/volty.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { join as join4 } from "node:path";
 
@@ -268,7 +268,7 @@ async function logout(config, env) {
 }
 
 // src/dispatch.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 
 // ../shared/ops/flag-parse.ts
 function acceptsNull(prop) {
@@ -354,9 +354,9 @@ function parseFlagTokens(props, rest, UsageError) {
       throw new UsageError(`unknown flag --${raw0}`);
     let raw = match[2];
     const next = rest[i + 1];
-    if (raw === undefined && valueBranch(prop).type !== "boolean" && next !== undefined && !next.startsWith("--")) {
+    const takes = valueBranch(prop).type === "boolean" ? next === "true" || next === "false" : !next?.startsWith("--");
+    if (raw === undefined && next !== undefined && takes)
       raw = rest[++i];
-    }
     if (prop.type === "array") {
       const list = input[flag] ?? [];
       list.push(...arrayItems(flag, raw, prop, UsageError));
@@ -406,12 +406,29 @@ function parseFlags(op, rest) {
   const parsed = parseFlagTokens(props, rest, CliUsageError);
   for (const [key, value] of Object.entries(parsed.input)) {
     const prop = props[key];
-    if (typeof value === "string" && value.startsWith("@") && prop && isBase64(prop)) {
+    if (typeof value !== "string" || !value.startsWith("@") || !prop)
+      continue;
+    if (isBase64(prop))
       parsed.input[key] = readBase64File(key, value.slice(1));
-    }
+    else if (isText(prop))
+      parsed.input[key] = readTextFlag(key, value.slice(1)) ?? value;
   }
   return parsed;
 }
+function isText(prop) {
+  return [prop, ...prop.anyOf ?? []].some((branch) => branch.type === "string" && !branch.enum);
+}
+function readTextFlag(flag, path) {
+  if (path === "-")
+    return readFileSync3(0, "utf8");
+  if (!existsSync3(path))
+    return null;
+  try {
+    return readFileSync3(path, "utf8");
+  } catch (err) {
+    throw new CliUsageError(`--${flag}: cannot read ${path} (${err.code ?? "error"})`);
+  }
+}
 function isBase64(prop) {
   return [prop, ...prop.anyOf ?? []].some((branch) => branch.contentEncoding === "base64");
 }
@@ -478,14 +495,19 @@ function opUsage(op) {
   }
   return parts.join(" ");
 }
-function renderCatalog(catalog) {
-  const lines = catalog.toSorted((a, b) => a.name.localeCompare(b.name)).map((op) => `  ${op.name}  —  ${op.description}`);
+function renderCatalog(catalog, group) {
+  const shown = group ? catalog.filter((op) => op.name === group || op.name.startsWith(`${group} `)) : catalog;
+  if (group && shown.length === 0) {
+    const groups = [...new Set(catalog.map((op) => op.name.split(" ")[0]))].toSorted();
+    return `No operations in '${group}'. Groups: ${groups.join(", ")}`;
+  }
+  const lines = shown.toSorted((a, b) => a.name.localeCompare(b.name)).map((op) => `  ${op.name}  —  ${op.description}`);
   return [
     "Run a Volty platform operation:  volty <operation> [--flags] [--json]",
     "",
     ...lines,
     "",
-    "`volty <operation> --help` shows usage; `--json` returns the machine-readable result."
+    "`volty help <group>` lists one group (`volty help chat-flow`); `volty <operation> --help` shows usage; `--json` returns the machine-readable result. A text flag takes a file as `--source=@flow.ts`, or stdin as `--source=@-`."
   ].join(`
 `);
 }
@@ -837,7 +859,7 @@ function handleSkill(rest) {
     join4(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
     join4(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
   ];
-  const source = candidates.find((p) => existsSync3(p));
+  const source = candidates.find((p) => existsSync4(p));
   if (!source)
     fail("bundled SKILL.md not found — reinstall the @voltade/volty package");
   const destDir = join4(homedir3(), ".claude", "skills", "volty-cli-ops");
@@ -893,7 +915,7 @@ async function main() {
     return handleChanges(rest, ctx);
   const catalog = await fetchCatalog(ctx, env, !cacheFlag.present);
   if (!cmd || cmd === "help" || cmd === "--help") {
-    process.stdout.write(`${renderCatalog(catalog.ops)}
+    process.stdout.write(`${renderCatalog(catalog.ops, rest.length ? rest.join(" ") : undefined)}
 `);
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltade/volty",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Remote CLI for the Volty platform — run operations, trigger real agent wakes, and inspect LLM I/O over an API key.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/volty-cli-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: volty-cli-ops
-description: "Drive Volty's agent with the `volty` CLI: run a real agent turn in one command on either lane (a contact message or a staff session) and read what the model saw and did. Use whenever you need to exercise the live agent end to end: does an inbound trigger the right reply, learning or proposal, can Volty read or operate a connected system (CRM, MCP server, drive, channel), why did a tool call come back wrong. Reproducing a reported behaviour costs one command, so reach for it before theorising. Triggers: 'test the agent', 'trigger a wake', 'wake-sync', 'session-sync', 'ask Volty on prod', 'what did the agent do with X', 'run a real LLM turn', 'reproduce this inbound', 'can Volty see X?'."
+description: "Drive Volty's agent with the `volty` CLI: run a real agent turn in one command on either lane (a contact message or a staff session) and read what the model saw and did. Use whenever you need to exercise the live agent end to end: does an inbound trigger the right reply, learning or proposal, can Volty read or operate a connected system (CRM, MCP server, drive, channel), why did a tool call come back wrong. Reproducing a reported behaviour costs one command, so reach for it before theorising. Also use it to create or configure a web chat channel from Claude Code. Triggers: 'set up a web chat', 'change the web chat settings', 'test the agent', 'trigger a wake', 'wake-sync', 'session-sync', 'ask Volty on prod', 'what did the agent do with X', 'run a real LLM turn', 'reproduce this inbound', 'can Volty see X?'."
 ---
 
 # volty CLI
@@ -19,6 +19,8 @@ This skill says which lane to use and what to keep to on prod. The commands and
 - `debug wake-sync --web-chat <channel id>` writes as a website visitor on a web chat channel, without the form's captcha: the contact lane on web chat. The chat is filed in the Sandbox inbox, where only testers see it, and Volty follows the web chat inbox's instructions, so you test that channel's setup without its staff seeing the test. You must be in the web chat channel's inbox.
 - `debug session-sync` runs a turn on the internal Volty chat as you: the staff lane.
 
+To create or change a web chat (its look, websites, the visitor's phone and email settings, the logo), use the `widgets` ops: `volty docs` has a "Setting up a web chat" section with the order to run them in. Read the settings back with `widgets get` after a change, and test the chat with `debug wake-sync --web-chat` before saying it works.
+
 Use the lane the behaviour was reported on. On the contact lane Volty declines to list internal records to a contact, as it should, so "can Volty read our CRM or MCP server" belongs on the staff lane; asked on the contact lane, that refusal looks like a broken feature.
 
 ## On prod