@vatio-ai/cli 0.53.0 → 0.54.0

package/lib/commands/knowledge.mjs

@@ -4,10 +4,13 @@
 // vatio.yml is a list of *names*, and a push neither fills nor empties one.
 // That is why this is a command and not part of the manifest.
 //
-// Every write goes to the base's draft, which preview answers from. Live
-// answers from the last published snapshot and changes only on `publish` --
-// or `rollback`, which points it at an earlier one. So: write, try it on
-// preview, publish.
+// The entries are live. Reads and writes here are as one environment sees
+// them: on a branch, the branch's own (see branch.mjs), which keeps the
+// entries it changed on top of live and answers from them in its preview;
+// otherwise `preview`; `--env live` writes live directly, the way a supervisor
+// in the inbox does. `vatio publish`, or merging the branch's pull request,
+// takes the changes live with the agent -- `vatio kb publish` takes them alone.
+// So: write, try it on the branch's preview, publish.
 //
 // A base holds entries, and an entry is markdown. Either you wrote it, or a
 // site wrote it from a page it read — and a site is one URL or one pattern,
@@ -16,32 +19,48 @@
 import { readFileSync, statSync } from "node:fs";
 
 import { deployClient } from "./deploy.mjs";
-import { fail } from "../support.mjs";
+import { fail, takeEnv, takeValue } from "../support.mjs";
+
+// Only what reads or writes entries takes an environment; bases and sites
+// belong to the workspace.
+const ENVIRONMENT_SCOPED = new Set(["list", "show", "write", "cat", "rm-entry", "status", "publish"]);
 
 export async function kb(config, args) {
   const workspace = config.resolveWorkspaceRequired();
   const client = deployClient(config, workspace);
   const sub = args.shift() ?? "list";
+  const env = ENVIRONMENT_SCOPED.has(sub) ? takeEnv(args, { fallback: null, cwd: config.workspaceRoot }) : null;
+  const ctx = { client, workspace, env };
 
   switch (sub) {
-    case "list": return await list(client, workspace);
-    case "show": return await show(client, workspace, args.shift());
+    case "list": return await list(ctx);
+    case "show": return await show(ctx, args.shift());
     case "create": return await create(client, workspace, args.splice(0));
     case "rm": return await remove(client, workspace, args.shift());
-    case "write": return await write(client, workspace, args);
-    case "cat": return await cat(client, args.shift(), args.shift());
-    case "rm-entry": return await removeEntry(client, workspace, args.shift(), args.shift());
+    case "write": return await write(ctx, args);
+    case "cat": return await cat(ctx, args);
+    case "rm-entry": return await removeEntry(ctx, args.shift(), args.shift());
     case "follow": return await follow(client, workspace, args.shift(), args.shift());
     case "unfollow": return await unfollow(client, workspace, args.shift(), args.shift());
     case "refresh": return await refresh(client, workspace, args.shift(), args.shift());
-    case "status": return await status(client, workspace, args.shift());
-    case "publish": return await publish(client, workspace, args);
+    case "status": return await status(ctx, args.shift());
+    case "publish": return await publish(ctx, args.shift());
     case "history": return await history(client, workspace, args.shift());
-    case "rollback": return await rollback(client, workspace, args.shift(), args.shift());
+    case "rollback":
+      return fail(
+        "`vatio kb rollback` was removed. Restore one entry instead: `vatio kb history BASE` lists what " +
+          "reached live, `vatio kb cat BASE ENTRY --version N > old.md` prints one, and " +
+          "`vatio kb write BASE ENTRY old.md --env live` brings it back."
+      );
     default: fail(`Unknown kb subcommand: ${sub}\n\n${usage()}`);
   }
 }
 
+// `preview` when the platform chose, for messages.
+function envName(env) {
+  return env ?? "preview";
+}
+
 function usage() {
   return `usage:
   vatio kb                                  List knowledge bases
@@ -49,19 +68,21 @@ function usage() {
   vatio kb create NAME [NAME...]            Create one base, or several
   vatio kb rm NAME                          Delete a base (must be unreferenced)
   vatio kb write BASE ENTRY [FILE]          Write an entry, from FILE or stdin
-  vatio kb cat BASE ENTRY                   Print an entry's markdown
+  vatio kb cat BASE ENTRY [--version N]     Print an entry's markdown, or one of its versions
   vatio kb rm-entry BASE ENTRY              Delete one entry
   vatio kb follow BASE URL                  Read a site into the base, nightly
   vatio kb unfollow BASE URL                Stop reading it, and drop its entries
   vatio kb refresh BASE [URL]               Read the sites again now
-  vatio kb status BASE                      What the draft has that live does not
-  vatio kb publish BASE [-m NOTE]           Take the draft live
-  vatio kb history BASE                     Every publication, newest first
-  vatio kb rollback BASE NUMBER             Point live back at publication NUMBER`;
+  vatio kb status BASE                      What this environment changed that live does not have
+  vatio kb publish BASE                     Take this environment's changes live, without the agent
+  vatio kb history BASE                     What reached live, newest first
+
+  Entry commands, status and publish take --env NAME; on a branch they default
+  to the branch's environment, otherwise to preview. --env live writes live.`;
 }
 
-async function list(client, workspace) {
-  const bases = asArray((await client.knowledgeBases()).data);
+async function list({ client, workspace, env }) {
+  const bases = asArray((await client.knowledgeBases({ environment: env })).data);
   if (bases.length === 0) {
     console.log(`No knowledge bases on workspace ${workspace}`);
     console.log("Create one with `vatio kb create docs`, then add `knowledge: [docs]` to vatio.yml");
@@ -70,9 +91,10 @@ async function list(client, workspace) {
 
   console.log(`Knowledge bases on workspace ${workspace} (${bases.length}):`);
   for (const row of bases) {
+    const pending = row.pending_changes ? `  ${row.pending_changes} unpublished in ${envName(env)}` : "";
     console.log(
       `  ${row.name}  entries=${row.entries_count}  ready=${row.answerable_count}  ` +
-        `sites=${row.sites_count}${referenceNote(row)}`
+        `sites=${row.sites_count}${pending}${referenceNote(row)}`
     );
   }
 }
@@ -84,15 +106,17 @@ function referenceNote(row) {
   return row.referenced ? "" : "  (not referenced by any deployed agent)";
 }
 
-async function show(client, workspace, name) {
+async function show({ client, workspace, env }, name) {
   if (!name) fail("usage: vatio kb show NAME");
 
-  const base = await client.knowledgeBase(name);
+  const base = await client.knowledgeBase(name, { environment: env });
   console.log(
     `${base.name} on workspace ${workspace}: entries=${base.entries_count} ` +
       `ready=${base.answerable_count}${referenceNote(base)}`
   );
-  console.log(`  ${liveNote(base)}`);
+  if (base.pending_changes) {
+    console.log(`  ${base.pending_changes} change(s) in ${envName(env)} that live does not have — \`vatio kb status ${base.name}\``);
+  }
 
   const sites = asArray(base.sites);
   if (sites.length > 0) {
@@ -116,23 +140,15 @@ async function show(client, workspace, name) {
     return;
   }
 
-  console.log("\n  entries:");
+  console.log(`\n  entries, as ${envName(env)} sees them:`);
   for (const entry of entries) {
     const origin = entry.written ? "written here" : entry.url;
     const version = entry.version ? `  v${entry.version}` : "";
-    console.log(`    ${entry.name}${version}  ${entry.state ?? "?"}  ${origin}`);
+    const unpublished = entry.published === false ? "  (not live yet)" : "";
+    console.log(`    ${entry.name}${version}  ${entry.state ?? "?"}  ${origin}${unpublished}`);
   }
 }
 
-// Where live stands, and whether the draft has moved past it.
-function liveNote(base) {
-  const live = base.live_snapshot ? `live=publication #${base.live_snapshot}` : "live=never published";
-  const pending = base.pending_changes
-    ? `  ${base.pending_changes} unpublished change${base.pending_changes === 1 ? "" : "s"} — \`vatio kb publish ${base.name}\``
-    : "";
-  return `${live}${pending}`;
-}
-
 // Several names, because the moment this command is most often run is a push
 // that just refused for naming bases that do not exist yet -- and that push
 // names all of them at once. One base per invocation turned a first deploy
@@ -177,7 +193,7 @@ async function remove(client, workspace, name) {
 //   vatio kb cat docs horarios > horarios.md
 //   $EDITOR horarios.md
 //   vatio kb write docs horarios horarios.md
-async function write(client, workspace, args) {
+async function write({ client, workspace, env }, args) {
   const [base, name, file] = args;
   if (!base || !name) fail("usage: vatio kb write BASE ENTRY [FILE]   (or pipe the markdown in)");
   if (file && !isFile(file)) fail(`No such file: ${file}`);
@@ -187,27 +203,33 @@ async function write(client, workspace, args) {
     fail("Nothing to write: pass a FILE, or pipe the markdown in on stdin.");
   }
 
-  const row = await client.writeKnowledgeEntry({ base, name, content });
+  const row = await client.writeKnowledgeEntry({ base, name, content, environment: env });
   const version = row.version ? ` (v${row.version})` : "";
-  console.log(`Wrote ${row.name}${version} to the draft of ${base} on workspace ${workspace}`);
-  console.log(`Preview answers with it now; \`vatio kb publish ${base}\` takes it live.`);
+  if (env === "live") {
+    console.log(`Wrote ${row.name}${version} to ${base} on workspace ${workspace}. Live answers with it now.`);
+    return;
+  }
+  console.log(`Wrote ${row.name}${version} to ${base} in ${envName(env)} on workspace ${workspace}`);
+  console.log(`${envName(env)} answers with it now; \`vatio publish\` takes it live with the agent.`);
 }
 
 // Prints exactly what the platform holds, so a diff against the file you
 // pushed is a real answer to "is what I sent what it has".
-async function cat(client, base, name) {
-  if (!base || !name) fail("usage: vatio kb cat BASE ENTRY");
+async function cat({ client, env }, args) {
+  const version = takeValue(args, "--version");
+  const [base, name] = args;
+  if (!base || !name) fail("usage: vatio kb cat BASE ENTRY [--version N]");
 
-  const row = await client.knowledgeEntry({ base, name });
+  const row = await client.knowledgeEntry({ base, name, environment: env, version });
   const content = row.content ?? "";
   process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
 }
 
-async function removeEntry(client, workspace, base, name) {
+async function removeEntry({ client, workspace, env }, base, name) {
   if (!base || !name) fail("usage: vatio kb rm-entry BASE ENTRY");
 
-  await client.deleteKnowledgeEntry({ base, name });
-  console.log(`Deleted entry ${name} from ${base} on workspace ${workspace}`);
+  await client.deleteKnowledgeEntry({ base, name, environment: env });
+  console.log(`Deleted entry ${name} from ${base} in ${envName(env)} on workspace ${workspace}`);
 }
 
 // One URL, and the shape of it is the whole configuration. A URL is that URL;
@@ -246,65 +268,61 @@ async function refresh(client, workspace, base, url) {
   console.log(`Runs in the background — check progress with \`vatio kb show ${base}\``);
 }
 
-// The draft against live, entry by entry -- what `publish` would do.
-async function status(client, workspace, base) {
+// What this environment changed against live, entry by entry -- what
+// publishing it would do, and which entries live changed underneath.
+async function status({ client, workspace, env }, base) {
   if (!base) fail("usage: vatio kb status BASE");
 
-  const changes = asArray((await client.knowledgeChanges(base)).data);
+  const payload = await client.knowledgeChanges(base, { environment: env });
+  const changes = asArray(payload.data);
   if (changes.length === 0) {
-    console.log(`${base} on workspace ${workspace}: everything is published`);
+    console.log(`${base} in ${envName(env)} on workspace ${workspace}: nothing that live does not have`);
     return;
   }
 
-  console.log(`${base} on workspace ${workspace}: ${changes.length} unpublished change${changes.length === 1 ? "" : "s"}`);
+  console.log(`${base} in ${envName(env)} on workspace ${workspace}: ${changes.length} change${changes.length === 1 ? "" : "s"} live does not have`);
   for (const change of changes) {
     const from = change.live_version ? `v${change.live_version}` : "—";
-    const to = change.draft_version ? `v${change.draft_version}` : "—";
-    console.log(`  ${change.change.padEnd(8)} ${change.name}  ${from} → ${to}`);
+    const to = change.version ?? change.draft_version;
+    const conflict = change.conflict ? "  CONFLICT: live changed it after you did" : "";
+    console.log(`  ${change.change.padEnd(8)} ${change.name}  ${from} → v${to}${conflict}`);
+  }
+  if (changes.some((change) => change.conflict)) {
+    console.log(`\nRead each conflicting entry from live (\`vatio kb cat ${base} ENTRY --env live\`), write your change on top, and it clears.`);
+    if (payload.review_url) console.log(`Or resolve them side by side: ${payload.review_url}`);
+  } else {
+    console.log("\n`vatio publish` takes them live with the agent; `vatio kb publish` takes them alone.");
   }
-  console.log(`\nPublish with \`vatio kb publish ${base} -m "what changed"\``);
 }
 
-async function publish(client, workspace, args) {
-  const base = args.shift();
-  if (!base) fail("usage: vatio kb publish BASE [-m NOTE]");
+async function publish({ client, workspace, env }, base) {
+  if (!base) fail("usage: vatio kb publish BASE [--env NAME]");
 
-  let note = "";
-  const flag = args.findIndex((arg) => arg === "-m" || arg === "--note");
-  if (flag !== -1) note = args[flag + 1] ?? "";
-
-  const snapshot = await client.publishKnowledgeBase({ base, note });
-  console.log(`Published ${base} on workspace ${workspace} as #${snapshot.number} (${snapshot.entries} entries)`);
-  console.log(`Live answers from it now. Undo with \`vatio kb rollback ${base} NUMBER\` — see \`vatio kb history ${base}\`.`);
+  const result = await client.publishKnowledgeBase({ base, environment: env });
+  const names = asArray(result.published);
+  console.log(`Published ${names.length} change${names.length === 1 ? "" : "s"} to ${base} from ${envName(env)} on workspace ${workspace}: ${names.join(", ")}`);
+  console.log("Live answers from them now.");
 }
 
+// Every version that reached live, newest first. Going back is writing one
+// of them again.
 async function history(client, workspace, base) {
   if (!base) fail("usage: vatio kb history BASE");
 
-  const snapshots = asArray((await client.knowledgeSnapshots(base)).data);
-  if (snapshots.length === 0) {
-    console.log(`${base} on workspace ${workspace} was never published — \`vatio kb publish ${base}\``);
+  const versions = asArray((await client.knowledgeHistory(base)).data);
+  if (versions.length === 0) {
+    console.log(`Nothing in ${base} on workspace ${workspace} has reached live yet`);
     return;
   }
 
-  console.log(`Publications of ${base} on workspace ${workspace}:`);
-  for (const snapshot of snapshots) {
-    const live = snapshot.live ? "  ← live" : "";
-    const who = snapshot.author ? `  ${snapshot.author}` : "";
-    const note = snapshot.note ? `  ${snapshot.note}` : "";
-    console.log(`  #${snapshot.number}  ${snapshot.created_at}${who}  entries=${snapshot.entries}${note}${live}`);
+  console.log(`What reached live in ${base} on workspace ${workspace}:`);
+  for (const row of versions) {
+    const who = row.author ? `  ${row.author}` : "";
+    const what = row.deleted ? "  deleted" : "";
+    console.log(`  ${row.published_at}  ${row.name}  v${row.version}  ${row.source}${who}${what}`);
   }
 }
 
-// Only the pointer moves: the draft, and every later publication, stay.
-async function rollback(client, workspace, base, number) {
-  if (!base || !number || !/^\d+$/.test(number)) fail("usage: vatio kb rollback BASE NUMBER");
-
-  await client.rollbackKnowledgeBase({ base, number });
-  console.log(`Live for ${base} on workspace ${workspace} is publication #${number} again`);
-  console.log("The draft is untouched; publish again whenever it is ready.");
-}
-
 // Blocking on purpose: `vatio kb write docs refunds < refunds.md` should behave
 // like every other filter, and a terminal with nobody piping into it returns ""
 // rather than hanging on a read that will never end.

package/lib/commands/mcp.mjs

@@ -60,22 +60,31 @@ const COMMANDS = {
   push: {
     usage: "[--env NAME]",
     summary:
-      "Validate the workspace and update a preview deployment. Never touches live. `--env NAME` " +
-      "lands it on its own named preview (one per pull request) instead of the default one.",
+      "Validate the workspace and update a preview deployment. Never touches live. On a git branch " +
+      "other than the default one it lands on that branch's own environment (fix/pagos -> fix-pagos), " +
+      "the same one the branch's pull request deploys to; elsewhere on `preview`.",
     annotations: { readOnlyHint: false }
   },
   publish: {
     usage: "[--env NAME]",
     summary:
-      "Promote the latest push to live (or the preview `--env` names), which is what customers " +
-      "see. Ask the developer first: this is " +
-      "the one step that changes what real visitors get. Refused when the workspace is connected " +
-      "to GitHub: there, live changes only by merging to the default branch.",
+      "Promote an environment to live, with the knowledge changes made in it — what customers see. " +
+      "Ask the developer first: this is the one step that changes what real visitors get. Refused " +
+      "when the workspace is connected to GitHub: there, live changes only by merging the branch's " +
+      "pull request. Refused too when live changed an entry this environment also changed.",
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
+  env: {
+    usage: "[NAME] | list | rm NAME",
+    summary:
+      "The environment this workspace is working in — the branch's own on a branch — with its " +
+      "publishable token, widget snippet, share link, the knowledge entries it changed and any that " +
+      "live changed underneath. Use its token to point an app being developed at this environment.",
+    annotations: { readOnlyHint: true }
+  },
   rollback: {
     usage: "",
-    summary: "Restore the previous live deployment. Same weight as publish — ask first.",
+    summary: "Put live back to the previous snapshot — its configuration and its knowledge together. Same weight as publish — ask first.",
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   chat: {
@@ -88,21 +97,24 @@ const COMMANDS = {
     annotations: { readOnlyHint: false }
   },
   secrets: {
-    usage: "list | set KEY VALUE | rm KEY",
+    usage: "list | set KEY VALUE | rm KEY [--env NAME]",
     summary:
-      "Credentials the workspace's JS tools read as ctx.env. Values are write-only — listing shows " +
-      "keys, never values.",
+      "Credentials the workspace's tools read as $env.KEY. Values are write-only — listing shows " +
+      "keys, never values. On a branch (or with --env) a value applies to that environment only, " +
+      "replacing the one everywhere else: point a branch's tools at staging without touching live.",
     annotations: { readOnlyHint: false }
   },
   kb: {
     usage:
-      "[list] | show NAME | create NAME | write BASE ENTRY [FILE] | cat BASE ENTRY | rm-entry BASE ENTRY | " +
-      "follow BASE URL | unfollow BASE URL | refresh BASE [URL] | status BASE | publish BASE [-m NOTE] | " +
-      "history BASE | rollback BASE NUMBER",
+      "[list] | show NAME | create NAME | write BASE ENTRY [FILE] | cat BASE ENTRY [--version N] | " +
+      "rm-entry BASE ENTRY | follow BASE URL | unfollow BASE URL | refresh BASE [URL] | status BASE | " +
+      "publish BASE | history BASE   (entry commands take --env NAME)",
     summary:
       "Knowledge bases, which belong to the workspace rather than to a deployment: `knowledge:` in " +
-      "vatio.yml is a list of names, and a push neither fills nor empties one. Writes go to a draft that " +
-      "preview answers from; live changes only on publish.",
+      "vatio.yml is a list of names, and a push neither fills nor empties one. The entries are live; " +
+      "writes on a branch are changes only that branch's preview answers from, and they go live with " +
+      "vatio_publish or the merge of its pull request. `status` names entries live changed underneath: " +
+      "read those from live (`cat --env live`), write your change on top, and the conflict clears.",
     annotations: { readOnlyHint: false, openWorldHint: true }
   },
   tokens: {
@@ -125,7 +137,7 @@ const COMMANDS = {
     summary:
       "The workspace's own WhatsApp number, which serves live: whether it is connected, whether Meta " +
       "delivers to it, and whether it is answering — three things that fail separately. `numbers` is " +
-      "the other thing: the shared WhatsApp preview, test phones that reach preview and need no Meta " +
+      "the other thing: the shared WhatsApp preview, test phones that reach the environment they point at (`point PHONE --env NAME`) and need no Meta " +
       "account. A code goes to the handset, so a human has to read it back to you.",
     annotations: { readOnlyHint: false, openWorldHint: true }
   },
@@ -155,6 +167,7 @@ const WITHHELD = {
 const BLOCKED_SUBCOMMANDS = {
   chat: { destroy: "destroys a conversation; ask the developer" },
   kb: { rm: "deletes an indexed base; ask the developer" },
+  env: { rm: "removes an environment with its unpublished knowledge changes; ask the developer" },
   whatsapp: { connect: "takes Meta credentials the developer holds", disconnect: "ask the developer" },
   instagram: { connect: "needs Meta's consent screen in a browser", disconnect: "ask the developer" }
 };
@@ -218,8 +231,13 @@ function initializeResult(params) {
       "Start with vatio_docs: it is the contract for vatio.yml, tools, auth, visitor identity and",
       "knowledge, fetched live from the platform, so it is what the platform actually accepts.",
       "",
-      "The loop is: edit files, vatio_push (preview only), vatio_chat to read the agent's answer,",
-      "vatio_publish when the developer says so. Nothing a customer sees changes until publish.",
+      "Work on a git branch (a worktree is ideal): every command then uses that branch's own",
+      "environment — its agent, its knowledge changes, its secret values — and nothing you do there",
+      "reaches live or another branch. vatio_env shows which one and the token to point an app at it.",
+      "",
+      "The loop is: edit files and knowledge (vatio_kb write), vatio_push, vatio_chat to read the",
+      "agent's answer, then publish when the developer says so — by merging the branch's pull request",
+      "when GitHub is connected, vatio_publish otherwise. The prompt and the knowledge go live together.",
       "",
       "Anything that needs a browser or a person — login, issue, instagram connect — is not here;",
       "ask the developer to run it in their terminal."

package/lib/commands/workspace-admin.mjs

@@ -6,63 +6,71 @@
 // will actually enforce, edited in the console. None of them are in vatio.yml.
 
 import { deployClient } from "./deploy.mjs";
-import { askSecret, fail, paint, takeValue } from "../support.mjs";
+import { askSecret, branchDefault, fail, paint, takeValue } from "../support.mjs";
 
-// live, preview, or a named preview like pr-42. This used to accept only the
-// first two, which meant a workspace could deploy to `pr-42` and then have no
-// way to mint the publishable token that makes it embeddable.
+// live, preview, or a branch's own like fix-pagos.
 const ENVIRONMENT_NAME = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
 const ENVIRONMENT_MAX = 40;
 
-function environmentOption(args, fallback) {
-  const value =
-    takeValue(args, "--env") ?? takeValue(args, "--environment") ?? takeValue(args, "-e") ?? fallback;
+// On a branch, its environment unless told otherwise (see branch.mjs).
+function environmentOption(args, fallback, cwd) {
+  const given = takeValue(args, "--env") ?? takeValue(args, "--environment") ?? takeValue(args, "-e");
+  const value = given ?? branchDefault(cwd, fallback);
+  if (value === null) return null;
   if (String(value).length > ENVIRONMENT_MAX || !ENVIRONMENT_NAME.test(String(value))) {
-    fail(`Unknown environment "${value}" (use live, preview, or a preview name like pr-42)`);
+    fail(`Unknown environment "${value}" (use live, preview, or a branch's environment like fix-pagos)`);
   }
   return String(value);
 }
 
+// Without an environment a secret is the value everywhere. On a branch, or
+// with --env, it is the value only that environment uses -- a preview pointing
+// its tools at staging while live keeps production.
 export async function secrets(config, args) {
   const workspace = config.resolveWorkspaceRequired();
   const client = deployClient(config, workspace);
+  const environment = environmentOption(args, null, config.workspaceRoot);
+  const where = environment ? `${environment} on workspace ${workspace}` : `workspace ${workspace}`;
   const sub = args.shift() ?? "list";
 
   if (sub === "list") {
-    const payload = await client.listSecrets();
+    const payload = await client.listSecrets({ environment });
     const keys = asArray(payload.secrets);
     if (keys.length === 0) {
-      console.log(`No secrets on workspace ${workspace}`);
+      console.log(`No secrets on ${where}`);
       console.log("  Set one: vatio secrets set STRIPE_KEY sk_live_…");
       return;
     }
     // Keys only, never values. The platform does not hand a value back once it
     // is stored, and a CLI that printed them would be a CLI that leaks them
     // into a terminal scrollback.
-    console.log(`Secrets on workspace ${workspace} (${keys.length}):`);
-    for (const secret of keys) console.log(`  ${secret.key ?? secret}`);
+    console.log(`Secrets on ${where} (${keys.length}):`);
+    for (const secret of keys) {
+      const scope = secret.environment ? `  (only ${secret.environment})` : "";
+      console.log(`  ${secret.key ?? secret}${scope}`);
+    }
     return;
   }
   if (sub === "set") {
     const key = args.shift();
-    if (!key) fail("Usage: vatio secrets set KEY [VALUE]");
+    if (!key) fail("Usage: vatio secrets set KEY [VALUE] [--env NAME]");
     // Asked for rather than typed on the command line, where it would stay in
     // shell history.
     const value = args.shift() ?? (await askSecret(`${paint("green", "?")} Paste your secret: `));
     if (value === "") fail(`No value given for ${key}`);
-    await client.upsertSecret({ key, value });
-    console.log(`${paint("green", "✓")} Set secret ${key} on workspace ${workspace}`);
+    await client.upsertSecret({ key, value, environment });
+    console.log(`${paint("green", "✓")} Set secret ${key} on ${where}`);
     return;
   }
   if (sub === "rm" || sub === "remove" || sub === "delete") {
     const key = args.shift();
-    if (!key) fail("Usage: vatio secrets rm KEY");
-    await client.deleteSecret({ key });
-    console.log(`Removed ${key} from workspace ${workspace}`);
+    if (!key) fail("Usage: vatio secrets rm KEY [--env NAME]");
+    await client.deleteSecret({ key, environment });
+    console.log(`Removed ${key} from ${where}`);
     return;
   }
 
-  fail("Usage: vatio secrets list|set KEY [VALUE]|rm KEY");
+  fail("Usage: vatio secrets list|set KEY [VALUE]|rm KEY [--env NAME]");
 }
 
 // Repeatable: `--origin https://a.com --origin https://b.com`.
@@ -75,7 +83,7 @@ function takeOrigins(args) {
 }
 
 export async function tokens(config, args) {
-  const environment = environmentOption(args, "live");
+  const environment = environmentOption(args, "live", config.workspaceRoot);
   const label = takeValue(args, "--label") ?? takeValue(args, "-l");
   const origins = takeOrigins(args);
   const workspace = config.resolveWorkspaceRequired();
@@ -139,7 +147,7 @@ function originsLine(origins) {
 }
 
 export async function widget(config, args) {
-  const environment = environmentOption(args, "live");
+  const environment = environmentOption(args, "live", config.workspaceRoot);
   const workspace = config.resolveWorkspaceRequired();
   const payload = await deployClient(config, workspace).widget();
 

package/lib/help.mjs

@@ -12,7 +12,10 @@ A workspace is any directory with a vatio.yml. Every command except init reads
 \`workspace:\` from the vatio.yml at or above the cwd — there is no --workspace
 flag, the directory decides.
 
---env NAME targets a deployment: live, preview, or a preview name like pr-42.
+--env NAME targets an environment: live, preview, or a branch's own. On a git
+branch other than the default one, the branch's environment is the default
+(fix/pagos -> fix-pagos): its own agent, knowledge changes and secret values,
+and the one its pull request deploys to. Elsewhere commands default as listed.
 
   Getting started:
     init [SLUG] [--name NAME]  Create vatio.yml here, and the remote to match
@@ -24,11 +27,15 @@ flag, the directory decides.
 
   Deploy:
     push [--env NAME]          Validate the workspace, then update a preview
-    publish [--env NAME]       Promote the latest push to live. --env promotes
-                               a specific preview instead. Refused when GitHub
-                               is connected: merge to the default branch
-    rollback                   Restore the previous live deployment
+    publish [--env NAME]       Promote an environment to live, with its knowledge
+                               changes. Without --env or a branch, the latest
+                               push. Refused when GitHub is connected: merge
+                               the branch's pull request instead
+    rollback                   Put live back to the previous snapshot: config and knowledge
     status                     Preview and live deployment state
+    env [NAME]                 This environment: token, widget snippet, link,
+                               knowledge changes and conflicts
+    env list | rm NAME         Every environment / remove one and what it holds
     diff [--env NAME]          What this directory would change (default: preview)
                                --env live answers "what would publishing change?"
     diff --stat|--name-only|--format json|--full
@@ -45,18 +52,23 @@ flag, the directory decides.
     kb [list]                  Bases, and whether a deployed agent reads each
     kb show NAME               One base: its sites and its entries
     kb create NAME | rm NAME
-    kb write BASE ENTRY [FILE] Write an entry, from FILE or stdin
-    kb cat BASE ENTRY          Print an entry's markdown
-    kb rm-entry BASE ENTRY     Delete one entry
+    kb write BASE ENTRY [FILE] Write an entry in this environment, from FILE or stdin
+    kb cat BASE ENTRY [--version N]
+                               Print an entry's markdown, or one old version
+    kb rm-entry BASE ENTRY     Delete one entry in this environment
     kb follow BASE URL         Read a site into the base, nightly
     kb unfollow BASE URL | refresh BASE [URL]
-    kb status BASE             What the draft has that live does not
-    kb publish BASE [-m NOTE]  Take the draft live (preview already has it)
-    kb history BASE | rollback BASE NUMBER
+    kb status BASE             What this environment changed that live does not
+                               have, and what live changed underneath
+    kb publish BASE            Take this environment's changes live, alone
+    kb history BASE            What reached live, newest first
+                               (entry commands take --env; --env live writes live)
 
   Credentials and the widget:
-    secrets list|set KEY [VALUE]|rm KEY
-                               Without VALUE, set asks for it with the input hidden
+    secrets list|set KEY [VALUE]|rm KEY [--env NAME]
+                               Without VALUE, set asks for it with the input hidden.
+                               On a branch or with --env, the value only that
+                               environment uses; otherwise the value everywhere
     tokens list|create [--env NAME] [--label NAME] [--origin URL]...|revoke PREFIX
     tokens origins PREFIX URL...
                                The origins a token is accepted from (replaces the list)
@@ -64,11 +76,13 @@ flag, the directory decides.
                                the look is edited in the console
     auth --new-key             Keypair that signs the JWT saying who a visitor is
 
-  Channels (your own account serves live; the shared preview always serves preview):
+  Channels (your own account serves live; each test phone or account on the shared
+  preview reaches the environment it points at -- add and point take --env, and
+  default to the branch you are on):
     whatsapp [status]|connect|check|activate|deactivate|disconnect
-    whatsapp numbers list|add PHONE|verify PHONE CODE|resend PHONE|remove PHONE
+    whatsapp numbers list|add PHONE|point PHONE|verify PHONE CODE|resend PHONE|remove PHONE
     instagram [status]|connect|check|disconnect
-    instagram accounts list|add @HANDLE|verify CODE|resend ID|remove ID
+    instagram accounts list|add @HANDLE|point ID|verify CODE|resend ID|remove ID
 
   Everything else:
     issue "what should change"|list|show ID|comment ID "reply"|--template

package/lib/http.mjs

@@ -37,7 +37,10 @@ function unprocessableMessage(body) {
     .map((entry) => (typeof entry === "object" ? String(entry.message ?? "") : String(entry)));
   if (errors.length > 0) return errors.join("; ");
 
-  const message = body.error_message ?? body.error;
+  // `{ error: { code, message } }` is how the knowledge and token endpoints
+  // say it.
+  const error = body.error && typeof body.error === "object" && !Array.isArray(body.error) ? body.error.message : body.error;
+  const message = body.error_message ?? error;
   if (message != null) return Array.isArray(message) ? message.join("; ") : String(message);
 
   return "Unprocessable";