@workser/cli 0.6.6 → 0.6.8

package/AGENTS.md

@@ -71,10 +71,11 @@ workser workflow list | create <name> [--body <json>] | get <id>
 workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <json>]
 workser workflow runs <id>                    # past executions of a workflow
 workser workflow nodes [query]                # search the node-type catalog
-workser app list [--toolkit <slug>]           # connectable + connected third-party apps
-workser app connect <toolkit> | disconnect <connectionId>
-workser app tools <toolkit>                   # a connected app's callable actions
-workser app run <toolSlug> [--body <json>]    # execute one action (e.g. GOOGLESHEETS_APPEND_ROW)
+workser connection list [--toolkit <slug>]           # connectable + connected third-party apps
+workser connection search "<query>" [--toolkit <slug>] [--limit N]  # full-text search across every toolkit's actions
+workser connection connect <toolkit> | disconnect <connectionId>
+workser connection tools <toolkit>                   # browse one connected toolkit's callable actions
+workser connection run <toolSlug> [--body <json>]    # execute one action (e.g. GOOGLESHEETS_APPEND_ROW)
 
 workser tool list                             # computer-use tools available to you now
 workser tool run <name> [--body <json>]       # filesystem/shell/screenshot/input/clipboard/browser
@@ -87,8 +88,27 @@ workser artifact add <path> [--kind <k>] [-d <text>]  # record a finished delive
 workser artifact add --url <url> --kind app          # record a deployed app
 workser artifact run                                 # which task you're attached to
 
+workser search "<query>" [-n <maxResults>]           # Google-grounded web search
+
+workser image generate "<prompt>" [-r <url>...] [-o <path>]  # generate an image, get a public URL
+workser image understand "<query>" [--url <u>|--file <p>] [-t <task>]  # describe/caption/answer questions about an image
+workser video understand "<query>" [--url <u>|--file <p>] [-t <task>]  # summarize/describe a video (URL also accepts YouTube)
+workser audio understand "<query>" [--url <u>|--file <p>] [-t <task>]  # transcribe/describe audio (URL also accepts YouTube)
+# image/video/audio understand: the fallback for a text-only model, or media you have no other
+# way to see/hear. --url is fetched server-side (no size ceiling); --file reads a small local
+# file and sends it inline — for anything bigger, `workser storage upload` it and pass --url.
+
 workser ask "<question>" [--type <t>] [--option <o>] # ask the user, WAIT for the answer
 
+# Tasks and subtasks (the plan shown in Orbit)
+workser task show [id]                              # inspect the task and its current plan
+workser task subtask list [taskId]                  # list the task's subtasks
+workser task subtask add "<title>" --role <role>    # add one proposed subtask
+workser task subtask update <id> --role <role>      # fix its teammate after creation
+workser task subtask update <id> --title "…" --note "…" --scope <paths...>
+workser task subtask remove <id>                    # remove it before work starts
+workser task start [id]                             # starts only an already-approved plan
+
 # owner-only (will return owner_only / exit 6 — ask the user to do these in Orbit):
 #   project create, project use, env rm, domain set
 ```
@@ -108,12 +128,12 @@ workser doc create "<title>" --markdown <text> | doc update <id> --markdown <tex
 already doing and what this project chose on purpose, so you don't re-file work or
 quietly reverse a decision.
 
-**A plan with phases goes on the Board before you build it.** The moment you split a
-task into more than one phase: one `board create` card per phase (only the one you're
-doing goes to `in-progress`), the plan itself as one `doc create --markdown` — with
-**no `--work-item`**, because a linked doc is shown on its card and hidden from the
-Docs panel — and a `decision create` if the plan settled a real tradeoff. A plan that
-lives only in your reply is gone as soon as the conversation scrolls.
+**A plan with phases goes on this task's Subtasks list, not the Board.** Use one
+`task subtask add` per phase. If you spot a bad title, role, note, or file scope after
+creation, correct that existing row with `task subtask update <id>`; do not say it is
+locked, create a replacement, or duplicate the plan. Write the plan narrative once
+as `doc create --markdown` with no `--work-item`, and record a real tradeoff with
+`decision create`.
 
 **Keep it true as you work.** `board move <id> in-progress` when you pick it up,
 `in-review` when it's ready to look at, `board close <id>` when it's done and
@@ -215,11 +235,14 @@ done: `workser workflow create` builds an event-driven, multi-step automation (t
 same engine Workser's own web Workflow tab uses) — nodes, connections, and triggers go
 in `--body` as JSON; browse `workser workflow nodes` first to see what's available.
 Before an automation can use a third-party app (Gmail, Slack, Stripe, Google Sheets,
-...), the user connects it once via `workser app connect <toolkit>` (this opens an
-OAuth link — ask the user to complete it, then continue); after that, `workser app
-run <toolSlug> --body '{"...":...}'` calls any of its actions directly, and a workflow
-node can call the same toolkit. Use `workser app list` to see what's already
-connected before assuming you need to ask the user to connect something new.
+...), the user connects it once via `workser connection connect <toolkit>` (this opens
+an OAuth link — ask the user to complete it, then continue); after that, `workser
+connection run <toolSlug> --body '{"...":...}'` calls any of its actions directly, and
+a workflow node can call the same toolkit. Use `workser connection list` to see what's
+already connected before assuming you need to ask the user to connect something new.
+Don't know the exact action slug? `workser connection search "<what you want to do>"`
+searches across every toolkit's actions at once — cheaper than browsing toolkit by
+toolkit with `workser connection tools <toolkit>`.
 
 ## Delegate to roles
 The user can configure **roles** — named specialists each backed by a local CLI agent

package/dist/index.js

@@ -3794,7 +3794,7 @@ and the spec is the difference.
     topic: "automation",
     title: "Workflows & connected apps",
     summary: "Build automations that outlive the run; use Gmail, Slack, Stripe, Sheets.",
-    commands: ["workflow", "app"],
+    commands: ["workflow", "connection"],
     source: "skills/workser/reference/automation.md",
     body: `# Workflows & connected apps
 
@@ -3807,10 +3807,11 @@ workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <js
 workser workflow runs <id>          # past executions of a workflow
 workser workflow nodes [query]      # search the node-type catalog
 
-workser app list [--toolkit <slug>] # connectable + connected third-party apps
-workser app connect <toolkit> | disconnect <connectionId>
-workser app tools <toolkit>         # a connected app's callable actions
-workser app run <toolSlug> [--body <json>]  # execute one action
+workser connection list [--toolkit <slug>]  # connectable + connected third-party apps
+workser connection search "<query>" [--toolkit <slug>] [--limit N]  # find an action across every toolkit
+workser connection connect <toolkit> | disconnect <connectionId>
+workser connection tools <toolkit>          # browse one connected toolkit's actions
+workser connection run <toolSlug> [--body <json>]  # execute one action
 \`\`\`
 
 ## Building a workflow
@@ -3826,12 +3827,13 @@ Created workflows start inactive: \`workser workflow activate <id>\` when it's r
 
 ## Using a connected app
 
-1. \`workser app list\` \u2014 check what's already connected before asking for anything.
-2. If it isn't: \`workser app connect <toolkit>\` returns an OAuth link. The **user**
+1. \`workser connection list\` \u2014 check what's already connected before asking for anything.
+2. If it isn't: \`workser connection connect <toolkit>\` returns an OAuth link. The **user**
    must open it; you cannot complete OAuth on their behalf. Wait, then continue.
-3. \`workser app tools <toolkit>\` \u2014 read the argument schema rather than guessing
-   field names.
-4. \`workser app run <toolSlug> --body '{"\u2026":\u2026}'\` \u2014 e.g. \`GOOGLESHEETS_APPEND_ROW\`,
+3. Don't know the exact action? \`workser connection search "<query>"\` finds it across
+   every toolkit; \`workser connection tools <toolkit>\` browses one toolkit you already
+   know. Either way, read the argument schema rather than guessing field names.
+4. \`workser connection run <toolSlug> --body '{"\u2026":\u2026}'\` \u2014 e.g. \`GOOGLESHEETS_APPEND_ROW\`,
    \`GMAIL_SEND_EMAIL\`.
 
 **A \`run\` is a real side effect in someone's real account.** Sending an email or
@@ -4566,11 +4568,11 @@ up front \u2014 most of the apps a goal will touch don't exist when it's propose
   },
   {
     topic: "images",
-    title: "Image generation",
-    summary: "Generate images from a prompt, optionally conditioned on existing images.",
-    commands: ["image"],
+    title: "Image generation & media understanding",
+    summary: "Generate images from a prompt; describe/transcribe an image, video, or audio clip you can't natively see or hear.",
+    commands: ["image", "video", "audio"],
     source: "skills/workser/reference/images.md",
-    body: `# Image generation
+    body: `# Image generation & media understanding
 
 \`\`\`
 workser image generate "<prompt>"            # alias: workser image gen
@@ -4586,7 +4588,7 @@ workser image generate "flat illustration of a farm delivery van, brand colors"
 workser image gen "same van, from the side" -r https://\u2026 -o ./public/van.png --json
 \`\`\`
 
-## Notes that matter
+## Notes that matter (generation)
 
 - **Reference images are image-to-image conditioning**, not attachments. Up to 4;
   anything beyond that is dropped.
@@ -4598,6 +4600,42 @@ workser image gen "same van, from the side" -r https://\u2026 -o ./public/van.pn
   exist only as URLs.
 - **Placeholder art is not a deliverable.** Generating a hero image to unblock a
   layout is fine; shipping it as the user's brand asset without asking is not.
+
+## Understanding media you can't natively see or hear
+
+The fallback for a text-only model, or media you have no other way to reach: describe
+an image, summarize/transcribe a video, transcribe/describe audio. Runs server-side
+(Gemini) \u2014 you never need a model key.
+
+\`\`\`
+workser image understand "<query>" [--url <u> | --file <p>] [-t <task>]
+workser video understand "<query>" [--url <u> | --file <p>] [-t <task>]
+workser audio understand "<query>" [--url <u> | --file <p>] [-t <task>]
+\`\`\`
+
+\`\`\`bash
+workser image understand "what's wrong with this layout?" --url https://\u2026/screenshot.png --json
+workser video understand "what happens at the end?" --url https://youtu.be/\u2026 -t timestamp_analysis --json
+workser audio understand "transcribe this" --file ./voicemail.m4a -t transcribe --json
+\`\`\`
+
+## Notes that matter (understanding)
+
+- **\`--url\` vs \`--file\`**: \`--url\` is fetched server-side with no size ceiling \u2014 the
+  right choice for anything already hosted (a project's own storage bucket, a public
+  link, a YouTube URL for video/audio). \`--file\` is read and sent inline by the CLI
+  itself, so it's bounded by the daemon's own request-size limit \u2014 for a small local
+  file only (a screenshot, a short voice memo). Something bigger: \`workser storage
+  upload\` it first, then pass the returned URL with \`--url\`.
+- **\`-t/--task\` shapes the answer, it doesn't gate what you can ask** \u2014 \`general\` (the
+  default) takes any free-form \`<query>\`. The other values just bias the prompt
+  toward a specific shape: \`caption\`/\`visual_qa\`/\`object_detection\`/\`segmentation\`
+  for images; \`summarize\`/\`describe\`/\`visual_qa\`/\`timestamp_analysis\` for video;
+  \`transcribe\`/\`describe\`/\`audio_qa\`/\`speaker_diarization\`/\`emotion_detection\` for
+  audio.
+- **This is billed to the project's organization**, same as image generation \u2014 it's
+  a real provider call, not free introspection. Don't loop it over every file in a
+  folder "just in case"; use it when you actually need to know what's in one.
 `
   },
   {
@@ -7498,11 +7536,11 @@ function registerWorkflow(program3) {
   );
 }
 
-// src/commands/app.ts
+// src/commands/connection.ts
 var import_picocolors20 = __toESM(require_picocolors(), 1);
-function registerApp(program3) {
-  const appCmd = program3.command("app").description("Connect and use third-party app integrations (Gmail, Slack, Stripe, ...)");
-  appCmd.command("list").description("List connectable toolkits and this project's existing connections").option("--toolkit <slug>", "filter connections to one toolkit").action(
+function registerConnection(program3) {
+  const connection = program3.command("connection").description("Connect and use third-party app connections (Gmail, Slack, Stripe, ...)");
+  connection.command("list").description("List connectable toolkits and this project's existing connections").option("--toolkit <slug>", "filter connections to one toolkit").action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
       const [catalog, connections] = await Promise.all([
@@ -7518,7 +7556,21 @@ function registerApp(program3) {
       });
     })
   );
-  appCmd.command("connect <toolkit>").description("Start OAuth to connect a toolkit").option("--reference-user-id <id>", "connect on behalf of one of the app's own end-users").option("--redirect-url <url>", "where to send the user after OAuth completes").action(
+  connection.command("search <query>").description('Full-text search for actions across every toolkit (or one, with --toolkit) \u2014 e.g. "send email"').option("--toolkit <slug>", "narrow the search to one toolkit").option("--limit <n>", "max results").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const items = await api(ctx, `/v1/projects/${projectId}/integrations/search`, {
+        query: { q: args[0], toolkit: opts.toolkit, limit: opts.limit }
+      });
+      ok(items, () => {
+        if (!items?.length) return line(import_picocolors20.default.dim("No matching actions."));
+        for (const t of items) {
+          line(`${t.slug}  ${import_picocolors20.default.dim(`[${t.toolkit}]`)}  ${t.description ?? ""}`);
+        }
+      });
+    })
+  );
+  connection.command("connect <toolkit>").description("Start OAuth to connect a toolkit").option("--reference-user-id <id>", "connect on behalf of one of the app's own end-users").option("--redirect-url <url>", "where to send the user after OAuth completes").action(
     action(async ({ ctx, args, opts }) => {
       const projectId = requireProject(ctx);
       const res = await api(ctx, `/v1/projects/${projectId}/integrations/connect`, {
@@ -7534,7 +7586,7 @@ function registerApp(program3) {
       );
     })
   );
-  appCmd.command("disconnect <connectionId>").description("Disconnect a connection").action(
+  connection.command("disconnect <connectionId>").description("Disconnect a connection").action(
     action(async ({ ctx, args }) => {
       const projectId = requireProject(ctx);
       const res = await api(ctx, `/v1/projects/${projectId}/integrations/${args[0]}`, {
@@ -7543,7 +7595,7 @@ function registerApp(program3) {
       ok(res, () => line("Disconnected."));
     })
   );
-  appCmd.command("tools <toolkit>").description("List a connected toolkit's callable tools + their arguments").action(
+  connection.command("tools <toolkit>").description("List a connected toolkit's callable tools + their arguments").action(
     action(async ({ ctx, args }) => {
       const projectId = requireProject(ctx);
       const items = await api(ctx, `/v1/projects/${projectId}/integrations/${args[0]}/tools`);
@@ -7553,7 +7605,7 @@ function registerApp(program3) {
       });
     })
   );
-  appCmd.command("run <toolSlug>").description("Execute one tool action (e.g. GOOGLESHEETS_APPEND_ROW)").option("--body <args>", "the tool's arguments as a JSON string", "{}").option("--reference-user-id <id>", "run on behalf of one of the app's own end-users").action(
+  connection.command("run <toolSlug>").description("Execute one tool action (e.g. GOOGLESHEETS_APPEND_ROW)").option("--body <args>", "the tool's arguments as a JSON string", "{}").option("--reference-user-id <id>", "run on behalf of one of the app's own end-users").action(
     action(async ({ ctx, args, opts }) => {
       const projectId = requireProject(ctx);
       const res = await api(ctx, `/v1/projects/${projectId}/integrations/${args[0]}/execute`, {
@@ -7917,6 +7969,56 @@ function printRun(run) {
 // src/commands/image.ts
 import { writeFile as writeFile4, mkdir } from "fs/promises";
 import { dirname as dirname3, resolve as resolve4 } from "path";
+
+// src/media-source.ts
+import { readFile as readFile4 } from "fs/promises";
+import { extname } from "path";
+var EXT_MIME = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".heic": "image/heic",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+  ".avi": "video/x-msvideo",
+  ".mp3": "audio/mp3",
+  ".wav": "audio/wav",
+  ".m4a": "audio/mp4",
+  ".ogg": "audio/ogg",
+  ".flac": "audio/flac",
+  ".aac": "audio/aac"
+};
+async function resolveMediaSource(opts) {
+  if (opts.url && opts.file) {
+    throw new WorkserError("Pass --url or --file, not both.", {
+      code: "bad_request"
+    });
+  }
+  if (opts.url) {
+    return { type: "url", url: opts.url };
+  }
+  if (opts.file) {
+    let bytes;
+    try {
+      bytes = await readFile4(opts.file);
+    } catch (e) {
+      throw new WorkserError(
+        `Could not read ${opts.file}: ${e instanceof Error ? e.message : String(e)}`,
+        { code: "bad_request" }
+      );
+    }
+    const mimeType = EXT_MIME[extname(opts.file).toLowerCase()] ?? "application/octet-stream";
+    return { type: "base64", data: bytes.toString("base64"), mimeType };
+  }
+  throw new WorkserError("Pass --url <url> or --file <path> for the media to look at.", {
+    code: "bad_request"
+  });
+}
+
+// src/commands/image.ts
 function registerImage(program3) {
   const image = program3.command("image").description("Generate images from a text prompt");
   image.command("generate <prompt>").alias("gen").description("Generate an image and return its public URL").option(
@@ -7969,6 +8071,23 @@ function registerImage(program3) {
       });
     })
   );
+  image.command("understand <query>").description(
+    "Describe/caption/answer questions about an image \u2014 the fallback for a text-only model or an image you have no other way to see"
+  ).option("-u, --url <url>", "the image's URL (fetched server-side)").option("-f, --file <path>", "a local image file (read + sent inline; small files only)").option(
+    "-t, --task <task>",
+    "caption | visual_qa | object_detection | segmentation | general",
+    "general"
+  ).action(
+    action(async ({ ctx, opts, args }) => {
+      const projectId = requireProject(ctx);
+      const source = await resolveMediaSource({ url: opts.url, file: opts.file });
+      const res = await api(ctx, `/projects/${projectId}/images/understand`, {
+        method: "POST",
+        body: { source, query: args[0], task: opts.task }
+      });
+      ok(res, () => line(res?.answer ?? ""));
+    })
+  );
 }
 async function download(url, output) {
   const target = resolve4(output);
@@ -7984,6 +8103,46 @@ async function download(url, output) {
   return target;
 }
 
+// src/commands/video.ts
+function registerVideo(program3) {
+  const video = program3.command("video").description("Understand video (the fallback for a model that can't watch it itself)");
+  video.command("understand <query>").description("Summarize/describe/answer questions about a video").option("-u, --url <url>", "the video's URL (fetched server-side; also accepts a YouTube URL)").option("-f, --file <path>", "a local video file (read + sent inline; small clips only)").option(
+    "-t, --task <task>",
+    "summarize | describe | visual_qa | timestamp_analysis | general",
+    "general"
+  ).action(
+    action(async ({ ctx, opts, args }) => {
+      const projectId = requireProject(ctx);
+      const source = await resolveMediaSource({ url: opts.url, file: opts.file });
+      const res = await api(ctx, `/projects/${projectId}/video/understand`, {
+        method: "POST",
+        body: { source, query: args[0], task: opts.task }
+      });
+      ok(res, () => line(res?.answer ?? ""));
+    })
+  );
+}
+
+// src/commands/audio.ts
+function registerAudio(program3) {
+  const audio = program3.command("audio").description("Understand audio (the fallback for a model that can't hear it itself)");
+  audio.command("understand <query>").description("Transcribe/describe/answer questions about audio").option("-u, --url <url>", "the audio's URL (fetched server-side; also accepts a YouTube URL)").option("-f, --file <path>", "a local audio file (read + sent inline; small clips only)").option(
+    "-t, --task <task>",
+    "transcribe | describe | audio_qa | speaker_diarization | emotion_detection | general",
+    "general"
+  ).action(
+    action(async ({ ctx, opts, args }) => {
+      const projectId = requireProject(ctx);
+      const source = await resolveMediaSource({ url: opts.url, file: opts.file });
+      const res = await api(ctx, `/projects/${projectId}/audio/understand`, {
+        method: "POST",
+        body: { source, query: args[0], task: opts.task }
+      });
+      ok(res, () => line(res?.answer ?? ""));
+    })
+  );
+}
+
 // src/commands/ask.ts
 var import_picocolors25 = __toESM(require_picocolors(), 1);
 var TYPES = [
@@ -8335,15 +8494,33 @@ function collect2(value, previous) {
 
 // src/commands/task.ts
 var import_picocolors28 = __toESM(require_picocolors(), 1);
-var STATUSES2 = ["todo", "working", "checking", "ready", "accepted", "archived"];
+var STATUSES2 = [
+  "todo",
+  "working",
+  "checking",
+  "ready",
+  "accepted",
+  "archived"
+];
 var ROLES = ["pm", "architect", "web", "api", "automation", "qa"];
-var KINDS2 = ["data_reports", "web", "mobile", "service", "automation", "docs"];
+var KINDS2 = [
+  "data_reports",
+  "web",
+  "mobile",
+  "service",
+  "automation",
+  "docs"
+];
 function registerTask(program3) {
   const task = program3.command("task").description("The project's tasks and their subtasks (AI Tech Team)");
-  task.command("list").description("List the board's tasks \u2014 run this before starting anything").option("--status <value>", `only tasks in this status (${STATUSES2.join(" | ")})`).option("--label <value>", "only tasks carrying this label").option("--limit <n>", "cap the number of tasks returned").action(
+  task.command("list").description("List the board's tasks \u2014 run this before starting anything").option(
+    "--status <value>",
+    `only tasks in this status (${STATUSES2.join(" | ")})`
+  ).option("--label <value>", "only tasks carrying this label").option("--limit <n>", "cap the number of tasks returned").action(
     action(async ({ ctx, opts }) => {
       requireProject(ctx);
-      if (opts.status !== void 0) assertOneOf("--status", opts.status, STATUSES2);
+      if (opts.status !== void 0)
+        assertOneOf("--status", opts.status, STATUSES2);
       const rows = await api(ctx, "/v1/project-tasks", {
         query: {
           status: opts.status,
@@ -8365,7 +8542,10 @@ function registerTask(program3) {
   ).action(
     action(async ({ ctx, args }) => {
       const id = args[0] || ctx.parentTaskId || resolveTaskId(ctx);
-      const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(id)}`
+      );
       const goalId = row.goal_id;
       const goal = goalId ? await api(
         ctx,
@@ -8395,8 +8575,14 @@ function registerTask(program3) {
           goalId: opts.goal,
           phase: opts.phase,
           targets: [
-            ...(opts.app ?? []).map((appId) => ({ kind: "app", appId })),
-            ...(opts.infra ?? []).map((ref) => ({ kind: "infra", ref }))
+            ...(opts.app ?? []).map((appId) => ({
+              kind: "app",
+              appId
+            })),
+            ...(opts.infra ?? []).map((ref) => ({
+              kind: "infra",
+              ref
+            }))
           ],
           ...hasChannelOrigin ? {
             channelId: ctx.projectChannelId,
@@ -8436,8 +8622,11 @@ function registerTask(program3) {
         ...channelMessageError ? { channelMessageError } : {}
       };
       ok(result, () => {
-        line(`${import_picocolors28.default.green("opened")} ${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`);
-        if (channelMessage) line(import_picocolors28.default.dim("posted to the channel as Project Manager"));
+        line(
+          `${import_picocolors28.default.green("opened")} ${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`
+        );
+        if (channelMessage)
+          line(import_picocolors28.default.dim("posted to the channel as Project Manager"));
         if (channelMessageError) {
           warn(
             `Task opened, but its Project Manager card could not be posted: ${channelMessageError.message}`
@@ -8449,10 +8638,19 @@ function registerTask(program3) {
   const subtask = task.command("subtask").description("The subtasks a task is broken into");
   subtask.command("add <title>").description(
     'Add one subtask, e.g. `workser task subtask add "Build the upload screen" --role web`'
-  ).option("--task <id>", "the parent task (defaults to the task this run is inside)").option("--role <value>", `who does it (${ROLES.join(" | ")})`).option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--note <text>", "one sentence on what this subtask does").option(
+  ).option(
+    "--task <id>",
+    "the parent task (defaults to the task this run is inside)"
+  ).option("--role <value>", `who does it (${ROLES.join(" | ")})`).option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--note <text>", "one sentence on what this subtask does").option(
     "--app <id...>",
     "the app this subtask is for \u2014 one id runs it inside that app's folder; leave it off and it runs at the project, seeing every app"
-  ).option("--infra <ref...>", "shared setup it touches (database | storage | auth | hosting | jobs)").option("--scope <path...>", "files or folders THIS subtask owns").option("--depends-on <id...>", "subtasks that must finish first (key or id)").action(
+  ).option(
+    "--infra <ref...>",
+    "shared setup it touches (database | storage | auth | hosting | jobs)"
+  ).option("--scope <path...>", "files or folders THIS subtask owns").option(
+    "--depends-on <id...>",
+    "subtasks that must finish first (key or id)"
+  ).action(
     action(async ({ ctx, args, opts }) => {
       const parent = resolveTaskId(ctx, opts.task);
       if (opts.role !== void 0) assertOneOf("--role", opts.role, ROLES);
@@ -8468,13 +8666,21 @@ function registerTask(program3) {
           scopePaths: opts.scope,
           dependsOn,
           targets: [
-            ...(opts.app ?? []).map((appId) => ({ kind: "app", appId })),
-            ...(opts.infra ?? []).map((ref) => ({ kind: "infra", ref }))
+            ...(opts.app ?? []).map((appId) => ({
+              kind: "app",
+              appId
+            })),
+            ...(opts.infra ?? []).map((ref) => ({
+              kind: "infra",
+              ref
+            }))
           ]
         }
       });
       ok(row, () => {
-        line(`${import_picocolors28.default.green("added")} ${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`);
+        line(
+          `${import_picocolors28.default.green("added")} ${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`
+        );
         if (row.role) line(import_picocolors28.default.dim(`role: ${row.role}`));
       });
     })
@@ -8482,7 +8688,10 @@ function registerTask(program3) {
   subtask.command("list [taskId]").description("The subtasks of a task, in order").action(
     action(async ({ ctx, args }) => {
       const id = resolveTaskId(ctx, args[0]);
-      const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(id)}`
+      );
       const rows = row.subtasks ?? [];
       ok(rows, () => {
         if (!rows.length) {
@@ -8522,7 +8731,9 @@ function registerTask(program3) {
       ok({ removed: args[0] }, () => line(import_picocolors28.default.green("removed")));
     })
   );
-  task.command("move <id> <status>").description(`Move a task or step along the board (${STATUSES2.join(" | ")})`).action(
+  task.command("move <id> <status>").description(
+    `Move a task or step along the board (${STATUSES2.join(" | ")})`
+  ).action(
     action(async ({ ctx, args }) => {
       assertOneOf("<status>", args[1], STATUSES2);
       const row = await api(
@@ -8530,7 +8741,10 @@ function registerTask(program3) {
         `/v1/project-tasks/${encodeURIComponent(args[0])}/move`,
         { body: { status: args[1] } }
       );
-      ok(row, () => line(`${import_picocolors28.default.green("moved")} ${import_picocolors28.default.bold(row.title)} \u2192 ${args[1]}`));
+      ok(
+        row,
+        () => line(`${import_picocolors28.default.green("moved")} ${import_picocolors28.default.bold(row.title)} \u2192 ${args[1]}`)
+      );
     })
   );
   task.command("resume [id]").description(
@@ -8581,7 +8795,9 @@ function registerTask(program3) {
       });
     })
   );
-  task.command("can-start [id]").description("Ask whether work on this task may begin. Refuses until the owner approves.").action(
+  task.command("can-start [id]").description(
+    "Ask whether work on this task may begin. Refuses until the owner approves."
+  ).action(
     action(async ({ ctx, args }) => {
       const id = resolveTaskId(ctx, args[0]);
       const row = await api(
@@ -8597,11 +8813,9 @@ function registerTask(program3) {
   ).action(
     action(async ({ ctx, args }) => {
       const id = resolveTaskId(ctx, args[0]);
-      const row = await api(
-        ctx,
-        `/v1/project-tasks/${encodeURIComponent(id)}/start`,
-        { method: "POST" }
-      );
+      const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}/start`, {
+        method: "POST"
+      });
       ok(row, () => {
         const started = row?.started ?? null;
         if (started && started > 0) {
@@ -8627,7 +8841,9 @@ function registerTask(program3) {
         );
         ok({ awaiting: row2.approval_state === "awaiting", task: row2 }, () => {
           line(
-            row2.approval_state === "awaiting" ? import_picocolors28.default.yellow("The plan is waiting on the owner. They see it in the task.") : `Already ${row2.approval_state}.`
+            row2.approval_state === "awaiting" ? import_picocolors28.default.yellow(
+              "The plan is waiting on the owner. They see it in the task."
+            ) : `Already ${row2.approval_state}.`
           );
         });
         return;
@@ -8648,7 +8864,10 @@ function registerTask(program3) {
           }
         }
       );
-      ok(row, () => line(`${import_picocolors28.default.green(row.approval_state)} ${import_picocolors28.default.bold(row.title)}`));
+      ok(
+        row,
+        () => line(`${import_picocolors28.default.green(row.approval_state)} ${import_picocolors28.default.bold(row.title)}`)
+      );
     })
   );
   task.command("done [id]").description("Record what a subtask produced, and move it to ready").option("--summary <text>", "what changed, in the owner's words").action(
@@ -8777,7 +8996,11 @@ Nothing is running. The next part waiting is "${next.name}" \u2014 offer it to t
       )
     );
   } else if (!next) {
-    line(import_picocolors28.default.dim("\nEvery part of this plan is done. Say so, and offer to wrap it up."));
+    line(
+      import_picocolors28.default.dim(
+        "\nEvery part of this plan is done. Say so, and offer to wrap it up."
+      )
+    );
   }
   line(
     import_picocolors28.default.dim(
@@ -9841,7 +10064,7 @@ function requireApp(app) {
   const value = typeof app === "string" ? app.trim() : "";
   if (value) return value;
   throw new WorkserError(
-    "Which service? Pass --app <webAppId>; `workser app list` shows them.",
+    "Which service? Pass --app <webAppId>; `workser project apps` shows them.",
     { code: "bad_request" }
   );
 }
@@ -10632,7 +10855,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.6" : "0.0.0-dev"
+  version: true ? "0.6.8" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -10675,12 +10898,14 @@ registerUsage(program2);
 registerCheckpoint(program2);
 registerSync(program2);
 registerWorkflow(program2);
-registerApp(program2);
+registerConnection(program2);
 registerTool(program2);
 registerMemory(program2);
 registerBusiness(program2);
 registerArtifact(program2);
 registerImage(program2);
+registerVideo(program2);
+registerAudio(program2);
 registerAsk(program2);
 registerSearch(program2);
 registerBoard(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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

@@ -77,6 +77,9 @@ pick or switch it.
 3. **A phased plan goes on the subtask list, never the Board.** Phases are
    `workser task subtask add` (`workser help tasks`) — not `board create`,
    which makes a second, driftable "the plan" the task page never reads.
+   If a subtask's title, teammate, note, or scope is wrong after creation, fix
+   that same row with `workser task subtask update <id> --title … --role …
+   --note … --scope …`; never claim it is locked or create a duplicate.
    Write the narrative once as `doc create` (no `--work-item`, or it's hidden
    from the Docs panel), plus `decision create` for a real tradeoff. A plan
    in your reply alone is gone when the conversation scrolls. Details:

package/skills/workser/reference/automation.md

@@ -2,7 +2,7 @@
 topic: automation
 title: Workflows & connected apps
 summary: Build automations that outlive the run; use Gmail, Slack, Stripe, Sheets.
-commands: [workflow, app]
+commands: [workflow, connection]
 ---
 
 # Workflows & connected apps
@@ -16,10 +16,11 @@ workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <js
 workser workflow runs <id>          # past executions of a workflow
 workser workflow nodes [query]      # search the node-type catalog
 
-workser app list [--toolkit <slug>] # connectable + connected third-party apps
-workser app connect <toolkit> | disconnect <connectionId>
-workser app tools <toolkit>         # a connected app's callable actions
-workser app run <toolSlug> [--body <json>]  # execute one action
+workser connection list [--toolkit <slug>]  # connectable + connected third-party apps
+workser connection search "<query>" [--toolkit <slug>] [--limit N]  # find an action across every toolkit
+workser connection connect <toolkit> | disconnect <connectionId>
+workser connection tools <toolkit>          # browse one connected toolkit's actions
+workser connection run <toolSlug> [--body <json>]  # execute one action
 ```
 
 ## Building a workflow
@@ -35,12 +36,13 @@ Created workflows start inactive: `workser workflow activate <id>` when it's rea
 
 ## Using a connected app
 
-1. `workser app list` — check what's already connected before asking for anything.
-2. If it isn't: `workser app connect <toolkit>` returns an OAuth link. The **user**
+1. `workser connection list` — check what's already connected before asking for anything.
+2. If it isn't: `workser connection connect <toolkit>` returns an OAuth link. The **user**
    must open it; you cannot complete OAuth on their behalf. Wait, then continue.
-3. `workser app tools <toolkit>` — read the argument schema rather than guessing
-   field names.
-4. `workser app run <toolSlug> --body '{"…":…}'` — e.g. `GOOGLESHEETS_APPEND_ROW`,
+3. Don't know the exact action? `workser connection search "<query>"` finds it across
+   every toolkit; `workser connection tools <toolkit>` browses one toolkit you already
+   know. Either way, read the argument schema rather than guessing field names.
+4. `workser connection run <toolSlug> --body '{"…":…}'` — e.g. `GOOGLESHEETS_APPEND_ROW`,
    `GMAIL_SEND_EMAIL`.
 
 **A `run` is a real side effect in someone's real account.** Sending an email or

package/skills/workser/reference/images.md

@@ -1,11 +1,11 @@
 ---
 topic: images
-title: Image generation
-summary: Generate images from a prompt, optionally conditioned on existing images.
-commands: [image]
+title: Image generation & media understanding
+summary: Generate images from a prompt; describe/transcribe an image, video, or audio clip you can't natively see or hear.
+commands: [image, video, audio]
 ---
 
-# Image generation
+# Image generation & media understanding
 
 ```
 workser image generate "<prompt>"            # alias: workser image gen
@@ -21,7 +21,7 @@ workser image generate "flat illustration of a farm delivery van, brand colors"
 workser image gen "same van, from the side" -r https://… -o ./public/van.png --json
 ```
 
-## Notes that matter
+## Notes that matter (generation)
 
 - **Reference images are image-to-image conditioning**, not attachments. Up to 4;
   anything beyond that is dropped.
@@ -33,3 +33,39 @@ workser image gen "same van, from the side" -r https://… -o ./public/van.png -
   exist only as URLs.
 - **Placeholder art is not a deliverable.** Generating a hero image to unblock a
   layout is fine; shipping it as the user's brand asset without asking is not.
+
+## Understanding media you can't natively see or hear
+
+The fallback for a text-only model, or media you have no other way to reach: describe
+an image, summarize/transcribe a video, transcribe/describe audio. Runs server-side
+(Gemini) — you never need a model key.
+
+```
+workser image understand "<query>" [--url <u> | --file <p>] [-t <task>]
+workser video understand "<query>" [--url <u> | --file <p>] [-t <task>]
+workser audio understand "<query>" [--url <u> | --file <p>] [-t <task>]
+```
+
+```bash
+workser image understand "what's wrong with this layout?" --url https://…/screenshot.png --json
+workser video understand "what happens at the end?" --url https://youtu.be/… -t timestamp_analysis --json
+workser audio understand "transcribe this" --file ./voicemail.m4a -t transcribe --json
+```
+
+## Notes that matter (understanding)
+
+- **`--url` vs `--file`**: `--url` is fetched server-side with no size ceiling — the
+  right choice for anything already hosted (a project's own storage bucket, a public
+  link, a YouTube URL for video/audio). `--file` is read and sent inline by the CLI
+  itself, so it's bounded by the daemon's own request-size limit — for a small local
+  file only (a screenshot, a short voice memo). Something bigger: `workser storage
+  upload` it first, then pass the returned URL with `--url`.
+- **`-t/--task` shapes the answer, it doesn't gate what you can ask** — `general` (the
+  default) takes any free-form `<query>`. The other values just bias the prompt
+  toward a specific shape: `caption`/`visual_qa`/`object_detection`/`segmentation`
+  for images; `summarize`/`describe`/`visual_qa`/`timestamp_analysis` for video;
+  `transcribe`/`describe`/`audio_qa`/`speaker_diarization`/`emotion_detection` for
+  audio.
+- **This is billed to the project's organization**, same as image generation — it's
+  a real provider call, not free introspection. Don't loop it over every file in a
+  folder "just in case"; use it when you actually need to know what's in one.