@workser/cli 0.6.6 → 0.6.7

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,6 +88,16 @@ 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
 
 # owner-only (will return owner_only / exit 6 — ask the user to do these in Orbit):
@@ -215,11 +226,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 = [
@@ -9841,7 +10000,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 +10791,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.6" : "0.0.0-dev"
+  version: true ? "0.6.7" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -10675,12 +10834,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.7",
   "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/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.