@workser/cli 0.6.14 → 0.6.15

package/dist/index.js

@@ -3663,6 +3663,137 @@ var import_picocolors2 = __toESM(require_picocolors(), 1);
 
 // src/help-content.ts
 var HELP_TOPICS = [
+  {
+    topic: "agent-cloud",
+    title: "Ship an agent inside the app",
+    summary: "Create an AI agent that runs on Workser and can be called from this project's apps.",
+    commands: ["agent-cloud"],
+    source: "skills/workser/reference/agent-cloud.md",
+    body: `# Ship an agent inside the app
+
+\`workser agent-cloud\` creates an AI agent that runs on **Workser's**
+infrastructure, keeps its own memory and tools, and can be called from the web,
+mobile, API or Python apps in this project.
+
+**This is not \`workser agent\`.** That one hands a subtask to a coding agent on
+this machine \u2014 a teammate helping you build. This one is a thing the project
+*ships*: it works for the user after you are gone.
+
+\`\`\`
+workser agent-cloud list
+workser agent-cloud create "Order desk" --instructions "..."
+workser agent-cloud show <agentId>
+workser agent-cloud run <agentId> "<what to do>"
+workser agent-cloud runs <agentId>        # recent runs
+workser agent-cloud runs <runId>          # one run, with what it cost
+\`\`\`
+
+Every call is scoped to the project this folder belongs to.
+
+## Creating one is not finishing one
+
+An agent created with a name and a sentence knows nothing about the business.
+Teaching it is the actual work, and it is all here:
+
+\`\`\`
+workser agent-cloud set <id> system_prompt="..." handle="orderdesk"
+workser agent-cloud add <id> skill name="Refunds" instructions_md="..."
+workser agent-cloud add <id> knowledge name="Price list" content_text="..."
+workser agent-cloud add <id> tool display_name="Send email" provider="gmail" \\
+                             provider_tool_id="GMAIL_SEND_EMAIL"
+workser agent-cloud add <id> secret key="STRIPE_KEY" value="..."
+workser agent-cloud add <id> subagent subagent_id=<otherId> name="researcher"
+workser agent-cloud get <id> skill          # what it has
+workser agent-cloud remove <id> skill <itemId>
+\`\`\`
+
+\`add\` takes \`key=value\` pairs and REFUSES a field it does not know, rather than
+sending it. That matters: the API silently drops unknown fields, so a typo
+would otherwise be accepted, dropped, and reported as success \u2014 leaving an
+agent that had been told nothing.
+
+## Nothing takes effect until you publish
+
+**This is the step to not forget.** The runtime resolves the PUBLISHED version
+of an agent and never the draft, so every \`set\` and \`add\` above is inert until:
+
+\`\`\`
+workser agent-cloud publish <id> --note "taught it refunds"
+\`\`\`
+
+Before publishing, try the setup without putting it live:
+
+\`\`\`
+workser agent-cloud try <id> "a customer wants a refund on order 1042"
+\`\`\`
+
+A \`try\` runs the draft, costs the same as a real run, and changes nothing that
+customers can reach.
+
+## Choosing how it thinks and what it runs on
+
+\`\`\`
+workser agent-cloud models            # cheapest first, on Workser credit
+workser agent-cloud models --all      # includes ones needing your own key
+workser agent-cloud set <id> default_provider=openrouter default_model=...
+
+workser agent-cloud machines          # video, data analysis, design, ...
+\`\`\`
+
+A model marked "needs your own key" will make \`publish\` FAIL unless a matching
+secret is stored first. Add the key with \`add <id> secret\` before setting it.
+
+## When to reach for this
+
+When the user describes a job that **keeps happening** and needs judgement:
+"check every order for stock and email me the problems", "read the LINE
+messages and file them", "reconcile these invoices". That is an agent.
+
+A one-off transformation is not an agent \u2014 write the code. A fixed sequence of
+steps with no judgement in it is not an agent either \u2014 that is \`workser
+workflow\`.
+
+## Calling it from the app you are building
+
+Do NOT shell out to the CLI from app code. Use the SDK, which streams:
+
+\`\`\`ts
+import { workser } from '@workser/app';
+
+const run = await workser.agents.run(agentId, { message }, {
+  referenceUserId: user.id,   // who it is acting for
+});
+
+for await (const event of workser.agents.stream(run.id)) {
+  // event.type, event.data \u2014 forward these to the browser
+}
+\`\`\`
+
+\`stream()\` reconnects itself through dropped connections, so the person
+watching sees the agent think. See the \`workser-sdk\` skill, \`reference/agents.md\`.
+
+## Things that will bite you
+
+1. **A run costs money by the minute.** It is metered \u2014 runtime, workspace, and
+   a per-run fee \u2014 so a loop that starts agents is a loop that spends. Cancel
+   what you abandon: \`workser agent-cloud runs <runId>\` shows the cost.
+
+2. **Instructions are the product.** The agent does what its instructions say,
+   in the user's own words. Write them the way you would brief a new colleague:
+   what to do, what to leave alone, when to ask. Vague instructions are the
+   single biggest cause of an agent that "doesn't work".
+
+3. **Free plans cannot run agents at all**, and a trial has a small allowance.
+   A \`402\` with \`spend_limit_reached\` is not a bug \u2014 tell the user what it says
+   and point them at their plan.
+
+4. **Say who it is for.** An agent acting for one of the app's customers needs
+   \`referenceUserId\`, or its memory and audit trail belong to nobody.
+
+5. **Do not invent an agent the user did not ask for.** Creating one is cheap;
+   an agent nobody wanted, quietly costing money per run, is not.
+`
+  },
   {
     topic: "analysis",
     title: "Analysis \u2014 running Python on this project's data",
@@ -4071,84 +4202,6 @@ Two things worth knowing:
 
 An app that has never been published has no address, so there is nothing to
 check. That is reported as a note, not as a pass.
-`
-  },
-  {
-    topic: "cloud-agents",
-    title: "Ship an agent inside the app",
-    summary: "Create an AI agent that runs on Workser and can be called from this project's apps.",
-    commands: ["cloud-agent"],
-    source: "skills/workser/reference/cloud-agents.md",
-    body: `# Ship an agent inside the app
-
-\`workser cloud-agent\` creates an AI agent that runs on **Workser's**
-infrastructure, keeps its own memory and tools, and can be called from the web,
-mobile, API or Python apps in this project.
-
-**This is not \`workser agent\`.** That one hands a subtask to a coding agent on
-this machine \u2014 a teammate helping you build. This one is a thing the project
-*ships*: it works for the user after you are gone.
-
-\`\`\`
-workser cloud-agent list
-workser cloud-agent create "Order desk" --instructions "..."
-workser cloud-agent show <agentId>
-workser cloud-agent run <agentId> "<what to do>"
-workser cloud-agent runs <agentId>        # recent runs
-workser cloud-agent runs <runId>          # one run, with what it cost
-\`\`\`
-
-Every call is scoped to the project this folder belongs to.
-
-## When to reach for this
-
-When the user describes a job that **keeps happening** and needs judgement:
-"check every order for stock and email me the problems", "read the LINE
-messages and file them", "reconcile these invoices". That is an agent.
-
-A one-off transformation is not an agent \u2014 write the code. A fixed sequence of
-steps with no judgement in it is not an agent either \u2014 that is \`workser
-workflow\`.
-
-## Calling it from the app you are building
-
-Do NOT shell out to the CLI from app code. Use the SDK, which streams:
-
-\`\`\`ts
-import { workser } from '@workser/app';
-
-const run = await workser.agents.run(agentId, { message }, {
-  referenceUserId: user.id,   // who it is acting for
-});
-
-for await (const event of workser.agents.stream(run.id)) {
-  // event.type, event.data \u2014 forward these to the browser
-}
-\`\`\`
-
-\`stream()\` reconnects itself through dropped connections, so the person
-watching sees the agent think. See the \`workser-sdk\` skill, \`reference/agents.md\`.
-
-## Things that will bite you
-
-1. **A run costs money by the minute.** It is metered \u2014 runtime, workspace, and
-   a per-run fee \u2014 so a loop that starts agents is a loop that spends. Cancel
-   what you abandon: \`workser cloud-agent runs <runId>\` shows the cost.
-
-2. **Instructions are the product.** The agent does what its instructions say,
-   in the user's own words. Write them the way you would brief a new colleague:
-   what to do, what to leave alone, when to ask. Vague instructions are the
-   single biggest cause of an agent that "doesn't work".
-
-3. **Free plans cannot run agents at all**, and a trial has a small allowance.
-   A \`402\` with \`spend_limit_reached\` is not a bug \u2014 tell the user what it says
-   and point them at their plan.
-
-4. **Say who it is for.** An agent acting for one of the app's customers needs
-   \`referenceUserId\`, or its memory and audit trail belong to nobody.
-
-5. **Do not invent an agent the user did not ask for.** Creating one is cheap;
-   an agent nobody wanted, quietly costing money per run, is not.
 `
   },
   {
@@ -7537,21 +7590,21 @@ function formatRole(r) {
   return `${label}  ${agent}  ${enabled}  ${ready}${tail}`;
 }
 
-// src/commands/cloud-agent.ts
+// src/commands/agent-cloud.ts
 var import_picocolors17 = __toESM(require_picocolors(), 1);
-function registerCloudAgent(program3) {
-  const cloud = program3.command("cloud-agent").description(
+function registerAgentCloud(program3) {
+  const cloud = program3.command("agent-cloud").description(
     "Agents that run in the cloud and can be called from this project's apps (not the local coding agents \u2014 that's `workser agent`)"
   );
   cloud.command("list").description("List this project's cloud agents").action(
     action(async ({ ctx }) => {
-      const res = await api(ctx, "/v1/cloud-agents");
+      const res = await api(ctx, "/v1/agent-cloud");
       const agents = res?.agents ?? res ?? [];
       ok(res, () => {
         if (!agents.length) {
           line(import_picocolors17.default.dim("No cloud agents yet."));
           line(
-            import_picocolors17.default.dim("Create one: ") + import_picocolors17.default.bold('workser cloud-agent create "Order desk" --instructions "..."')
+            import_picocolors17.default.dim("Create one: ") + import_picocolors17.default.bold('workser agent-cloud create "Order desk" --instructions "..."')
           );
           return;
         }
@@ -7569,7 +7622,7 @@ function registerCloudAgent(program3) {
     "The agent's standing instructions \u2014 what it should always do"
   ).action(
     action(async ({ ctx, args, opts }) => {
-      const res = await api(ctx, "/v1/cloud-agents", {
+      const res = await api(ctx, "/v1/agent-cloud", {
         method: "POST",
         body: {
           name: args[0],
@@ -7582,14 +7635,14 @@ function registerCloudAgent(program3) {
         if (res?.id) line(import_picocolors17.default.dim(res.id));
         line("");
         line(
-          import_picocolors17.default.dim("Give it work: ") + import_picocolors17.default.bold(`workser cloud-agent run ${res?.id ?? "<id>"} "..."`)
+          import_picocolors17.default.dim("Give it work: ") + import_picocolors17.default.bold(`workser agent-cloud run ${res?.id ?? "<id>"} "..."`)
         );
       });
     })
   );
   cloud.command("show <agentId>").description("One cloud agent, with its configuration").action(
     action(async ({ ctx, args }) => {
-      const res = await api(ctx, `/v1/cloud-agents/${encodeURIComponent(args[0])}`);
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}`);
       ok(res, () => {
         line(import_picocolors17.default.bold(res?.name ?? args[0]));
         if (res?.description) line(import_picocolors17.default.dim(res.description));
@@ -7605,13 +7658,13 @@ function registerCloudAgent(program3) {
     action(async ({ ctx, args }) => {
       const res = await api(
         ctx,
-        `/v1/cloud-agents/${encodeURIComponent(args[0])}/runs`,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/runs`,
         { method: "POST", body: { input: { message: args[1] } } }
       );
       ok(res, () => {
         line(import_picocolors17.default.green("Started run ") + import_picocolors17.default.bold(res?.id ?? ""));
         line(
-          import_picocolors17.default.dim("Follow it: ") + import_picocolors17.default.bold(`workser cloud-agent runs ${res?.id ?? "<runId>"}`)
+          import_picocolors17.default.dim("Follow it: ") + import_picocolors17.default.bold(`workser agent-cloud runs ${res?.id ?? "<runId>"}`)
         );
       });
     })
@@ -7626,7 +7679,7 @@ function registerCloudAgent(program3) {
       try {
         const run = await api(
           ctx,
-          `/v1/cloud-agents/runs/${encodeURIComponent(id)}`
+          `/v1/agent-cloud/runs/${encodeURIComponent(id)}`
         );
         ok(run, () => printRun(run));
         return;
@@ -7634,7 +7687,7 @@ function registerCloudAgent(program3) {
       }
       const res = await api(
         ctx,
-        `/v1/cloud-agents/${encodeURIComponent(id)}/runs`,
+        `/v1/agent-cloud/${encodeURIComponent(id)}/runs`,
         { query: { limit: opts.limit } }
       );
       const runs = res?.runs ?? res ?? [];
@@ -7647,6 +7700,202 @@ function registerCloudAgent(program3) {
       });
     })
   );
+  const COLLECTIONS = {
+    skill: {
+      path: "skills",
+      key: "skills",
+      label: "skill",
+      fields: ["name", "description", "instructions_md"],
+      required: ["name"]
+    },
+    tool: {
+      path: "tools",
+      key: "tools",
+      label: "action",
+      fields: ["display_name", "provider", "provider_tool_id", "description"],
+      required: ["display_name"]
+    },
+    mcp: {
+      path: "mcp-servers",
+      key: "servers",
+      label: "MCP server",
+      fields: ["name", "url"],
+      required: ["name", "url"]
+    },
+    knowledge: {
+      path: "resources",
+      key: "resources",
+      label: "reference material",
+      fields: ["name", "content_text"],
+      required: ["name"]
+    },
+    secret: {
+      path: "secrets",
+      key: "secrets",
+      label: "stored key",
+      fields: ["key", "value", "description"],
+      required: ["key", "value"]
+    },
+    subagent: {
+      path: "subagents",
+      key: "subagents",
+      label: "team member",
+      fields: ["subagent_id", "name", "description"],
+      required: ["subagent_id", "name"]
+    },
+    workflow: {
+      path: "workflows",
+      key: "workflows",
+      label: "workflow",
+      fields: ["workflow_id", "description"],
+      required: ["workflow_id"]
+    }
+  };
+  const kinds = Object.keys(COLLECTIONS).join(" | ");
+  cloud.command("get <agentId> <kind>").description(`What an agent has been given (${kinds})`).action(
+    action(async ({ ctx, args }) => {
+      const spec = COLLECTIONS[args[1]];
+      if (!spec) throw new Error(`Unknown kind "${args[1]}". One of: ${kinds}`);
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}/${spec.path}`);
+      const items = res?.[spec.key] ?? [];
+      ok(res, () => {
+        if (!items.length) {
+          line(import_picocolors17.default.dim(`No ${spec.label} yet.`));
+          return;
+        }
+        for (const i of items) {
+          const title = i.name ?? i.display_name ?? i.key ?? i.workflow_id ?? i.id;
+          line(`${import_picocolors17.default.bold(title)}  ${import_picocolors17.default.dim(i.id)}`);
+          if (i.description) line("  " + import_picocolors17.default.dim(i.description));
+          if (i.is_enabled === false) line("  " + import_picocolors17.default.yellow("turned off"));
+        }
+      });
+    })
+  );
+  cloud.command("add <agentId> <kind> [pairs...]").description(
+    `Give an agent something (${kinds}). Pairs are key=value, e.g. name="Refunds"`
+  ).action(
+    action(async ({ ctx, args }) => {
+      const spec = COLLECTIONS[args[1]];
+      if (!spec) throw new Error(`Unknown kind "${args[1]}". One of: ${kinds}`);
+      const body = parsePairs(args[2] ?? [], spec.fields);
+      const missing = spec.required.filter((f) => !body[f]);
+      if (missing.length) {
+        throw new Error(
+          `A ${spec.label} needs ${missing.join(" and ")}. Accepted: ${spec.fields.join(", ")}`
+        );
+      }
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}/${spec.path}`, {
+        method: "POST",
+        body
+      });
+      ok(res, () => {
+        line(import_picocolors17.default.green(`Added the ${spec.label}.`) + "  " + import_picocolors17.default.dim(res?.id ?? ""));
+        line(
+          import_picocolors17.default.dim("Not live yet \u2014 run ") + import_picocolors17.default.bold(`workser agent-cloud publish ${args[0]}`) + import_picocolors17.default.dim(" when the setup is ready.")
+        );
+      });
+    })
+  );
+  cloud.command("remove <agentId> <kind> <itemId>").description(`Take something away from an agent (${kinds})`).action(
+    action(async ({ ctx, args }) => {
+      const spec = COLLECTIONS[args[1]];
+      if (!spec) throw new Error(`Unknown kind "${args[1]}". One of: ${kinds}`);
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/${spec.path}/${encodeURIComponent(args[2])}`,
+        { method: "DELETE" }
+      );
+      ok(res, () => line(import_picocolors17.default.green(`Removed the ${spec.label}.`)));
+    })
+  );
+  cloud.command("set <agentId> [pairs...]").description(
+    "Change the brief or the model. Pairs: name, description, system_prompt, handle, default_provider, default_model"
+  ).action(
+    action(async ({ ctx, args }) => {
+      const body = parsePairs(args[1] ?? [], [
+        "name",
+        "description",
+        "system_prompt",
+        "handle",
+        "default_provider",
+        "default_model"
+      ]);
+      if (!Object.keys(body).length) {
+        throw new Error(
+          'Nothing to change. Example: workser agent-cloud set <id> system_prompt="Always check stock first"'
+        );
+      }
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}`, {
+        method: "PATCH",
+        body
+      });
+      ok(res, () => {
+        line(import_picocolors17.default.green("Saved."));
+        line(
+          import_picocolors17.default.dim("Not live yet \u2014 run ") + import_picocolors17.default.bold(`workser agent-cloud publish ${args[0]}`) + import_picocolors17.default.dim(".")
+        );
+      });
+    })
+  );
+  cloud.command("publish <agentId>").description("Put the current setup live \u2014 nothing takes effect until this runs").option("--note <text>", "What changed, for the version history").action(
+    action(async ({ ctx, args, opts }) => {
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}/publish`, {
+        method: "POST",
+        body: { changelog: opts.note }
+      });
+      ok(
+        res,
+        () => line(import_picocolors17.default.green(`Live${res?.version ? ` \u2014 version ${res.version}` : ""}.`))
+      );
+    })
+  );
+  cloud.command("try <agentId> <message>").description("Run the current setup WITHOUT publishing it").action(
+    action(async ({ ctx, args }) => {
+      const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}/test-runs`, {
+        method: "POST",
+        body: { input: { message: args[1] } }
+      });
+      ok(res, () => {
+        line(import_picocolors17.default.green("Trying it \u2014 nothing has gone live."));
+        if (res?.run_id) {
+          line(
+            import_picocolors17.default.dim("Watch it: ") + import_picocolors17.default.bold(`workser agent-cloud runs ${res.run_id}`)
+          );
+        }
+      });
+    })
+  );
+  cloud.command("machines").description("The pre-built machines an agent can run on").action(
+    action(async ({ ctx }) => {
+      const res = await api(ctx, "/v1/agent-cloud/catalog/machines");
+      ok(res, () => {
+        for (const m of res?.machines ?? []) {
+          line(`${import_picocolors17.default.bold(m.label)}  ${import_picocolors17.default.dim(m.alias)}`);
+          line("  " + import_picocolors17.default.dim(m.description));
+        }
+      });
+    })
+  );
+  cloud.command("models").description("Models this organisation can run an agent on, cheapest first").option("--all", "Include models that need your own provider key").action(
+    action(async ({ ctx, opts }) => {
+      const res = await api(ctx, "/v1/agent-cloud/catalog/models/live");
+      const models = (res?.models ?? []).filter(
+        (m) => opts.all || m.credit_tier === "PLATFORM_CREDITS"
+      );
+      ok(res, () => {
+        if (!models.length) {
+          warn("The live model list could not be read.");
+          return;
+        }
+        for (const m of models.slice(0, 40)) {
+          const price = typeof m.input_price_per_million_usd === "number" ? `$${m.input_price_per_million_usd.toFixed(2)}/M in` : "price unknown";
+          const byok = m.credit_tier === "PLATFORM_CREDITS" ? "" : import_picocolors17.default.yellow("  needs your own key");
+          line(`${import_picocolors17.default.bold(m.id)}  ${import_picocolors17.default.dim(price)}${byok}`);
+        }
+      });
+    })
+  );
 }
 function printRun(run, compact = false) {
   const status = String(run?.status ?? "").toLowerCase();
@@ -7682,6 +7931,22 @@ function formatDuration(ms) {
   const minutes = Math.floor(seconds / 60);
   return `${minutes}m ${seconds % 60}s`;
 }
+function parsePairs(pairs, allowed) {
+  const out = {};
+  for (const raw of pairs) {
+    const at = raw.indexOf("=");
+    if (at < 1) {
+      throw new Error(`"${raw}" is not a key=value pair.`);
+    }
+    const key = raw.slice(0, at).trim();
+    const value = raw.slice(at + 1);
+    if (!allowed.includes(key)) {
+      throw new Error(`"${key}" is not a field here. Accepted: ${allowed.join(", ")}`);
+    }
+    if (value) out[key] = value;
+  }
+  return out;
+}
 
 // src/commands/verify.ts
 var import_picocolors18 = __toESM(require_picocolors(), 1);
@@ -11489,7 +11754,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.14" : "0.0.0-dev"
+  version: true ? "0.6.15" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -11522,7 +11787,7 @@ registerDomain(program2);
 registerOpen(program2);
 registerDoctor(program2);
 registerAgent(program2);
-registerCloudAgent(program2);
+registerAgentCloud(program2);
 registerVerify(program2);
 registerApi(program2);
 registerAnalysis(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -30,7 +30,7 @@ load.
 | Build an automation, or use Gmail/Slack/Stripe/Sheets | `workflow …`, `app …` | `workser help automation` |
 | Generate an image | `image …` | `workser help images` |
 | Hand a subtask to another agent | `agent …` | `workser help roles` |
-| Ship an AI agent inside the user's app | `cloud-agent …` | `workser help cloud-agents` |
+| Ship an AI agent inside the user's app | `agent-cloud …` | `workser help agent-cloud` |
 | Recall across conversations; leave this task's team a fact | `memory …`, `workser note` | `workser help memory` |
 | Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
 | Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |

package/skills/workser/reference/{cloud-agents.md → agent-cloud.md}

@@ -1,13 +1,13 @@
 ---
-topic: cloud-agents
+topic: agent-cloud
 title: Ship an agent inside the app
 summary: Create an AI agent that runs on Workser and can be called from this project's apps.
-commands: [cloud-agent]
+commands: [agent-cloud]
 ---
 
 # Ship an agent inside the app
 
-`workser cloud-agent` creates an AI agent that runs on **Workser's**
+`workser agent-cloud` creates an AI agent that runs on **Workser's**
 infrastructure, keeps its own memory and tools, and can be called from the web,
 mobile, API or Python apps in this project.
 
@@ -16,16 +16,69 @@ this machine — a teammate helping you build. This one is a thing the project
 *ships*: it works for the user after you are gone.
 
 ```
-workser cloud-agent list
-workser cloud-agent create "Order desk" --instructions "..."
-workser cloud-agent show <agentId>
-workser cloud-agent run <agentId> "<what to do>"
-workser cloud-agent runs <agentId>        # recent runs
-workser cloud-agent runs <runId>          # one run, with what it cost
+workser agent-cloud list
+workser agent-cloud create "Order desk" --instructions "..."
+workser agent-cloud show <agentId>
+workser agent-cloud run <agentId> "<what to do>"
+workser agent-cloud runs <agentId>        # recent runs
+workser agent-cloud runs <runId>          # one run, with what it cost
 ```
 
 Every call is scoped to the project this folder belongs to.
 
+## Creating one is not finishing one
+
+An agent created with a name and a sentence knows nothing about the business.
+Teaching it is the actual work, and it is all here:
+
+```
+workser agent-cloud set <id> system_prompt="..." handle="orderdesk"
+workser agent-cloud add <id> skill name="Refunds" instructions_md="..."
+workser agent-cloud add <id> knowledge name="Price list" content_text="..."
+workser agent-cloud add <id> tool display_name="Send email" provider="gmail" \
+                             provider_tool_id="GMAIL_SEND_EMAIL"
+workser agent-cloud add <id> secret key="STRIPE_KEY" value="..."
+workser agent-cloud add <id> subagent subagent_id=<otherId> name="researcher"
+workser agent-cloud get <id> skill          # what it has
+workser agent-cloud remove <id> skill <itemId>
+```
+
+`add` takes `key=value` pairs and REFUSES a field it does not know, rather than
+sending it. That matters: the API silently drops unknown fields, so a typo
+would otherwise be accepted, dropped, and reported as success — leaving an
+agent that had been told nothing.
+
+## Nothing takes effect until you publish
+
+**This is the step to not forget.** The runtime resolves the PUBLISHED version
+of an agent and never the draft, so every `set` and `add` above is inert until:
+
+```
+workser agent-cloud publish <id> --note "taught it refunds"
+```
+
+Before publishing, try the setup without putting it live:
+
+```
+workser agent-cloud try <id> "a customer wants a refund on order 1042"
+```
+
+A `try` runs the draft, costs the same as a real run, and changes nothing that
+customers can reach.
+
+## Choosing how it thinks and what it runs on
+
+```
+workser agent-cloud models            # cheapest first, on Workser credit
+workser agent-cloud models --all      # includes ones needing your own key
+workser agent-cloud set <id> default_provider=openrouter default_model=...
+
+workser agent-cloud machines          # video, data analysis, design, ...
+```
+
+A model marked "needs your own key" will make `publish` FAIL unless a matching
+secret is stored first. Add the key with `add <id> secret` before setting it.
+
 ## When to reach for this
 
 When the user describes a job that **keeps happening** and needs judgement:
@@ -59,7 +112,7 @@ watching sees the agent think. See the `workser-sdk` skill, `reference/agents.md
 
 1. **A run costs money by the minute.** It is metered — runtime, workspace, and
    a per-run fee — so a loop that starts agents is a loop that spends. Cancel
-   what you abandon: `workser cloud-agent runs <runId>` shows the cost.
+   what you abandon: `workser agent-cloud runs <runId>` shows the cost.
 
 2. **Instructions are the product.** The agent does what its instructions say,
    in the user's own words. Write them the way you would brief a new colleague: