@vatio-ai/cli 0.37.2 → 0.44.0

package/bin/vatio.mjs

@@ -18,6 +18,7 @@ import { login, logout } from "../lib/commands/auth.mjs";
 import { configCommand, doctor, init, version } from "../lib/commands/misc.mjs";
 import { diff, publish, push, rollback, status, toolsCheck } from "../lib/commands/deploy.mjs";
 import { secrets, tokens, widget } from "../lib/commands/workspace-admin.mjs";
+import { auth } from "../lib/commands/identity-key.mjs";
 import { chat } from "../lib/commands/chat.mjs";
 import { kb } from "../lib/commands/knowledge.mjs";
 import { instagram, whatsapp } from "../lib/commands/channels.mjs";
@@ -70,6 +71,8 @@ async function main(argv) {
       return await tokens(config, args);
     case "widget":
       return await widget(config, args);
+    case "auth":
+      return await auth(config, args);
     case "chat":
       return await chat(config, args);
     case "kb":

package/lib/api-client.mjs

@@ -73,6 +73,9 @@ export class ApiClient extends HttpClient {
   }
 
   // --- knowledge bases ------------------------------------------------
+  //
+  // A base holds entries (markdown) and reads sites (a URL or a pattern). Two
+  // nouns, and every call below is one of them.
 
   knowledgeBases() {
     return this.get("/knowledge_bases");
@@ -90,27 +93,38 @@ export class ApiClient extends HttpClient {
     return this.delete(`/knowledge_bases/${encode(name)}`);
   }
 
-  addKnowledgeCrawl({ base, name, siteUrl, includes = [], excludes = [] }) {
-    return this.post(`/knowledge_bases/${encode(base)}/sources`, {
-      name,
-      site_url: siteUrl,
-      include: includes,
-      exclude: excludes
-    });
+  refreshKnowledgeBase(name) {
+    return this.post(`/knowledge_bases/${encode(name)}/refresh`, {});
   }
 
-  // The file's bytes travel in the body: the platform chunks and embeds, and
-  // it is the only copy there will be.
-  uploadKnowledgeDocument({ base, filename, content }) {
-    return this.post(`/knowledge_bases/${encode(base)}/sources`, { filename, content });
+  knowledgeEntry({ base, name }) {
+    return this.get(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`);
   }
 
-  deleteKnowledgeSource({ base, name }) {
-    return this.delete(`/knowledge_bases/${encode(base)}/sources/${encode(name)}`);
+  // Put this markdown under this name, whether or not the entry exists yet --
+  // one call for "write" and "rewrite", because from the terminal they are the
+  // same sentence.
+  writeKnowledgeEntry({ base, name, content }) {
+    return this.patch(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`, { content });
   }
 
-  reindexKnowledgeSource({ base, name }) {
-    return this.post(`/knowledge_bases/${encode(base)}/sources/${encode(name)}/reindex`, {});
+  deleteKnowledgeEntry({ base, name }) {
+    return this.delete(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`);
+  }
+
+  followKnowledgeSite({ base, url }) {
+    return this.post(`/knowledge_bases/${encode(base)}/sites`, { url });
+  }
+
+  // Addressed by the URL you typed rather than by an id you would have to look
+  // up first. It travels as a query parameter because a URL does not survive
+  // being a path segment.
+  unfollowKnowledgeSite({ base, url }) {
+    return this.delete(`/knowledge_bases/${encode(base)}/sites?url=${encode(url)}`);
+  }
+
+  refreshKnowledgeSite({ base, url }) {
+    return this.post(`/knowledge_bases/${encode(base)}/sites/refresh`, { url });
   }
 
   // --- publishable tokens and the widget ------------------------------
@@ -240,12 +254,15 @@ export class ApiClient extends HttpClient {
     return this.post(`/chats/${encode(chatId)}/reset`, { environment });
   }
 
-  showChat({ chatId, view = "visitor" }) {
-    return this.get(`/chats/${encode(chatId)}`, { view });
+  // No `view` parameter: the developer token is the developer view, so the
+  // API returns one shape and the caller decides how much of it to print.
+  // `transcript` prints the visitor's half of it; `debug` prints all of it.
+  showChat({ chatId }) {
+    return this.get(`/chats/${encode(chatId)}`);
   }
 
-  chatMessages({ chatId, view = "visitor", after = null, limit = null }) {
-    const params = { view };
+  chatMessages({ chatId, after = null, limit = null }) {
+    const params = {};
     if (after) params.after = after;
     if (limit) params.limit = limit;
     return this.get(`/chats/${encode(chatId)}/messages`, params);

package/lib/commands/chat.mjs

@@ -148,15 +148,25 @@ async function converse(config, options, message) {
   console.log(formatVisitor(assistant));
 }
 
+// What a visitor would have seen in a row the developer API always sends in
+// full -- the same three questions the server used to answer behind
+// `view=visitor`: not deleted, said by a person or the agent, and actually
+// carrying words. A tool call with no text answers the last one and is skipped,
+// which is what makes this safe to run over the developer payload.
+const visitorVisible = (entry) =>
+  !entry.discarded &&
+  ["user", "assistant"].includes(entry.role) &&
+  String(entry.content ?? "").trim() !== "";
+
 // Conversations are asynchronous: post a message, then poll for the reply.
 async function waitForAssistant(api, { chatId, after, timeout, interval = 2 }) {
   const deadline = Date.now() + timeout * 1000;
   for (;;) {
-    const payload = await api.chatMessages({ chatId, view: "visitor", after });
+    const payload = await api.chatMessages({ chatId, after });
     const messages = Array.isArray(payload.data) ? payload.data : [];
-    const assistant = [...messages].reverse().find(
-      (entry) => entry.role === "assistant" && String(entry.content ?? "").trim() !== ""
-    );
+    const assistant = [...messages]
+      .reverse()
+      .find((entry) => entry.role === "assistant" && visitorVisible(entry));
     if (assistant) return assistant;
     if (Date.now() >= deadline) fail(`Timed out waiting for assistant reply after ${timeout}s`);
     await sleep(interval * 1000);
@@ -168,11 +178,10 @@ async function transcript(config, options) {
   const chatId = await ensureChat(config, options);
   const payload = await api.chatMessages({
     chatId,
-    view: "visitor",
     limit: Math.min(options.last * 6, 200)
   });
   const messages = (Array.isArray(payload.data) ? payload.data : [])
-    .filter((entry) => ["user", "assistant"].includes(entry.role) && !entry.discarded)
+    .filter(visitorVisible)
     .slice(-options.last);
   for (const message of messages) console.log(formatVisitor(message));
 }
@@ -182,10 +191,10 @@ async function debugChat(config, options) {
   const chatId = await ensureChat(config, options);
 
   console.log("## Chat status (developer)");
-  console.log(JSON.stringify(await api.showChat({ chatId, view: "developer" }), null, 2));
+  console.log(JSON.stringify(await api.showChat({ chatId }), null, 2));
   console.log("");
   console.log(`## Transcript (developer/debug, last ${options.last})`);
-  const payload = await api.chatMessages({ chatId, view: "developer", limit: options.last });
+  const payload = await api.chatMessages({ chatId, limit: options.last });
   for (const message of Array.isArray(payload.data) ? payload.data : []) {
     console.log(`[${message.role}] ${String(message.content ?? "").trim()}`);
   }

package/lib/commands/identity-key.mjs

@@ -0,0 +1,95 @@
+// `vatio auth --new-key` — the keypair that signs the JWT saying who a visitor is.
+//
+// This exists because asking a developer to authenticate users and then leaving
+// them to work out `openssl genpkey` flags, which half of the pair goes in the
+// workspace, and what the token has to contain is most of the reason the old
+// design grew a JavaScript escape hatch. Everything the platform can settle for
+// them is settled here: the algorithm, the file names, the audience, and the
+// exact claims, printed as code they can paste.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "../support.mjs";
+
+const PUBLIC_FILE = "identity.pub";
+const PRIVATE_FILE = "identity.pem";
+
+export async function auth(config, args) {
+  if (!args.includes("--new-key")) {
+    fail("Usage: vatio auth --new-key   (generates the keypair that signs your JWT)");
+  }
+
+  const root = config.workspaceRootRequired();
+  const publicPath = join(root, PUBLIC_FILE);
+  const privatePath = join(root, PRIVATE_FILE);
+  const slug = config.resolveWorkspaceRequired();
+
+  if (existsSync(publicPath) && !args.includes("--force")) {
+    fail(
+      `${PUBLIC_FILE} already exists. Rotating a key signs out every visitor holding a token ` +
+        `from the old one — re-run with --force if that is what you want.`
+    );
+  }
+
+  try {
+    execFileSync("openssl", ["genpkey", "-algorithm", "RSA", "-pkeyopt", "rsa_keygen_bits:2048", "-out", privatePath], {
+      stdio: "ignore"
+    });
+    execFileSync("openssl", ["rsa", "-in", privatePath, "-pubout", "-out", publicPath], { stdio: "ignore" });
+  } catch (error) {
+    if (existsSync(privatePath)) unlinkSync(privatePath);
+    fail(`Could not run openssl: ${error.message}`);
+  }
+
+  // The private half must never be pushed, and the surest way to keep it out is
+  // to keep it out of git — the deploy refuses it too, but by then it has
+  // already been read off disk.
+  ignorePrivateKey(root);
+
+  console.log(`Wrote ${PUBLIC_FILE} and ${PRIVATE_FILE}. They go to different places.`);
+  console.log("");
+  console.log(`1. ${PUBLIC_FILE} stays here. Commit it, and name it in vatio.yml:`);
+  console.log("");
+  console.log("     auth:");
+  console.log(`       public_key: ${PUBLIC_FILE}`);
+  console.log("");
+  console.log(`2. ${PRIVATE_FILE} goes into your backend as a secret — an env var, or`);
+  console.log("   whatever credential store you use. Your backend is what signs, so it");
+  console.log("   is the only thing that needs it. Then delete it from this directory:");
+  console.log("");
+  console.log(`     VATIO_IDENTITY_PRIVATE_KEY="$(cat ${PRIVATE_FILE})"`);
+  console.log("");
+  console.log("   Not `vatio secrets set` — that store is read by Vatio, and the whole");
+  console.log("   point is that Vatio can check your tokens but never mint one.");
+  console.log(`   (${PRIVATE_FILE} was added to .gitignore in the meantime.)`);
+  console.log("");
+  console.log("Sign a JWT with it for the person who is signed in:");
+  console.log("");
+  const claims = [
+    [ '"sub": "<your user id>",', "who this is" ],
+    [ `"aud": ${JSON.stringify(slug)},`, "this workspace, always" ],
+    [ '"exp": <unix seconds>,', "required; keep it short" ],
+    [ '"name": "Ada Lovelace",', "optional, fills the CRM" ],
+    [ '"email": "ada@example.com"', "optional, fills the CRM" ]
+  ];
+  const width = Math.max(...claims.map(([ claim ]) => claim.length));
+  console.log("  {");
+  for (const [ claim, note ] of claims) {
+    console.log(`    ${claim.padEnd(width)}  // ${note}`);
+  }
+  console.log("  }");
+  console.log("");
+  console.log("Put it on the widget as data-visitor-token, and push.");
+  console.log("Full examples: https://vatio.ai/docs#auth");
+}
+
+function ignorePrivateKey(root) {
+  const path = join(root, ".gitignore");
+  const line = PRIVATE_FILE;
+  let body = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (body.split(/\r?\n/).some((entry) => entry.trim() === line)) return;
+
+  if (body.length > 0 && !body.endsWith("\n")) body += "\n";
+  writeFileSync(path, `${body}${line}\n`);
+}

package/lib/commands/knowledge.mjs

@@ -4,12 +4,15 @@
 // 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, and why live and
 // preview read the same base.
+//
+// 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,
+// re-read every night. Everything below is one of those two nouns.
 
-import { basename } from "node:path";
 import { readFileSync, statSync } from "node:fs";
 
 import { deployClient } from "./deploy.mjs";
-import { fail, takeValue } from "../support.mjs";
+import { fail } from "../support.mjs";
 
 export async function kb(config, args) {
   const workspace = config.resolveWorkspaceRequired();
@@ -19,12 +22,14 @@ export async function kb(config, args) {
   switch (sub) {
     case "list": return await list(client, workspace);
     case "show": return await show(client, workspace, args.shift());
-    case "create": return await create(client, workspace, args.shift());
+    case "create": return await create(client, workspace, args.splice(0));
     case "rm": return await remove(client, workspace, args.shift());
-    case "add-source": return await addSource(client, workspace, args);
-    case "upload": return await upload(client, workspace, args.shift(), args);
-    case "rm-source": return await removeSource(client, workspace, args.shift(), args.shift());
-    case "reindex": return await reindex(client, workspace, args.shift(), 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 "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());
     default: fail(`Unknown kb subcommand: ${sub}\n\n${usage()}`);
   }
 }
@@ -32,13 +37,15 @@ export async function kb(config, args) {
 function usage() {
   return `usage:
   vatio kb                                  List knowledge bases
-  vatio kb show NAME                        One base and its sources
-  vatio kb create NAME                      Create a base
+  vatio kb show NAME                        One base: its sites and its entries
+  vatio kb create NAME [NAME...]            Create one base, or several
   vatio kb rm NAME                          Delete a base (must be unreferenced)
-  vatio kb add-source BASE NAME URL         Add a crawl
-  vatio kb upload BASE FILE...              Upload files into a base
-  vatio kb rm-source BASE NAME              Delete one source
-  vatio kb reindex BASE [NAME]              Re-crawl one source, or every crawl`;
+  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 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`;
 }
 
 async function list(client, workspace) {
@@ -51,7 +58,10 @@ async function list(client, workspace) {
 
   console.log(`Knowledge bases on workspace ${workspace} (${bases.length}):`);
   for (const row of bases) {
-    console.log(`  ${row.name}  sources=${row.sources_count}  entries=${row.entries_count}${referenceNote(row)}`);
+    console.log(
+      `  ${row.name}  entries=${row.entries_count}  ready=${row.answerable_count}  ` +
+        `sites=${row.sites_count}${referenceNote(row)}`
+    );
   }
 }
 
@@ -66,34 +76,64 @@ async function show(client, workspace, name) {
   if (!name) fail("usage: vatio kb show NAME");
 
   const base = await client.knowledgeBase(name);
-  console.log(`${base.name} on workspace ${workspace}: entries=${base.entries_count}${referenceNote(base)}`);
+  console.log(
+    `${base.name} on workspace ${workspace}: entries=${base.entries_count} ` +
+      `ready=${base.answerable_count}${referenceNote(base)}`
+  );
+
+  const sites = asArray(base.sites);
+  if (sites.length > 0) {
+    console.log("\n  sites:");
+    for (const site of sites) {
+      const when = site.last_run_at ?? "never";
+      console.log(
+        `    ${site.url}  ${site.status}  pages=${site.pages_found_count}  ` +
+          `entries=${site.entries_written_count}  last_read=${when}`
+      );
+      if (site.last_error) console.log(`      error: ${site.last_error}`);
+    }
+  }
 
-  const sources = asArray(base.sources);
-  if (sources.length === 0) {
+  const entries = asArray(base.entries);
+  if (entries.length === 0) {
     console.log(
-      `  no sources yet — add one with \`vatio kb add-source ${name} NAME URL\` or \`vatio kb upload ${name} FILE\``
+      `\n  no entries yet — write one with \`vatio kb write ${name} ENTRY FILE\`, ` +
+        `or read a site with \`vatio kb follow ${name} acme.com/help/**\``
     );
     return;
   }
 
-  for (const row of sources) {
-    const lastCrawled = row.last_crawled_at ?? "never";
-    console.log(
-      `  ${row.name} [${row.kind}]  ${row.status}  pages=${pagesDisplay(row)}  ` +
-        `entries=${row.entries_count}  last_indexed_at=${lastCrawled}`
-    );
-    console.log(row.kind === "upload" ? `    ${row.filename}` : `    ${row.site_url}  ${patternsDisplay(row)}`);
-    if (row.last_error) console.log(`    error: ${row.last_error}`);
+  console.log("\n  entries:");
+  for (const entry of entries) {
+    const origin = entry.written ? "written here" : entry.url;
+    console.log(`    ${entry.name}  ${entry.state ?? "?"}  ${origin}`);
   }
 }
 
-async function create(client, workspace, name) {
-  if (!name) fail("usage: vatio kb create NAME");
+// 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
+// into one round trip per name.
+//
+// Still never implicit: a base is created because someone typed its name here,
+// which is what keeps `knowledge: [defualt]` a failed push instead of an empty
+// base the agent searches forever.
+async function create(client, workspace, names) {
+  const wanted = names.filter((name) => name.trim() !== "");
+  if (wanted.length === 0) fail("usage: vatio kb create NAME [NAME...]");
+
+  const created = [];
+  for (const name of wanted) {
+    const base = await client.createKnowledgeBase(name);
+    created.push(base.name);
+    console.log(`Created knowledge base ${base.name} on workspace ${workspace}`);
+  }
 
-  const base = await client.createKnowledgeBase(name);
-  console.log(`Created knowledge base ${base.name} on workspace ${workspace}`);
-  console.log("It is empty and nothing reads it yet. Fill it with `vatio kb add-source` or `vatio kb upload`,");
-  console.log(`then add \`knowledge: [${base.name}]\` to vatio.yml and push.`);
+  console.log(created.length === 1
+    ? "It is empty and nothing reads it yet."
+    : "They are empty and nothing reads them yet.");
+  console.log("Fill with `vatio kb write` or `vatio kb follow`, then add");
+  console.log(`\`knowledge: [${created.join(", ")}]\` to the agent in vatio.yml and push.`);
 }
 
 async function remove(client, workspace, name) {
@@ -103,143 +143,94 @@ async function remove(client, workspace, name) {
   console.log(`Deleted knowledge base ${name} on workspace ${workspace}`);
 }
 
-async function addSource(client, workspace, args) {
-  const includes = takeAll(args, "--include");
-  const excludes = takeAll(args, "--exclude");
-  const [base, name, siteUrl] = args;
-
-  if (!base || !name || !siteUrl) {
-    fail("usage: vatio kb add-source BASE NAME URL [--include PATH] [--exclude PATH]");
+// Put this markdown under this name. One shape, positional, no flags: the
+// entry's name is the only thing the command cannot work out for itself — the
+// title comes from the document's own `# heading`, and the body comes from the
+// file or from stdin.
+//
+// Creates the entry if the name is free and replaces it if it is taken, so the
+// round trip is the obvious one:
+//
+//   vatio kb cat docs horarios > horarios.md
+//   $EDITOR horarios.md
+//   vatio kb write docs horarios horarios.md
+async function write(client, workspace, 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}`);
+
+  const content = file ? readFileSync(file, "utf8") : readStdin();
+  if (!content.trim()) {
+    fail("Nothing to write: pass a FILE, or pipe the markdown in on stdin.");
   }
 
-  const row = await client.addKnowledgeCrawl({ base, name, siteUrl, includes, excludes });
-  console.log(`Added crawl ${row.name} to ${base} on workspace ${workspace} (status=${row.status})`);
-  console.log(`Crawling runs in the background — check progress with \`vatio kb show ${base}\``);
+  const row = await client.writeKnowledgeEntry({ base, name, content });
+  console.log(`Wrote ${row.name} in ${base} on workspace ${workspace}`);
 }
 
-// Every file in one command, because `knowledge/*.md` is how a repo that
-// predates knowledge bases holds its content, and moving it should be one line
-// rather than one line per file.
-async function upload(client, workspace, base, paths) {
-  if (!base || paths.length === 0) fail("usage: vatio kb upload BASE FILE...");
+// 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");
 
-  const missing = paths.filter((path) => !isFile(path));
-  if (missing.length > 0) fail(`No such file: ${missing.join(", ")}`);
+  const row = await client.knowledgeEntry({ base, name });
+  const content = row.content ?? "";
+  process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+}
 
-  await abortOnCrawlCollisions(client, base, paths);
+async function removeEntry(client, workspace, base, name) {
+  if (!base || !name) fail("usage: vatio kb rm-entry BASE ENTRY");
 
-  for (const path of paths) {
-    const row = await client.uploadKnowledgeDocument({
-      base,
-      filename: basename(path),
-      content: readFileSync(path, "utf8")
-    });
-    console.log(`Uploaded ${basename(path)} to ${base} as ${row.name} (entries=${row.entries_count})`);
-  }
-  console.log(`Indexing runs in the background — check progress with \`vatio kb show ${base}\``);
+  await client.deleteKnowledgeEntry({ base, name });
+  console.log(`Deleted entry ${name} from ${base} on workspace ${workspace}`);
 }
 
-// Checked for the whole batch before a single file goes up, so an upload of
-// forty files either happens or does not. The platform refuses each collision
-// on its own, but one file at a time means a collision on file twenty lands
-// after nineteen are already in -- half an upload nobody asked for.
+// One URL, and the shape of it is the whole configuration. A URL is that URL;
+// a pattern is every page that matches it:
 //
-// Advisory, not the guarantee: the platform is what actually refuses. If this
-// check and its naming rule ever drift, the worst case is that this misses a
-// collision and the upload stops there instead, which is where it stopped
-// before.
-async function abortOnCrawlCollisions(client, base, paths) {
-  const sources = asArray((await client.knowledgeBase(base)).sources);
-  const crawls = new Map(sources.filter((row) => row.kind === "crawl").map((row) => [row.name, row]));
-  if (crawls.size === 0) return;
-
-  const collisions = paths
-    .map((path) => [path, crawls.get(sourceNameFor(path))])
-    .filter(([, crawl]) => crawl);
-  if (collisions.length === 0) return;
-
-  const lines = collisions.map(([path, crawl]) => {
-    const declaration = [crawl.site_url, ...asArray(crawl.include).map((p) => `include=${p}`)]
-      .filter(Boolean)
-      .join(" ");
-    return `  ${basename(path)} would land on "${crawl.name}", a crawl of ${declaration}`;
-  });
-
-  fail(
-    `Refusing to upload: ${collisions.length} of ${paths.length} file(s) collide with a crawl in ${base}.\n\n` +
-      `${lines.join("\n")}\n\n` +
-      "An upload cannot take over a crawl — its pages would keep answering lookups\n" +
-      "under a source that no longer says where they came from. Rename the file(s),\n" +
-      `or drop the crawl first with \`vatio kb rm-source ${base} NAME\`.\n\n` +
-      "Nothing was uploaded."
-  );
-}
+//   acme.com              the home page, and only it
+//   acme.com/help         that page
+//   acme.com/**           every page of the site
+//   acme.com/help/**      that section, however deep
+async function follow(client, workspace, base, url) {
+  if (!base || !url) fail("usage: vatio kb follow BASE URL");
 
-// Mirrors the platform's own source naming. Kept in step by the platform
-// refusing anyway, not by this being right.
-function sourceNameFor(path) {
-  const stem = basename(String(path)).replace(/\.[^.]*$/, "").toLowerCase();
-  const slug = stem.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug.slice(0, 60).replace(/-+$/, "");
+  const site = await client.followKnowledgeSite({ base, url });
+  console.log(`Reading ${site.url} into ${base} on workspace ${workspace}`);
+  console.log(`It runs in the background, and again every night — check it with \`vatio kb show ${base}\``);
 }
 
-async function removeSource(client, workspace, base, name) {
-  if (!base || !name) fail("usage: vatio kb rm-source BASE NAME");
+async function unfollow(client, workspace, base, url) {
+  if (!base || !url) fail("usage: vatio kb unfollow BASE URL");
 
-  await client.deleteKnowledgeSource({ base, name });
-  console.log(`Deleted source ${name} from ${base} on workspace ${workspace}`);
+  await client.unfollowKnowledgeSite({ base, url });
+  console.log(`Stopped reading ${url} into ${base} on workspace ${workspace}`);
+  console.log("Its entries went with it: nothing was left that nothing would refresh.");
 }
 
-// A bare `vatio kb reindex BASE` re-runs every crawl in the base. Uploads are
-// skipped rather than failing the whole command: there is no upstream to
-// re-read, so "reindex everything" cannot mean them.
-async function reindex(client, workspace, base, name) {
-  if (!base) fail("usage: vatio kb reindex BASE [NAME]");
+async function refresh(client, workspace, base, url) {
+  if (!base) fail("usage: vatio kb refresh BASE [URL]");
 
-  let targets;
-  if (name) {
-    targets = [name];
+  if (url) {
+    const site = await client.refreshKnowledgeSite({ base, url });
+    console.log(`Reading ${site.url} again in ${base} on workspace ${workspace}`);
   } else {
-    const crawls = asArray((await client.knowledgeBase(base)).sources).filter((row) => row.kind === "crawl");
-    if (crawls.length === 0) fail(`No crawls to reindex in ${base} on workspace ${workspace}`);
-    targets = crawls.map((row) => row.name);
-  }
-
-  for (const target of targets) {
-    const row = await client.reindexKnowledgeSource({ base, name: target });
-    console.log(`Reindexing ${row.name} in ${base} on workspace ${workspace} (status=${row.status})`);
+    const row = await client.refreshKnowledgeBase(base);
+    console.log(`Reading every site in ${base} again on workspace ${workspace} (${asArray(row.sites).length} of them)`);
   }
-  console.log(`Crawling runs in the background — check progress with \`vatio kb show ${base}\``);
-}
-
-// pages_discovered_count is newer than pages_indexed_count -- a platform
-// predating it omits the key entirely, so this falls back to the old
-// single-number display rather than printing "pages=3/".
-function pagesDisplay(row) {
-  const discovered = row.pages_discovered_count;
-  const indexed = row.pages_indexed_count;
-  return discovered ? `${indexed}/${discovered}` : String(indexed ?? "");
+  console.log(`Runs in the background — check progress with \`vatio kb show ${base}\``);
 }
 
-// No patterns at all means the source covers the whole site, which is the
-// default and needs saying rather than printing blank.
-function patternsDisplay(row) {
-  const includes = asArray(row.include);
-  const excludes = asArray(row.exclude);
-  if (includes.length === 0 && excludes.length === 0) return "whole site";
-
-  const parts = [];
-  if (includes.length > 0) parts.push(`include=${includes.join(",")}`);
-  if (excludes.length > 0) parts.push(`exclude=${excludes.join(",")}`);
-  return parts.join("  ");
-}
+// 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.
+function readStdin() {
+  if (process.stdin.isTTY) return "";
 
-function takeAll(args, name) {
-  const values = [];
-  for (;;) {
-    const value = takeValue(args, name);
-    if (value === null) return values;
-    values.push(value);
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
   }
 }
 

package/lib/commands/support-commands.mjs

@@ -96,18 +96,42 @@ async function issueTemplate(config) {
   process.stdout.write(await response.text());
 }
 
+// Where a report stands, in the words the developer is actually asking in:
+// has anyone looked at it, and is the ball with them or with us. There is no
+// `status` field to print -- an issue has no states -- so this reads the few
+// facts the platform does publish about the thread.
+function issueStatus(row) {
+  if (row.resolved) return "closed";
+  // The developer wrote last and nothing has gone back yet.
+  if (row.awaiting_us) return "with us";
+  if (row.answered) return "answered";
+  if (row.answers > 0) return "in progress";
+  return "sent";
+}
+
 async function issueList(config) {
+  // `data`, the same envelope every other read in this CLI unwraps. Reading
+  // `issues` here is how `list` spent its whole life reporting that a
+  // developer had sent nothing while `show` returned those same issues by id.
   const payload = await issuesClient(config).get("/cli/issues");
-  const issues = Array.isArray(payload.issues) ? payload.issues : [];
+  const issues = Array.isArray(payload.data) ? payload.data : [];
   if (issues.length === 0) {
     console.log("You have not sent any issues yet.");
     console.log('  Send one: vatio issue "what should change"');
     return;
   }
   console.log(`Your issues (${issues.length}):`);
+  const idWidth = Math.max(...issues.map((row) => String(row.id).length));
+  const statusWidth = Math.max(...issues.map((row) => issueStatus(row).length));
+  // The pull request goes under the title it belongs to, so the id and status
+  // columns stay readable as columns.
+  const indent = " ".repeat(2 + idWidth + 3 + statusWidth + 2);
   for (const row of issues) {
-    console.log(`  [${row.id}] ${row.status ?? ""}  ${row.title ?? row.summary ?? ""}`.trimEnd());
+    const id = `[${String(row.id).padStart(idWidth)}]`;
+    console.log(`  ${id} ${issueStatus(row).padEnd(statusWidth)}  ${row.title ?? ""}`.trimEnd());
+    if (row.pull_request_url) console.log(`${indent}${row.pull_request_url}`);
   }
+  console.log("Read one, conversation included: vatio issue show ID");
 }
 
 // The markdown view, which is the same document Vatio's own triage agent

package/lib/commands/workspace-admin.mjs

@@ -108,10 +108,6 @@ export async function tokens(config, args) {
   fail("Usage: vatio tokens list|create [--env live|preview|NAME] [--label NAME]|revoke PREFIX");
 }
 
-// Everything needed to put the bubble on a page, in one screen: what the
-// platform will actually enforce, the tokens that exist, and the snippet to
-// paste. Read-only -- vatio.yml owns every field, so `vatio push` is what
-// changes it.
 export async function widget(config, args) {
   const environment = environmentOption(args, "live");
   const workspace = config.resolveWorkspaceRequired();

package/lib/help.mjs

@@ -39,16 +39,19 @@ flag, the directory decides.
 
   Knowledge:
     kb [list]                  Bases, and whether a deployed agent reads each
-    kb show NAME               One base and its sources
+    kb show NAME               One base: its sites and its entries
     kb create NAME | rm NAME
-    kb add-source BASE NAME URL [--include P] [--exclude P]
-    kb upload BASE FILE...     Upload files into a base
-    kb rm-source BASE NAME | reindex BASE [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 follow BASE URL         Read a site into the base, nightly
+    kb unfollow BASE URL | refresh BASE [URL]
 
   Credentials and the widget:
     secrets list|set KEY VALUE|rm KEY
     tokens list|create [--env NAME] [--label NAME]|revoke PREFIX
     widget [--env NAME]        What the platform enforces, and the tokens there are
+    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):
     whatsapp [status]|connect|check|activate|deactivate|disconnect

package/lib/workspace.mjs

@@ -2,7 +2,7 @@
 // contract -- the port of cli/lib/workspace_root.rb, and deliberately just as
 // small.
 //
-// What a `tools/*.js` declares, which blocks `vatio.yml` accepts and whether
+// What a `tools/*.yml` declares, which blocks `vatio.yml` accepts and whether
 // any of it is valid are answered by POST /api/v1/:slug/deploy/check. The one
 // thing a client cannot ask the platform for is the address of that call: the
 // slug is in its URL. So this reads `workspace:` and stops.
@@ -16,7 +16,8 @@ export const MANIFEST_FILE = "vatio.yml";
 // past this is still the platform's to reject; matching here only turns a typo
 // into a sentence instead of a 404.
 export const SLUG_FORMAT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-// A workspace has exactly one agent and it is the conversation entry point.
+// The key `agent:` stores its single agent under, and the default an `entry:`
+// table falls back to. A workspace may declare several under `agents:`.
 export const ENTRY_AGENT = "main";
 
 // The manifest in a directory, or null when the directory is not a workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vatio-ai/cli",
-  "version": "0.37.2",
+  "version": "0.44.0",
   "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
   "keywords": ["vatio", "agent", "ai", "cli", "deploy"],
   "homepage": "https://vatio.ai",