npm - @vatio-ai/skills - Versions diffs - 1.30.1 → 2.0.0 - Mend

@vatio-ai/skills 1.30.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/.claude-plugin/marketplace.json +2 -2
package/.claude-plugin/plugin.json +8 -2
package/README.md +56 -47
package/bin/install.mjs +47 -6
package/package.json +2 -2
package/skills/vatio-analyze/SKILL.md +26 -35
package/skills/vatio-improve/SKILL.md +61 -82
package/skills/vatio-init/SKILL.md +145 -123

package/.claude-plugin/marketplace.json CHANGED Viewed

@@ -11,8 +11,8 @@
     {
       "name": "vatio",
       "source": "./",
-      "description": "Vatio skills for Claude Code, Cursor and Codex: add an AI agent to the app you're building with /vatio-init, then improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze.",
-      "version": "1.25.1",
+      "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
+      "version": "2.0.0",
       "homepage": "https://vatio.ai/docs/integrations/claude-code",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "vatio",
-  "description": "Vatio skills for Claude Code, Cursor and Codex: add an AI agent to the app you're building with /vatio-init, then improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze.",
-  "version": "1.30.1",
+  "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
+  "version": "2.0.0",
   "author": {
     "name": "Vatio",
     "url": "https://vatio.ai"
@@ -9,6 +9,12 @@
   "homepage": "https://vatio.ai/docs/integrations/claude-code",
   "repository": "https://github.com/vatio-ai/skills",
   "license": "MIT",
+  "mcpServers": {
+    "vatio": {
+      "type": "http",
+      "url": "https://vatio.ai/mcp"
+    }
+  },
   "keywords": [
     "vatio",
     "ai-agent",

package/README.md CHANGED Viewed

@@ -7,38 +7,47 @@ the app and its users. In your app’s project:
 npx @vatio-ai/skills
 ```
-Then, in Claude Code, run `/vatio-init` (in Cursor or Codex, ask it to use
-vatio-init). It builds the agent from your project; [Vatio](https://vatio.ai)
-runs it with an inbox, human handoff and evaluation checks. You try the preview
-and approve publication.
+Then, in Claude Code, approve the **vatio** MCP server it asks about, sign in
+to Vatio, and run `/vatio-init` (in Cursor or Codex, ask it to use
+vatio-init). It builds the agent from your project, writes its tests and puts
+it in your app; [Vatio](https://vatio.ai) holds and runs it, with an inbox,
+human handoff and the tests checked before every publish. There are no config
+files to keep in your repository: the agent lives on Vatio and your coding
+agent changes it through the Vatio MCP.
 After launch, report mistakes in the inbox and make `/vatio-improve` your
-daily routine. Your coding agent prepares fixes, Vatio tests the reported
-cases, and you approve the update. You do not need to write code yourself; you
-need your app’s project on your computer and Node.js 20 or newer.
+daily routine. Your coding agent fixes the agent, Vatio replays the reported
+cases and your tests, and you approve the update. You do not need to write
+code yourself; you need your app’s project on your computer and Node.js 20 or
+newer.
 | Skill | What it does |
 |---|---|
-| `vatio-init` | The first one in a project: looks at what is already there (a `vatio.yml` anywhere in the repository, the app's code) and recommends from it. With no agent yet, builds one: asks the owner what the code does not answer, writes `vatio.yml`, pushes it and hands over a link to try. With one, gets a developer who joined the project up to speed |
-| `vatio-improve` | Takes every reply your supervisors reported in the inbox in one session: reads `vatio test list`, fixes each cause, `vatio push`, proves it with `vatio test` (on Vatio's servers, in the background) and publishes with `vatio publish` after your approval |
-| `vatio-analyze` | Reads what people talked about with the agent between two dates, from `vatio chat export` (redacted by Vatio before it leaves): topics with their counts, the questions it could not answer and the words people use, in a report for writing content, FAQs or knowledge. Anyone on the workspace's team can run it, viewers included |
-| `vatio-share-session` | Sends the coding session to the Vatio team when you ask it to, or offers to when the others finish (send it, not now, or don't ask again), after showing you what goes (images left out, anything that looks like a secret redacted), with your feedback if you want to add some |
+| `vatio-init` | The first one in a project: looks at what is already there (the workspaces your account reaches, the app's code) and recommends from it. With no agent yet, builds one through the MCP: asks the owner what the code does not answer, writes its instructions, knowledge and tools, tries it, writes its tests, puts the widget or SDK in your app and hands over a link to try. With one, gets a developer who joined the project up to speed |
+| `vatio-improve` | Takes every reply your supervisors reported in the inbox in one session: reads `list_reports`, fixes each cause, proves it with `run_tests` (on Vatio's servers) and publishes after your approval |
+| `vatio-analyze` | Reads what people talked about with the agent between two dates, from `list_conversations` (redacted by Vatio before it leaves): topics with their counts, the questions it could not answer and the words people use, in a report for writing content, FAQs or knowledge. Anyone on the workspace's team can run it, viewers included |
+| `vatio-share-session` | Sends the coding session to the Vatio team when you ask it to, after showing you what goes (images left out, anything that looks like a secret redacted), with your feedback if you want to add some |
-The skills are short on purpose. They tell your coding agent when to reach for
-the Vatio CLI; the instructions themselves come from the platform when it runs
-`vatio docs` or `vatio test list`, so they are never out of date.
+The skills are short on purpose. They tell your coding agent which of the
+Vatio MCP's tools to reach for; the instructions for working reports and tests
+come from the platform when it reads them, so they are never out of date.
 ## Install
 `npx @vatio-ai/skills` copies the skills into `.claude/skills/`, where Claude
 Code reads them, and `.agents/skills/`, where Codex, Cursor, Gemini CLI,
-GitHub Copilot and most other coding agents do. Run it again to update them.
+GitHub Copilot and most other coding agents do. It also adds the Vatio MCP
+(`https://vatio.ai/mcp`) to the project's `.mcp.json` and, when the project
+has a `.cursor/`, to `.cursor/mcp.json`; `--no-mcp` leaves those alone. Run it
+again to update the skills. Elsewhere, connect `https://vatio.ai/mcp` as your
+coding agent's docs say ([Vatio in Claude and ChatGPT](https://vatio.ai/docs/mcp)).
 ### As a Claude Code plugin
-In Claude Code the same skills come as a plugin that can update itself. Run
-these one at a time and follow the installation panel; the commands are then
-`/vatio:vatio-init` and `/vatio:vatio-improve`:
+In Claude Code the same skills come as a plugin that can update itself, and
+brings the Vatio MCP with it. Run these one at a time and follow the
+installation panel; the commands are then `/vatio:vatio-init` and
+`/vatio:vatio-improve`:
 ```text
 /plugin marketplace add vatio-ai/skills
@@ -55,34 +64,33 @@ Vatio, or you can call them by
 name: `/vatio-init`, `/vatio-improve`, `/vatio-analyze` and `/vatio-share-session`, or
 `/vatio:vatio-init` and so on from the plugin.
-`vatio init` also writes a pointer to `vatio test list` into the workspace's
-`AGENTS.md`, which most coding agents read without installing anything.
 ## What it runs and sends
-The skills are instructions for your coding agent, with no hooks, MCP servers
-or anything that runs by itself. What they have your agent run is one
-program, the [Vatio CLI](https://github.com/vatio-ai/cli)
-(`npx @vatio-ai/cli`, downloaded from npm), and it talks to one service,
+The skills are instructions for your coding agent, with no hooks or anything
+that runs by itself. They work through one MCP server,
+[vatio.ai/mcp](https://vatio.ai/docs/mcp), and for sharing a session when you
+ask, the [Vatio CLI](https://github.com/vatio-ai/cli)
+(`npx @vatio-ai/cli`, downloaded from npm). Both talk to one service,
 [vatio.ai](https://vatio.ai):
-- **Sign-in.** The first `vatio push` (or `vatio login`) opens vatio.ai in your
-  browser; the token it gets back is saved in `~/.vatio/config.json`.
-- **Your agent's files.** `vatio check` and `vatio push` send the directory
-  that holds `vatio.yml` (its tools and knowledge, never hidden files such as
-  `.env` or `.git/`) to vatio.ai, which runs the agent. `vatio secrets set`
-  sends a secret you name, stored encrypted.
-- **Conversations.** `vatio chat` sends what you type to your agent.
-  `vatio test list`, `vatio chat show` and `vatio chat export` (redacted by Vatio
-  before it leaves) bring your workspace's conversations to your terminal.
-  `vatio docs` fetches the docs.
-- **How each command ended.** The CLI tells Vatio which command ran, its exit
-  code, how long it took, which version of these skills the project has and,
-  on failure, what it printed; never arguments, file contents, secrets or what
-  a chat said. Installing these skills tells Vatio once, with their version
-  and the coding agent. `VATIO_TELEMETRY=0` turns both off.
-- **Feedback.** `vatio feedback "..."` sends the text your agent writes about
-  what got in its way.
+- **Sign-in.** Your coding agent's MCP client opens vatio.ai to sign you in,
+  and keeps the token it gets back. You see the connection under
+  **Account → Sessions** in the inbox and can end it there.
+- **Your agent.** The MCP's tools send what your coding agent writes (the
+  agent's instructions, knowledge, tools and tests) to vatio.ai, which runs
+  the agent. `set_secret` sends a secret you name, stored encrypted and never
+  shown again.
+- **Conversations.** `chat_with_agent` sends what your coding agent types to
+  your agent. `list_reports`, `get_conversation` and `list_conversations`
+  (redacted by Vatio before it leaves) bring your workspace's conversations to
+  it, and each read is recorded in the workspace's Activity.
+- **How each tool call ended.** Vatio records which tool ran, whether it ended
+  in an error, how long it took and which app made the call; never what a tool
+  was given or returned. Installing these skills tells Vatio once, with their
+  version and the coding agent. `VATIO_TELEMETRY=0` skips that.
+- **Feedback.** At the end of `vatio-init` and `vatio-improve`, your agent
+  sends the Vatio team a few sentences with the MCP's `send_feedback`: which
+  step took the most work, and why.
 - **Your coding session, only if you say yes.** `vatio-share-session` shows
   you what would go (images left out, anything that looks like a secret
   redacted) and sends it to the Vatio team only after you agree.
@@ -92,8 +100,9 @@ What Vatio keeps and for how long is in its
 ## Docs
-[Improve your agent from flags](https://vatio.ai/docs/improve) ·
-[CLI](https://vatio.ai/docs/cli/) · [Changelog](https://vatio.ai/docs/changelog)
+[Vatio MCP](https://vatio.ai/docs/mcp) ·
+[Improve your agent from reports](https://vatio.ai/docs/improve) ·
+[Changelog](https://vatio.ai/docs/changelog)
 ## Issues
@@ -113,6 +122,6 @@ npx @vatio-ai/skills
 ```
 This copies the skills into `.agents/skills/` and `.claude/skills/`.
-Run it again to update them. Any coding agent that reads those skills can
-follow the same procedures. You can also use `npx skills add vatio-ai/skills`
-with the [skills CLI](https://skills.sh).
+Run it again to update them. Any coding agent that reads those skills, and
+connects `https://vatio.ai/mcp`, can follow the same procedures. You can also
+use `npx skills add vatio-ai/skills` with the [skills CLI](https://skills.sh).

package/bin/install.mjs CHANGED Viewed

@@ -3,7 +3,11 @@
 // runs in, for every coding agent at once:
 //   .agents/skills/   Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Cline, Amp
 //   .claude/skills/   Claude Code, which does not read .agents/
-// Running it again overwrites the copies with this version's.
+// and connects the Vatio MCP the skills build and test the agent with:
+//   .mcp.json         Claude Code, which asks before using a project's server
+//   .cursor/mcp.json  Cursor, when the project has a .cursor/
+// Running it again overwrites the copies with this version's; an MCP entry
+// already there is left as it is.
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
@@ -11,19 +15,24 @@ import { homedir, platform } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-const usage = `usage: npx @vatio-ai/skills [--dir PATH]
+const usage = `usage: npx @vatio-ai/skills [--dir PATH] [--no-mcp]
 Copies the Vatio skills (vatio-init, vatio-improve, vatio-analyze,
-vatio-share-session) into PATH/.agents/skills and
-PATH/.claude/skills. PATH defaults to the current directory.`;
+vatio-share-session) into PATH/.agents/skills and PATH/.claude/skills,
+and adds the Vatio MCP (https://vatio.ai/mcp) to PATH/.mcp.json and,
+when there is a PATH/.cursor, PATH/.cursor/mcp.json. --no-mcp leaves
+those alone. PATH defaults to the current directory.`;
 const args = process.argv.slice(2);
 let root = process.cwd();
+let mcp = true;
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
   if (arg === "-h" || arg === "--help") {
     console.log(usage);
     process.exit(0);
+  } else if (arg === "--no-mcp") {
+    mcp = false;
   } else if (arg === "--dir" && args[i + 1]) {
     root = args[++i];
   } else {
@@ -72,8 +81,41 @@ function installedByUs(dir, name) {
   }
 }
+const base = String(process.env.VATIO_BASE_URL ?? "").trim().replace(/\/+$/, "") || "https://vatio.ai";
+const mcpUrl = `${base}/mcp`;
+if (mcp) {
+  addServer(join(root, ".mcp.json"), { type: "http", url: mcpUrl });
+  if (existsSync(join(root, ".cursor"))) addServer(join(root, ".cursor", "mcp.json"), { url: mcpUrl });
+}
+// Adds `vatio` to an MCP config's servers, keeping everything else in it. A
+// file that is not JSON is the developer's to fix, not ours to replace.
+function addServer(file, server) {
+  const shown = relative(process.cwd(), file) || file;
+  let config = {};
+  if (existsSync(file)) {
+    try {
+      config = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      console.log(`  ${shown} is not valid JSON: left alone. Add the Vatio MCP (${mcpUrl}) to it yourself.`);
+      return;
+    }
+  }
+  config.mcpServers ??= {};
+  if (config.mcpServers.vatio) {
+    console.log(`  ${shown} already has the Vatio MCP`);
+    return;
+  }
+  config.mcpServers.vatio = server;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  console.log(`  ${shown}: the Vatio MCP (${mcpUrl})`);
+}
 console.log(`
-Ask your coding agent to build or improve a Vatio agent and it will use them.
+Then, in Claude Code, approve the vatio server it asks about (or run /mcp) and
+sign in to Vatio; in another coding agent, connect ${mcpUrl}. Ask it to build or
+improve a Vatio agent, or run /vatio-init, and it will use them.
 Docs: https://vatio.ai/docs/integrations/claude-code`);
 await reportInstall();
@@ -88,7 +130,6 @@ async function reportInstall() {
   if (off) return;
   console.log("Letting Vatio know these skills were installed (their version and the coding agent, nothing else).\nVATIO_TELEMETRY=0 skips it.");
-  const base = String(process.env.VATIO_BASE_URL ?? "").trim().replace(/\/+$/, "") || "https://vatio.ai";
   try {
     await fetch(`${base}/api/developer/v1/cli/events`, {
       method: "POST",

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@vatio-ai/skills",
-  "version": "1.30.1",
-  "description": "Vatio skills for Claude Code, Cursor and Codex: add an AI agent to the app you're building with /vatio-init, then improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze.",
+  "version": "2.0.0",
+  "description": "Vatio skills and MCP for Claude Code, Cursor and Codex: build and test an AI agent for the app you're building with /vatio-init, improve it daily with /vatio-improve and learn what people ask it with /vatio-analyze. Vatio holds the agent; no config files in your repo.",
   "keywords": [
     "vatio",
     "ai-agent",

package/skills/vatio-analyze/SKILL.md CHANGED Viewed

@@ -1,44 +1,35 @@
 ---
 name: vatio-analyze
-description: Analyze what people talk about with a Vatio agent, from its real conversations between two dates — topics, frequent questions, questions it could not answer, and the words people use — to write content, FAQs or knowledge, or to report on it. Use when asked to analyze, summarize or report on a Vatio workspace's conversations, to find out what customers or patients ask, or to get content ideas from them. Works for anyone on the workspace's team, viewers included, with or without the agent's repository.
+description: Analyze what people talk about with a Vatio agent, from its real conversations between two dates — topics, frequent questions, questions it could not answer, and the words people use — to write content, FAQs or knowledge, or to report on it. Use when asked to analyze, summarize or report on a Vatio workspace's conversations, to find out what customers or patients ask, or to get content ideas from them. Works for anyone on the workspace's team, viewers included, through the Vatio MCP, with or without the app's repository.
 ---
 # Analyze a Vatio agent's conversations
-`vatio chat export` prints what people said to the agent, and what they were
-answered, between two dates: one conversation per line as JSON. Vatio redacts
-it before it leaves: names, emails, phone numbers, handles and RUTs it
-recognizes read `[FILTERED]`, and `person` stands for whoever it was without
-naming them. Every export is recorded in the workspace's Activity, under the
-name of whoever ran it.
+The Vatio MCP's `list_conversations` returns what people said to the agent,
+and what they were answered, between two dates. Vatio redacts it before it
+leaves: names, emails, phone numbers, handles and RUTs it recognizes read
+`[FILTERED]`, and `person` stands for whoever it was without naming them.
+Every read is recorded in the workspace's Activity, under the name of whoever
+made it. If you do not have the MCP's tools, connect it as the `vatio-init`
+skill's step 0 says.
-1. **Find the workspace.** The CLI reads it from the nearest `vatio.yml`. With
-   none here, ask for the workspace's slug (the part after
-   `inbox.vatio.ai/` in their inbox) and write a one-line one in a new folder
-   outside any repository:
-   ```bash
-   mkdir vatio-conversations && cd vatio-conversations
-   echo "workspace: SLUG" > vatio.yml
-   ```
+1. **Find the workspace.** `list_workspaces` lists the ones this account
+   reaches, with its role in each: any role works, viewers included. If the
+   one they mean is not there, the owner invites them from **Team** in the
+   inbox, with the email they signed in with. A workspace that requires
+   two-step verification needs it turned on in **Account** in the inbox
+   first.
 2. **Ask what the analysis is for,** if they have not said: content for a
    website or a search engine, FAQs, gaps in the agent's knowledge, a report.
    Ask for the dates too, or use the last 30 days and say so.
-3. **Export.** Use `npx @vatio-ai/cli@latest` if `vatio` is not installed:
-   ```bash
-   vatio chat export --from 2026-09-01 --to 2026-09-30 --out conversations.jsonl
-   ```
-   `--channel whatsapp` (or `instagram`, `web`, `widget`, `ios`, `android`)
-   narrows it, and `vatio chat help` explains the rest. If it asks to sign in,
-   run `vatio login`: they sign in in the browser with the email they were
-   invited with. `workspace_forbidden` means another email, or nobody has
-   invited them yet: the owner does it from **Team** in the inbox, and any
-   role works. `two_factor_required` means turning on two-step verification
-   in **Account** in the inbox first.
+3. **Fetch it all.** `list_conversations` with `from` and `to` (dates or
+   ISO 8601 times), `limit: 100` and, for each next page, `after` set to the
+   `next_after` the last page returned, until there is none. `channel`
+   (`whatsapp`, `instagram`, `web`, `widget`, `ios`, `android`) narrows it.
+   Write each page to a file as it arrives (`conversations.jsonl`, outside
+   git), one conversation per line, rather than holding them in your head.
 4. **Count before reading.** In a script (`jq`, Python or Node), get the number
    of conversations and messages, conversations per channel and per week, and
@@ -54,7 +45,7 @@ name of whoever ran it.
    batches, in parallel if you can run subagents, and keep the tally in a
    file, not in your head.
-6. **Report,** in the user's language, in a markdown file next to the export:
+6. **Report,** in the user's language, in a markdown file next to `conversations.jsonl`:
    - the dates, channels and number of conversations it covers;
    - the topics, largest first, each with its count and share and two or
      three short questions as people wrote them, spelling and all: they are
@@ -67,12 +58,12 @@ name of whoever ran it.
    Say what the numbers cannot tell: a sample, a short window, a channel left
    out.
-Treat the export as the private conversations it is. Never try to work out
+Treat `conversations.jsonl` as the private conversations it is. Never try to work out
 who someone is, and if something identifying slipped past the redaction (a
-third person's name, an address), leave it out of the report. Keep the export
+third person's name, an address), leave it out of the report. Keep the file
 out of git, and ask whether to delete it when you are done. Do not offer
 `vatio-share-session` after this skill: the session holds those conversations.
-If the export or its docs left you guessing,
-`vatio feedback "what you were doing and what was missing"` tells the Vatio
-team.
+If the conversations or the docs left you guessing, the MCP's
+`send_feedback` tells the Vatio team: what you were doing and what got in the
+way, without quoting the conversations.

package/skills/vatio-improve/SKILL.md CHANGED Viewed

@@ -1,23 +1,22 @@
 ---
 name: vatio-improve
-description: Improve a Vatio agent from what its supervisors reported. Use when asked to improve, fix or debug a Vatio agent, to work through reported or flagged replies or wrong answers in production, or when the daily Vatio email says there are open reports. Works in any directory with a vatio.yml.
+description: Improve a Vatio agent from what its supervisors reported, through the Vatio MCP. Use when asked to improve, fix or debug a Vatio agent, to work through reported or flagged replies or wrong answers in production, or when the daily Vatio email says there are open reports. Needs the Vatio MCP, not a vatio.yml.
 ---
 # Improve a Vatio agent from its reports
 Supervisors report wrong replies in the Vatio inbox and write what it should
 have said: a different answer, an action, or a tool the agent should have
-used or does not have. One session takes every open report. Vatio keeps the
-instructions for working them on the platform, so they are never out of date
-here. Start by reading them:
+used or does not have. One session takes every open report. You work through
+the Vatio MCP's tools; if you do not have them (`list_reports`,
+`update_agent`, `run_tests`…), connect it as the `vatio-init` skill's step 0
+says, and stop until they are there.
-```bash
-vatio test list
-```
-Run it from the directory with the workspace's `vatio.yml` (or below it).
-It prints every open report — the conversation, each tool call with what
-the backend answered, and the supervisor's note — then the tests that fail on preview and the ones the
+Vatio keeps the instructions for working the reports on the platform, so they
+are never out of date here. Start by reading them: `list_workspaces` for the
+slug (or the one the app names), then `list_reports`. It returns every open
+report (the conversation, each tool call with what the backend answered, and
+the supervisor's note), then the tests that fail on preview and the ones the
 agent answers differently each time, with how to work them at the top, and
 every test last. Follow those instructions; they take precedence over
 anything below.
@@ -27,80 +26,60 @@ In short:
 1. Read each report's **Diagnosis** first: it says whose it is to fix, from
    what that turn did. **Your backend**: a tool call to it failed. **Your
    agent**: everything answered and the reply was still wrong, so the fix is
-   in `vatio.yml`, knowledge or a tool's definition. **Vatio**: the model
-   provider or Vatio failed and Vatio wrote the reply itself. Do not change
-   the agent for those: tell the developer, who can remove the report, and
-   if they keep happening, `vatio feedback`.
-   `vatio test rm ID` removes a report and its test for everyone. It is the
+   in the agent's instructions, its knowledge or a tool's definition.
+   **Vatio**: the model provider or Vatio failed and Vatio wrote the reply
+   itself. Do not change the agent for those: tell the developer, who can
+   remove the report, and if they keep happening,
+   `npx @vatio-ai/cli@latest feedback "…"`.
+   `remove_test` removes a report and its test for everyone. It is the
    developer's call: propose it (a report Vatio caused, one that asks for
    something the agent must not do, one whose fix is in but the tests cannot
    reproduce) and run it only when they say so.
-   Vatio changes nothing on preview by itself: every open report is yours to
-   fix.
 2. Group the reports by cause, and fix each cause where it lives:
-   `vatio.yml`, a knowledge entry, a tool, or the developer's backend a tool
-   calls. `vatio tools --env live` shows each tool's error rate, timeouts and
-   latency, and the calls that failed with what the backend answered: a
-   failing tool rarely gets reported, because the agent apologizes and moves
-   on. Fix those too. After the reports come the tests that fail on preview
-   (one the developer added for something the agent does not do yet, or a
-   regression) and the tests the agent answers differently each time (the
-   same version passes and fails them): work those too, as their sections
-   say. For an unsteady one the agent is usually inconsistent and the fix is
-   in `vatio.yml` or knowledge; when the note is what is vague, rewrite it;
-   when it no longer applies, propose removing it to the developer. Never
-   remove a test because it fails. Something the developer asks the agent to
-   do that no report covers is a test first:
-   `vatio test add "QUESTION" "WHAT IT SHOULD DO"` asks it on preview and
-   says whether it passes now; then fix until it does.
-3. `vatio push`. It updates preview and runs no tests. No branch or
-   environment to set up: preview is the one. If it is refused because
-   preview has changes made outside the files (someone edited the agent from
-   the Vatio MCP in Claude or ChatGPT), run `vatio pull`, which writes them
-   into `vatio.yml` and `tools/` (commit your work first: it wants a clean
-   git tree), check `git diff` still carries your fix, and push again. Never
-   `vatio push --force` over them unless the developer says so.
-4. `vatio test` tests every report against preview, on Vatio's servers: it
-   starts the runs, prints their ids and returns. `vatio test --wait` waits
-   for the report (several minutes), so in Claude Code start that with the
-   Bash tool's `run_in_background` and read the report when it finishes;
-   `vatio test --show RUN_ID` prints a run so far. A case that did not pass
-   comes with the `vatio chat show CHAT_ID` of its replay. Iterate (fix, push,
-   test) until the reports pass and nothing that passes on live fails. A case
-   marked "not tested (Vatio's side)" says nothing about your fix: run
-   `vatio test --wait` again. One not tested because a tool needs a
-   signed-in visitor replays signed in with `vatio test --as-subject ID`. Name reports by id (`F-7K2QX`).
-5. Show the developer what passes now, and `vatio publish` once they agree:
-   it changes what visitors get. In a draft (no conversation from outside
-   the team yet) live already runs every push, and `vatio publish` says
-   there is nothing to publish. If it is refused, follow its message: it
-   says what to run. Never pass `--force` unless the developer explicitly
-   asks for it.
-6. If the digest, an error or the docs left you guessing, say so:
-   `vatio feedback "what you were doing and what was missing"`.
-7. Last, in Claude Code, offer to send this session to the Vatio team, as
-   the `vatio-share-session` skill says. It starts with
-   `vatio share-session --should-ask`: if that prints `no`, say nothing.
+   `update_agent` (instructions, tools, knowledge, links),
+   `write_knowledge_entry`, `set_tool`, or the app's backend a tool calls
+   (that code is in the app's repository). `get_tool_health` shows each tool's
+   error rate, timeouts and latency, and the calls that failed with what the
+   backend answered: a failing tool rarely gets reported, because the agent
+   apologizes and moves on. Fix those too. After the reports come the tests
+   that fail on preview and the ones the agent answers differently each time:
+   work those too, as their sections say. Never remove a test because it
+   fails. Something the developer asks the agent to do that no report covers
+   is a test first: `add_test` with `question` and `should` asks it on preview,
+   and `get_test` with the `chat_id` it answers with says whether it passes
+   now; then fix until it does.
+3. Each change lands on preview at once and runs no tests. `get_agent` reads
+   the agent whole before you change it.
+4. `run_tests` replays every report and test against preview on Vatio's
+   servers and returns the run ids; `get_test_results` with each id shows the
+   report so far. It takes a few minutes: ask again until it has finished. A
+   case that did not pass names the conversation of its replay
+   (`get_conversation`). Iterate (fix, `run_tests`) until the reports pass
+   and nothing that passes on live fails. A case marked "not tested (Vatio's
+   side)" says nothing about your fix: run the tests again. One not tested
+   because a tool needs a signed-in visitor replays signed in with
+   `run_tests` and a `visitor_token`
+   (https://vatio.ai/docs/authentication/tools.md#test-a-private-tool).
+   Name reports by id (`F-7K2QX`).
+5. Show the developer what passes now, and `publish` once they agree: it
+   changes what visitors get. In a draft (no conversation from outside the
+   team yet) live already runs every change, and `publish` says there is
+   nothing to publish. If it is refused, follow its message. Never pass
+   `force` unless the developer explicitly asks for it; `rollback` undoes a
+   publish.
+6. Last, tell the Vatio team how it went, with the MCP's `send_feedback`
+   (and the workspace's slug): which step of fixing the reports took the most
+   work, and why (a report that left you guessing, a test that would not
+   reproduce, a tool or an error that got in the way). A few sentences, with no
+   secrets or visitors' words, and tell the developer in one line that you
+   sent it.
-If the fix needs more than the digest says, `vatio docs search TERM` prints
-the sections of the docs that mention something, with their page,
-`vatio docs PAGE` one page (`tools`, `knowledge`), and `vatio docs` the whole
-contract (manifest, tools, knowledge, CLI). There are two ways to run the CLI,
-and the package name appears once in either: `vatio ARGS` when it is
-installed globally, and `npx @vatio-ai/cli@latest ARGS` when it is not. Pick
-one per command and leave it whole — `npx @vatio-ai/cli @vatio-ai/cli flags`
-is the commonest way to get this wrong, and the CLI reads the second name as
-the command and fails. If it says to log in, run `vatio login`: it
-opens the browser on the developer's machine (if it doesn't, give them the
-link it prints), and they sign in and check the code matches. If it times
-out, run it again after they have signed in.
+The reports hold real visitors' conversations. Keep them out of commits,
+issues and logs: refer to a report by its id and describe the cause, never
+quote what the visitor or the backend said.
-A command you hand the developer to run themselves, because a permission
-check refused it or it needs their own credentials, says
-`npx @vatio-ai/cli@latest`, never `vatio`: the `vatio` installed on their
-machine can be too old for Vatio to accept. When one command's output feeds
-another (a key into a secrets store), take it with `--json` and chain with
-`&&`, never through `grep`, so a failure stops there instead of passing on an
-empty value. If Claude Code's auto mode refused a `vatio` command and the
-project's `.claude/settings.json` has no `Bash(vatio *)` rule, also mention
-**Auto mode** on the docs' Claude Code page.
+When a fix needs more than the reports say,
+`npx @vatio-ai/cli@latest docs search TERM` prints the sections of the docs
+that mention it, with their page, and `npx @vatio-ai/cli@latest docs PAGE`
+one page (`tools`, `knowledge`); neither needs a workspace or a sign-in.
+https://vatio.ai/docs/llms.txt indexes every page as markdown.

package/skills/vatio-init/SKILL.md CHANGED Viewed

@@ -1,144 +1,166 @@
 ---
 name: vatio-init
-description: The first Vatio skill in a project. Looks at what is already there — a vatio.yml anywhere in the repository, the workspace on the platform, the app's own code — and recommends from it, then either builds a customer-facing AI agent (in the app first, through its web widget or mobile SDK, and on WhatsApp or Instagram when asked) and gets it to Try the agent in the Vatio inbox, or gets a developer who joined a project that already has one up to speed. Use when asked to create, set up, start or ship a Vatio agent, a chatbot or a support/sales assistant on Vatio, to get started on or onboard onto a project that uses Vatio, or when the user pastes the prompt from vatio.ai.
+description: The first Vatio skill in a project. Looks at what is already there — the workspaces the Vatio MCP reaches, the app's own code — and recommends from it, then either builds a customer-facing AI agent through the Vatio MCP (in the app first, through its web widget or mobile SDK, and on WhatsApp or Instagram when asked), writes its tests and gets it to Try the agent in the Vatio inbox, or gets a developer who joined a project that already has one up to speed. Use when asked to create, set up, start or ship a Vatio agent, a chatbot or a support/sales assistant on Vatio, to get started on or onboard onto a project that uses Vatio, or when the user pastes the prompt from vatio.ai.
 ---
 # Start with Vatio in this project
-Look before you create: the project may already have an agent. Vatio keeps
-the contract and the procedures on the platform, so they are never out of
-date here. Read them first:
+Vatio holds the agent: its instructions, knowledge, tools, secrets and tests
+live on the platform, and you build and test it with the Vatio MCP's tools.
+Nothing about the agent goes into the app's repository. What does is what
+puts it in front of people (the widget or SDK) and any endpoint of the app
+the agent calls.
-```bash
-npx @vatio-ai/cli docs
-```
+## 0. The Vatio MCP
-Under **For coding agents**, **Starting a new agent** and **Joining an
-existing workspace** are the two procedures. Follow the one that fits; it
-takes precedence over the summary below. The rest of that output is the
-contract for `vatio.yml`, tools, knowledge and the CLI. To look something up
-again later, `npx @vatio-ai/cli docs search TERM` prints the sections that
-mention it, with their page, and `npx @vatio-ai/cli docs PAGE` one page
-(`tools`, `knowledge`, `cli/deploy`), rather than reading it all twice.
+Its tools are `list_workspaces`, `update_agent`, `chat_with_agent`,
+`add_test` and the rest. If you do not have them:
+- **Claude Code:** `npx @vatio-ai/skills` added the server to this project's
+  `.mcp.json`. If it is not there, `claude mcp add --transport http vatio
+  https://vatio.ai/mcp`. Then the person runs `/mcp`, picks **vatio** and
+  signs in (email, Google or GitHub): only they can. A server added during a
+  session loads when Claude Code starts again, so say so and stop until its
+  tools are there.
+- **Cursor, Codex and the rest:** add an MCP server at `https://vatio.ai/mcp`
+  (Streamable HTTP, OAuth), as https://vatio.ai/docs/mcp.md says.
+Never work around a missing MCP by writing a `vatio.yml` or running
+`vatio push`.
 ## 1. Look at what is there
-- **An agent.** Every `vatio.yml`, at or above the current directory and
-  anywhere in the repository (`git ls-files '*vatio.yml'`). Its
-  `workspace:` line names the workspace.
-- **The app.** What the project does and for whom; the API an agent could
-  call (routes, controllers, an OpenAPI file); how its users sign in; and the
-  docs, FAQs or policies an agent could read as knowledge.
-- **This machine.** `vatio doctor`: whether it is signed in, and which
-  workspace this directory resolves to.
+- **The account.** `list_workspaces`: every workspace the person reaches and
+  their role in it.
+- **The app.** What it does and for whom; the API an agent could call
+  (routes, controllers, an OpenAPI file); how its users sign in; the docs,
+  FAQs or policies an agent could read as knowledge; and whether Vatio is
+  already in it (`cdn.vatio.ai`, `@vatio-ai/widget`, `data-workspace`, an
+  SDK's setup), which names its workspace.
+- **A `vatio.yml`** anywhere in the repository (`git ls-files
+  '*vatio.yml'`) means a team kept the agent as files. The agent is still
+  the one on Vatio, under its `workspace:` slug.
 ## 2. Say what you found, and recommend
-Before changing anything, tell the user in a few lines what is there and what
-you recommend, and ask them to confirm.
-- **No `vatio.yml`: a new agent.** Propose what it could do from what you
-  read: what it answers, which endpoints become tools, what becomes
-  knowledge. Then follow **Starting a new agent**, in short:
-  1. Ask the owner only what the code does not answer: what the business
-     does, what the agent must never say, when it hands off to a person,
-     which of their systems it should read from. Do not invent business
-     facts.
-  2. `vatio init SLUG` in the repository the agent belongs in, then write
-     `vatio.yml` (and `tools/` for their APIs, with one that alerts their
-     team when a person should take over: **Human in the loop** in the docs).
-  3. `vatio diff`, `vatio push`, then try it with `vatio chat`, including a
-     conversation that should hand off. A tool that needs the visitor's
-     phone or a team role runs with `vatio chat --as-phone me` (or a
-     customer phone); an `access: private` one with `--as-subject ID`. When visitors
-     will send files (a PDF, a photo), send one with `vatio chat --file PATH
-     "question"`: it says how much of a PDF the agent got.
-  4. **Write down what it should do as tests.** For each question that
-     matters, `vatio test add "what a visitor would ask" "what the answer has
-     to do"`: it asks it on preview and says whether it passes now (add
-     `--as-phone` or `--as-subject` as in `vatio chat`). Three or four is
-     enough to start. This is
-     the only thing that makes a later version's mistake visible: `vatio
-     test` replays them on every push, and once the workspace is published
-     `vatio publish` refuses a version that breaks one. A workspace with no
-     tests publishes with nothing checked, which is how a fix for one
-     question quietly breaks another.
-  5. Give them the link `vatio push` prints after `Try it:` (the inbox
-     with Try the agent open: web chat, WhatsApp and Instagram) with what you
-     tried. Until someone outside their team talks to the agent the
-     workspace is a draft: `vatio push` is the deploy, so there is nothing to
-     publish yet and you need not explain preview and live. Every push says
-     which of the two states the workspace is in; once it says visitors still
-     get an older version, publish with `vatio publish` only when they ask.
-- **A `vatio.yml`: the agent exists.** Never `vatio init` here: it writes a
-  starter agent, and pushing that replaces the real one. Work from the
-  directory of the `vatio.yml` and follow **Joining an existing workspace**:
-  sign in with the address they were invited with, then
-  `vatio diff --env live` and `vatio status`. Explain the agent from
-  `vatio.yml` (what it is for, its tools, its knowledge, when it hands off)
-  and recommend from what you see:
-  - the folder differs from live: say so first, the repository may be behind;
-  - `vatio status` lists changes made outside the files (from the Vatio MCP
-    in Claude or ChatGPT): `vatio pull` writes them into `vatio.yml` and
-    `tools/` before anything is pushed;
-  - open reports in `vatio test list`: work them with the `vatio-improve` skill;
-  - tool calls failing in `vatio tools`: the fix is in the backend they call;
-  - `workspace_forbidden`: they are not in the workspace yet, and the owner
-    invites them from **Team** in the inbox.
-- **A workspace slug but no `vatio.yml`.** Ask for the repository it lives
-  in. If it was built from the Vatio MCP in Claude or ChatGPT, it has none
-  yet: `vatio init SLUG` in the repository it should live in, then, before
-  any push, `vatio pull --force` to replace the starter agent with the one
-  Vatio runs. Otherwise do not `vatio init` one instead.
+Before changing anything, tell the person in a few lines what is there and
+what you recommend, and ask them to confirm.
+### No workspace for this app: a new agent
+Propose what it could do from what you read: what it answers, which
+endpoints become tools, what becomes knowledge. Then:
+1. **Ask the owner only what the code does not answer:** what the business
+   does and who writes in, what the agent must never say or promise, when it
+   hands the conversation to a person, which of their systems it should read
+   from. Do not invent business facts.
+2. **Create it.** `create_workspace` (a slug from the app's name), then
+   `update_agent`: `instructions` from the answers, with the never-say rules
+   as explicit rules, a `name` and a `personality`. Anything long the agent
+   should read rather than memorize is knowledge: `create_knowledge_base`,
+   one `write_knowledge_entry` per topic, and the base in the agent's
+   `knowledge` (`update_agent`).
+3. **Connect the app's backend.** `set_secret` for its URL and credential,
+   taking the values from the app's `.env` (never repeat one back or write
+   it into a file); `set_backend` with `base_url` and `headers` that read them
+   as `$env.KEY`; then one `set_tool` per endpoint, after reading
+   https://vatio.ai/docs/tools.md. Give it a tool that alerts the team when a
+   person should take over (https://vatio.ai/docs/handoff.md). An endpoint the
+   app does not have yet is yours to write in the app. A tool that writes (an
+   order, a booking) needs a test value (`set_secret` with `tests: true`, a
+   staging API) so tests never write to production.
+4. **Try it** with `chat_with_agent`: a few representative conversations,
+   including one that should hand off and one that asks for something it must
+   not say. Read the tools each reply called and what the backend answered;
+   `get_conversation` shows a whole turn. A tool that needs the visitor's
+   phone or a team role runs with `as_phone: "me"` (or a customer phone); an
+   `access: private` one with `visitor_token`, a JWT for a test user signed
+   with the private key from step 6
+   (https://vatio.ai/docs/authentication/tools.md#test-a-private-tool).
+   When visitors will send files (a PDF, a photo, a voice note), send one
+   too: run the curl command `prepare_file` returns, then pass the id it
+   answers in `chat_with_agent`'s `files`.
+5. **Write down what it should do as tests.** For each question that
+   matters, `add_test` with `question` (what a visitor would ask) and
+   `should` (what the answer has to do). It asks it on preview and answers
+   at once with a `chat_id` and how many seconds to wait: add the other tests
+   meanwhile, then `get_test` with each `chat_id` shows the test and whether
+   it passes now (while it is still being made, it says when to ask again).
+   A reply you already have becomes one with `chat_id` or `message_id`. Three or four is enough to start, including the
+   hand-off and something it must not say. This is the only thing that makes
+   a later version's mistake visible: `run_tests` replays them all, and once
+   the workspace is published `publish` refuses a version that breaks one. A
+   workspace with no tests publishes with nothing checked, which is how a fix
+   for one question quietly breaks another. Fix and `add_test` again until
+   they pass; `run_tests` then `get_test_results` checks them all together.
+6. **Put it in the app.** `get_status` returns `put_in_the_app`: the
+   publishable key and the widget's script tag, which work from any site
+   (local and production alike), and `preview_key` to try preview locally.
+   Add the widget (the tag, or `@vatio-ai/widget`) or the iOS, Android or
+   Flutter SDK where the app's users are, in the app's style:
+   https://vatio.ai/docs/channels/widget.md, https://vatio.ai/docs/sdk/ios.md,
+   https://vatio.ai/docs/sdk/android.md, https://vatio.ai/docs/sdk/flutter.md.
+   When the agent must know who is signed in (their orders, their account),
+   the app's backend signs a JWT: make a keypair (`openssl genpkey -algorithm
+   RSA -pkeyopt rsa_keygen_bits:2048 -out vatio-private.pem`, then `openssl
+   pkey -in vatio-private.pem -pubout`), keep the private key in the backend's
+   secrets (never in the frontend, never committed), `set_auth` with the
+   public key, and follow https://vatio.ai/docs/authentication.md.
+7. **Hand over.** `get_status` gives `try_preview`: the inbox with Try the
+   agent open (web chat, WhatsApp and Instagram). Give it with what you tried
+   and the tests. Until someone outside the team talks to the agent the
+   workspace is a draft: every change reaches the app at once and there is
+   nothing to publish, so you need not explain preview and live. Once
+   `get_status` says it is no longer a draft, changes wait in preview:
+   `publish` only when they ask.
+### A workspace already exists
+The app names one, `list_workspaces` shows it, or a `vatio.yml` does. Never
+create another. `get_agent` and `get_status`, then explain the agent from them
+(what it is for, its tools, its knowledge, when it hands off) and recommend
+from what you see:
+- open reports in `list_reports`: work them with the `vatio-improve` skill;
+- tools failing in `get_tool_health`: the fix is in the backend they call;
+- few or no tests (`list_reports` lists them last): offer to `add_test` what
+  matters most;
+- the workspace is not in `list_workspaces`: the owner invites them from
+  **Team** in the inbox, with the email they signed in with.
+If there is a `vatio.yml`, the agent on Vatio is the one that counts and you
+change it through the MCP from now on. Recommend removing `vatio.yml`,
+`tools/` and `identity.pub` from the repository, so nobody pushes an old copy
+over it, and do it only with their yes.
 ## Claude Code permissions
-In Claude Code, once the agent is pushed, check the project's
+In Claude Code, once the agent works, check the project's
 `.claude/settings.json` (in the folder Claude Code was opened in). If it has
-no `Bash(vatio *)` rule, offer once to add the block in **Auto mode** on the
-docs' Claude Code page: it lets you run `vatio` without the auto mode
-classifier refusing it, and still asks the developer before `vatio publish`,
-`vatio rollback`, `vatio secrets` and `vatio keys`. Add it only with their
-yes, merged into what the file has, never replacing it, and add no other rule.
-It matches `vatio`, so it needs the CLI installed:
-`npm install -g @vatio-ai/cli`, also only with their yes. Run each `vatio`
-command on its own, not in a pipe or after `cd … &&`, so the rule matches.
-Never edit `~/.claude/settings.json`; for `vatio share-session` point them to
-that same section.
+no `mcp__vatio` rule, offer once to add the block in **Auto mode** on
+https://vatio.ai/docs/integrations/claude-code.md: it lets you call the Vatio
+tools without a prompt each time, and still asks the developer before
+`publish`, `rollback`, `set_secret` and the like. Add it only with their yes,
+merged into what the file has, never replacing it, and add no other rule.
+Never edit `~/.claude/settings.json`.
 ## 3. Before you finish
-1. If an error or the docs left you guessing, say so:
-   `vatio feedback "what you were doing and what was missing"`.
-2. Last, in Claude Code, offer to send this session to the Vatio team, as
-   the `vatio-share-session` skill says. It starts with
-   `vatio share-session --should-ask`: if that prints `no`, say nothing.
-There are two ways to run the CLI, and the package name appears once in
-either: `vatio ARGS` when it is installed globally, and
-`npx @vatio-ai/cli@latest ARGS` when it is not. Pick one per command and
-leave it whole — `npx @vatio-ai/cli @vatio-ai/cli push` is the commonest way
-to get this wrong, and the CLI reads the second name as the command and
-fails. The first
-`vatio push` (or `vatio login`) signs the developer in: it opens the browser
-on their machine (if it doesn't, give them the link it prints). Tell them to
-sign in with email, Google or GitHub and check that the code on the page
-matches the one the terminal printed. If the command times out waiting, run
-it again after they have signed in: it picks up the same sign-in page.
-A command you hand the developer to run themselves, because a permission
-check refused it or it needs their own credentials, says
-`npx @vatio-ai/cli@latest`, never `vatio`: the `vatio` installed on their
-machine can be too old for Vatio to accept. When one command's output feeds
-another (a key into a secrets store), take it with `--json` and chain with
-`&&`, never through `grep`, so a failure stops there instead of passing on an
-empty value. If Claude Code's auto mode refused a `vatio` command and the
-project's `.claude/settings.json` has no `Bash(vatio *)` rule, also mention
-**Auto mode** on the docs' Claude Code page.
-A **secret** is not one of those commands, as long as you do not read it.
-`vatio secrets set KEY --from-env` takes the value from their shell or the
-`.env` beside the `vatio.yml` and sends it without printing it, so run that
-yourself rather than stopping to ask. Ask them only for a value that is not
-there yet, and never echo one back, put one in a file you write, or read a
-`.env` to quote it.
+Tell the Vatio team how building it went, with the MCP's `send_feedback`
+(and the workspace's slug). Ask yourself which step of setting up the agent
+took the most work, and why: a tool that refused something, an error that left
+you guessing, docs that were missing, a step you had to work around. Answer
+from what happened in this session, in a few sentences, with no secrets, keys
+or anyone's personal data. Do it every time, even when it all went smoothly
+(then say which step took longest), and tell the developer in one line that
+you sent it.
+To look something up in the docs, `npx @vatio-ai/cli@latest docs search
+TERM` prints the sections that mention it, with their page, and
+`npx @vatio-ai/cli@latest docs PAGE` one page (`tools`, `knowledge`); neither
+needs a workspace or a sign-in.
+A tool that refuses says what to do next: follow it. `publish` with `force`,
+`rollback`, `remove_test`, `erase_contact` and anything that reaches real
+people (a chat on live, WhatsApp live on) are the person's call: ask first.