@melius-ai/cli 0.5.2 → 0.7.0

package/README.md

@@ -259,12 +259,15 @@ mel upload ./photo.png --node-id <nodeId> --canvas-id <canvasId>
 
 Requires the Pro or Enterprise plan.
 
-| Command                                    | Description                                                                                                                    |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `mel asset search <query>`                 | Search the team's Files/DAM library (uploads + past generations) by meaning; exact matches rank first. Returns up to 5 matches |
-| `mel asset place <canvasId> <assetIds...>` | Place existing library assets onto a canvas by id — references the **original** asset (no duplicate)                           |
+| Command                                    | Description                                                                                                                              |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `mel asset search [query]`                 | Search the team's Files/DAM library (uploads + past generations) by meaning; exact matches rank first. Returns up to 20 matches per page |
+| `mel asset folders`                        | List the library's folders (`id`, `name`, `path`, `fileCount`) so you can resolve a folder name to an id for `--folder-id`               |
+| `mel asset place <canvasId> <assetIds...>` | Place existing library assets onto a canvas by id — references the **original** asset (no duplicate)                                     |
 
-`mel asset search` searches by meaning (semantic), with exact filename/title matches ranked first, so query with a filename or a description of the content. It returns `{ query, total, results: [{ assetId, filename, fileType, previewUrl, ... }] }`. Filter with `--file-type <image|video|audio|pdf|text>` and `--limit <1-5>`; scope to one canvas with `--canvas-id` (omit to search the whole team library).
+`mel asset search` searches by meaning (semantic), with exact filename/title matches ranked first, so query with a filename or a description of the content. It returns `{ query, total, results: [{ assetId, filename, fileType, previewUrl, ... }] }`. Filter with `--file-type <image|video|audio|pdf|text>` and `--limit <1-20>`; page deeper with `--offset <n>` (skip the first N matches — page until the running count reaches `total`); scope to one canvas with `--canvas-id` (omit to search the whole team library).
+
+Scope to a **folder** with `--folder-id` (from `mel asset folders`): with a query it filters within that folder and its subfolders; **omit the query** to bring in the _whole_ folder (every asset in it). `mel asset folders` returns each folder's root-relative `path` (e.g. `Brand / Logos`) to disambiguate same-named folders.
 
 `mel asset place` creates a file node per asset (writes to CRDT, no re-upload) and returns `{ placed: [{ assetId, nodeId, mediaType }] }`. Wire the returned `nodeId`s into generations with `mel edge create`. This is the correct way to reuse an existing library asset — do **not** re-upload it.
 
@@ -272,6 +275,11 @@ Requires the Pro or Enterprise plan.
 # Find an asset, then bring it onto a canvas and wire it
 mel asset search "black jacket shot" --file-type image
 mel asset place <canvasId> <assetId1> <assetId2>
+
+# Bring in a whole folder: resolve the folder, then search it with no query
+mel asset folders                                   # → [{ id, name, path, fileCount }]
+mel asset search --folder-id <folderId>             # every asset in the folder
+mel asset search "shark" --folder-id <folderId>     # or filter within it
 ```
 
 ### Shell completion

package/dist/bin/mel.js

@@ -7,7 +7,7 @@ import {
   printUpgradeNoticeIfNeeded,
   withDefaultHelp,
   writeError
-} from "../chunk-4GUG5TD2.js";
+} from "../chunk-5QT6WMID.js";
 
 // bin/mel.ts
 var program = createProgram();

package/dist/{chunk-4GUG5TD2.js → chunk-5QT6WMID.js}

@@ -7914,7 +7914,11 @@ var FileTypeSchema = external_exports.enum([
 var FileCanvasBacklinkSchema = external_exports.object({
   canvasId: external_exports.string().uuid(),
   projectId: external_exports.string().uuid(),
-  canvasTitle: external_exports.string()
+  canvasTitle: external_exports.string(),
+  // A node on this canvas whose active version holds the asset, so opening
+  // the canvas can center on it. Null when no such node survives (e.g. it was
+  // deleted but the asset is still referenced elsewhere on the canvas).
+  nodeId: external_exports.string().uuid().nullable().optional()
 });
 var FileCardSchema = external_exports.object({
   assetId: external_exports.string().uuid(),
@@ -8079,14 +8083,20 @@ var ListFilesResponseSchema = external_exports.object({
   cursor: external_exports.string().nullable().optional(),
   hasMore: external_exports.boolean().optional()
 });
+var AGENT_ASSET_SEARCH_PAGE_SIZE = 20;
 var AgentAssetSearchQuerySchema = external_exports.object({
-  query: external_exports.string().trim().min(1).max(500).describe("Asset search query"),
-  limit: external_exports.coerce.number().int().min(1).max(5).default(5),
+  query: external_exports.string().trim().min(1).max(500).optional().describe(
+    'The semantic search query \u2014 a filename or a description of the asset (e.g. "red logo", "the shark photo"). Provide it to FIND specific assets. OMIT it entirely to bring in EVERY asset from a folder: when the member says "bring in all my assets from the X folder" / "add everything in X to the canvas", resolve the folder with list_asset_folders and call asset_search with just that `folderId` and NO query. Never invent a query when the member asked for everything in a folder \u2014 a query filters and will drop assets they wanted. Omitting the query requires a `folderId`.'
+  ),
+  limit: external_exports.coerce.number().int().min(1).max(AGENT_ASSET_SEARCH_PAGE_SIZE).default(AGENT_ASSET_SEARCH_PAGE_SIZE),
   source: FileSourceSchema.optional(),
   fileType: FileTypeSchema.optional(),
   canvasId: external_exports.string().uuid().optional().describe(
     'Optional. Omit to search the whole team library \u2014 this is the default and what nearly every request wants (e.g. "use the asset I have"). Only set this to scope to a DIFFERENT canvas the member explicitly names ("search my other canvas"), resolving the id from canvas_list. Do NOT pass the canvas the chat is currently on (its assets are already visible via canvas_content, and scoping there hides whole-library matches), and never guess an id.'
   ),
+  folderId: external_exports.string().uuid().optional().describe(
+    'Optional. Scope to one Files folder AND its subfolders. Omit to search the whole team library \u2014 the default, and what nearly every request wants. Set it when the member names a specific folder \u2014 either to FILTER within it (pass `folderId` + `query`, e.g. "find the shark shot in my ocean folder") or to bring in EVERYTHING in it (pass `folderId` and OMIT `query`, e.g. "add all my assets from the ocean folder"). Resolve the id with list_asset_folders (match by name; if several plausibly match, ask which one); never guess a folder id.'
+  ),
   showInThread: external_exports.boolean().optional().describe(
     'Slack only. Set true when the member only wants to SEE the matched asset(s) \u2014 "find X and show it to me", "do I have Y?" \u2014 and is NOT asking to place, edit, or build on them. Skips the selection card and posts every match straight into the Slack thread as image files. Leave unset (the default) whenever the member wants to USE an asset on the canvas, so the selection card renders and a canvas gets bound.'
   )
@@ -8094,13 +8104,40 @@ var AgentAssetSearchQuerySchema = external_exports.object({
 var AgentAssetSearchModeSchema = external_exports.enum(["semantic", "filename"]);
 var AgentAssetSearchRequestSchema = AgentAssetSearchQuerySchema.extend(
   {
-    mode: AgentAssetSearchModeSchema.optional()
+    mode: AgentAssetSearchModeSchema.optional(),
+    // Pagination offset for the picker's "More results" button. Like
+    // `mode`, it lives here and NOT on `AgentAssetSearchQuerySchema` (the
+    // LLM tool input) so the model can never paginate — paging is a member
+    // action. Optional (not `.default(0)`): a default would make `offset`
+    // required in the inferred type and break assignment from the tool
+    // input, which has no offset. The service treats an absent offset as 0.
+    offset: external_exports.coerce.number().int().min(0).optional()
   }
 );
 var AgentAssetSearchResponseSchema = external_exports.object({
   query: external_exports.string(),
   results: external_exports.array(FileCardSchema),
-  total: external_exports.number().int().nonnegative()
+  total: external_exports.number().int().nonnegative(),
+  // Echo the search scope so the picker's "More results" button can re-page
+  // with the SAME scope. Without this, page 2 drops the folder/canvas filter
+  // and pages the whole library (and a query-less folder browse can't page at
+  // all). Absent when the corresponding filter wasn't set.
+  folderId: external_exports.string().uuid().optional(),
+  canvasId: external_exports.string().uuid().optional(),
+  source: FileSourceSchema.optional(),
+  fileType: FileTypeSchema.optional()
+});
+var AgentListAssetFoldersQuerySchema = external_exports.object({});
+var AgentAssetFolderSchema = external_exports.object({
+  id: external_exports.string().uuid(),
+  name: external_exports.string(),
+  // Full path from the team root (e.g. "Brand / Logos") so the agent can
+  // disambiguate when several folders share a name.
+  path: external_exports.string(),
+  fileCount: external_exports.number().int().nonnegative()
+});
+var AgentListAssetFoldersResponseSchema = external_exports.object({
+  folders: external_exports.array(AgentAssetFolderSchema)
 });
 var InitFilesUploadBodySchema = external_exports.object({
   filename: external_exports.string(),
@@ -8278,6 +8315,15 @@ var filesContract = c2.router({
     },
     summary: "Search team assets for the agent"
   },
+  listAgentAssetFolders: {
+    method: "GET",
+    path: "/files/agent-folders",
+    responses: {
+      200: AgentListAssetFoldersResponseSchema,
+      403: ErrorBodySchema
+    },
+    summary: "List team asset folders for the agent"
+  },
   getEmbeddingStorageUsage: {
     method: "GET",
     path: "/files/embedding-storage-usage",
@@ -8703,7 +8749,15 @@ var agentContract = c3.router({
         // clients that predate selection persistence.
         assetIds: external_exports.array(external_exports.string()).optional()
       }),
-      external_exports.object({ action: external_exports.literal("decline") })
+      external_exports.object({
+        action: external_exports.literal("decline"),
+        // When the member declines these results and instead types a new
+        // query into the card's "search for something else" input, the
+        // resumed turn re-runs asset_search with exactly this query
+        // instead of the agent asking a clarify. Bounds mirror
+        // `AgentAssetSearchQuerySchema.query`. Omitted = plain decline.
+        searchAgainQuery: external_exports.string().trim().min(1).max(500).optional()
+      })
     ]),
     responses: {
       200: AgentToolApprovalResponseSchema,
@@ -9061,14 +9115,14 @@ var AUTO_MODEL_REGISTRY = [
   {
     nodeType: "text",
     inputPattern: "default",
-    standard: { model: "gemini-3-flash", variant: "text" },
-    fast: { model: "gemini-3-flash", variant: "text" }
+    standard: { model: "gemini-3.1-pro", variant: "text" },
+    fast: { model: "gemini-3.1-pro", variant: "text" }
   },
   {
     nodeType: "text",
     inputPattern: "with-video",
-    standard: { model: "gemini-3-flash", variant: "text" },
-    fast: { model: "gemini-3-flash", variant: "text" }
+    standard: { model: "gemini-3.1-pro", variant: "text" },
+    fast: { model: "gemini-3.1-pro", variant: "text" }
   },
   // ── Audio ───────────────────────────────────────────────────────────
   {
@@ -9928,15 +9982,22 @@ var TemplatePortSchema = external_exports.discriminatedUnion("direction", [
     /** Creator-set cap on connections into this input. Absent = unlimited. */
     maxConnections: external_exports.number().int().positive().optional(),
     /**
-     * Hidden input: not exposed as a connectable handle on the collapsed box
+     * Locked input: not exposed as a connectable handle on the collapsed box
      * — its value comes from the source baked into the template definition
      * (used as-is for an upload/custom text, regenerated for a generation
      * node). The port is still recorded (rather than dropped) so it
-     * round-trips for editing in the internal tool. At apply, hidden input
+     * round-trips for editing in the internal tool. At apply, locked input
      * ports are not materialized as instance bindings, so no handle renders
      * and they never gate a run.
      */
-    hidden: external_exports.boolean().optional(),
+    locked: external_exports.boolean().optional(),
+    /**
+     * For a locked input only: the template node key of the baked source
+     * whose value is frozen in. Lets apply resolve the materialized source
+     * node so "Expand template" can surface it into the input column.
+     * Absent for visible inputs (the user supplies their own source).
+     */
+    sourceNodeKey: external_exports.string().optional(),
     /**
      * Every internal handle this input fans out to. Absent/empty = the
      * single `nodeKey`/`internalHandle` binding (pre-fan-out templates).
@@ -9971,12 +10032,12 @@ var InstancePortBindingSchema = external_exports.discriminatedUnion("direction",
     required: external_exports.boolean().optional(),
     maxConnections: external_exports.number().int().positive().optional(),
     /**
-     * Mirror of `TemplatePort.hidden`. Hidden input ports are not
+     * Mirror of `TemplatePort.locked`. Locked input ports are not
      * materialized as instance bindings today (the box never renders them),
      * so this is carried for symmetry/forward-compat rather than read at
      * runtime.
      */
-    hidden: external_exports.boolean().optional(),
+    locked: external_exports.boolean().optional(),
     /**
      * Every internal endpoint this input fans out to (resolved form of
      * `TemplatePort.internalTargets`). Absent/empty = the single
@@ -10138,9 +10199,10 @@ var CropRectSchema = external_exports.object({
 });
 var StitchClipOrderSchema = external_exports.array(external_exports.string());
 var StitchScaleFitSchema = external_exports.enum(["fit", "stretch"]);
+var roundMs = (value) => typeof value === "number" ? Math.round(value) : value;
 var StitchTrimWindowFields = {
-  trimStartMs: external_exports.number().int().nonnegative().optional(),
-  trimEndMs: external_exports.number().int().positive().optional()
+  trimStartMs: external_exports.preprocess(roundMs, external_exports.number().int().nonnegative()).optional(),
+  trimEndMs: external_exports.preprocess(roundMs, external_exports.number().int().positive()).optional()
 };
 var StitchAudioOverlaySchema = external_exports.object({
   nodeId: external_exports.string(),
@@ -10156,6 +10218,8 @@ var AssetSummaryDetailsSchema = external_exports.object({
   summary: external_exports.string()
 });
 var AssetResponseSchema = external_exports.object({
+  /** Omitted from persisted snapshots created before this field existed. */
+  assetId: external_exports.string().uuid().optional(),
   url: external_exports.string().nullable(),
   originalUrl: external_exports.string().nullable(),
   previewUrl: external_exports.string().nullable(),
@@ -10302,6 +10366,8 @@ var NodeResponseSchema = external_exports.object({
   templatePorts: external_exports.array(InstancePortBindingSchema).nullable().optional(),
   /** The source template id on a template-instance group (from CRDT). */
   templateId: external_exports.string().uuid().nullable().optional(),
+  /** Whether a template-instance group may be expanded to its workflow (from CRDT). */
+  isExpandable: external_exports.boolean().nullable().optional(),
   /** Direct child node IDs when nodeType is group (for agent wiring). */
   childNodeIds: external_exports.array(external_exports.string().uuid()).optional(),
   /** Per-ratio outputs for magic-resize nodes (from CRDT); one per variant. */
@@ -10407,8 +10473,11 @@ var NodeRunStatusSchema = external_exports.enum([
 var CreateNodeRunResponseSchema = external_exports.object({
   id: external_exports.string().uuid()
 });
+var RunOriginSchema = external_exports.enum(["canvas", "playground"]);
 var RunNodeBodySchema = external_exports.object({
   canvasId: external_exports.string().uuid().optional(),
+  /** Product surface this run originated on. Defaults to `canvas` server-side. */
+  origin: RunOriginSchema.optional(),
   textPrompt: external_exports.string().optional(),
   modelConfig: ModelConfigInputSchema.optional(),
   outputAspectRatio: OutputAspectRatioSchema.optional(),
@@ -10723,7 +10792,13 @@ var CreateDirectNodeBodyObjectSchema = external_exports.object({
   /** For template-instance groups only: resolved input/output port bindings. */
   templatePorts: external_exports.array(InstancePortBindingSchema).nullable().optional(),
   /** For template-instance groups only: the id of the source template. */
-  templateId: external_exports.string().uuid().nullable().optional()
+  templateId: external_exports.string().uuid().nullable().optional(),
+  /** For template-instance groups only: whether the box may be expanded to its
+   *  workflow (snapshot of the template's setting at apply time). */
+  isExpandable: external_exports.boolean().nullable().optional(),
+  /** For template-instance groups only: node ids of the baked locked-input
+   *  sources, surfaced into the input column when the box is expanded. */
+  lockedInputNodeIds: external_exports.array(external_exports.string().uuid()).nullable().optional()
 });
 var CreateDirectNodeBodySchema = CreateDirectNodeBodyObjectSchema.superRefine(
   validateDirectFileNodeAssetFields
@@ -11060,6 +11135,31 @@ var canvasContract = c7.router({
       404: MessageResponseSchema
     }
   },
+  // Mint per-node presigned download URLs (Content-Disposition: attachment)
+  // so a client can trigger a real file download. Used by the display_canvas
+  // MCP App, whose sandboxed iframe cannot download directly and must hand a
+  // download-forcing URL to the host. Returns only nodes with a downloadable
+  // active-version asset; nodes without one are omitted.
+  getNodeDownloadUrls: {
+    method: "POST",
+    path: "/canvases/:canvasId/node-download-urls",
+    pathParams: external_exports.object({ canvasId: external_exports.string().uuid() }),
+    body: external_exports.object({
+      nodeIds: external_exports.array(external_exports.string().uuid()).min(1).max(100)
+    }),
+    responses: {
+      200: external_exports.object({
+        urls: external_exports.array(
+          external_exports.object({
+            nodeId: external_exports.string().uuid(),
+            downloadUrl: external_exports.string().url(),
+            filename: external_exports.string()
+          })
+        )
+      }),
+      404: MessageResponseSchema
+    }
+  },
   listCanvasAssets: {
     method: "GET",
     path: "/canvases/:canvasId/assets",
@@ -11451,6 +11551,8 @@ var canvasContract = c7.router({
     pathParams: external_exports.object({ canvasId: external_exports.string().uuid() }),
     body: external_exports.object({
       nodeIds: external_exports.array(external_exports.string().uuid()).min(1).max(500),
+      /** Product surface this run originated on. Defaults to `canvas` server-side. */
+      origin: RunOriginSchema.optional(),
       /** Explicit image URLs applied to every node in the bulk run (merged with edge-resolved images). */
       imageUrls: external_exports.array(external_exports.string().url()).optional(),
       /**
@@ -12135,6 +12237,10 @@ var ModelCostSchema = external_exports.discriminatedUnion("type", [
     maxCreditCost: external_exports.number()
   })
 ]);
+var TextTokenPricingSchema = external_exports.object({
+  inputCreditsPerMillionTokens: external_exports.number(),
+  outputCreditsPerMillionTokens: external_exports.number()
+});
 var InputFileSizeConstraintsResponseSchema = external_exports.object({
   maximumFileBytes: external_exports.number().int().nonnegative().optional(),
   maximumTotalBytes: external_exports.number().int().nonnegative().optional()
@@ -12240,7 +12346,9 @@ var ModelResponseSchema = external_exports.object({
   hiddenFromAgent: external_exports.boolean().optional(),
   promoRateLimit: PromoRateLimitSchema.optional(),
   /** Maximum prompt length in characters. Used by text models that lack variants. */
-  maxPromptLength: external_exports.number().nullable().optional()
+  maxPromptLength: external_exports.number().nullable().optional(),
+  /** Per-1M-token credit rates for text models; drives the live cost-range estimate. */
+  textTokenPricing: TextTokenPricingSchema.optional()
 });
 var ListGenerativeModelsResponseSchema = external_exports.object({
   models: external_exports.array(ModelResponseSchema)
@@ -12733,7 +12841,8 @@ var EnterpriseOrderLineItemSchema = external_exports.object({
 var EnterpriseBillingIntervalSchema = external_exports.enum(["monthly", "annual"]);
 var EnterpriseStripeBillingInputSchema = external_exports.object({
   unitAmount: external_exports.number().int().positive(),
-  currency: external_exports.string().length(3).transform((value) => value.toLowerCase()),
+  // Expose the transform output to OpenAPI generation.
+  currency: external_exports.string().length(3).transform((value) => value.toLowerCase()).pipe(external_exports.string()),
   billingInterval: EnterpriseBillingIntervalSchema,
   creditsPerPeriod: external_exports.number().int().positive(),
   contractEndAt: external_exports.string().datetime().optional()
@@ -12797,7 +12906,8 @@ var EnterprisePendingExpansionSchema = external_exports.object({
 });
 var EnterpriseStripeBillingSchema = external_exports.object({
   unitAmount: external_exports.number().int().positive(),
-  currency: external_exports.string().length(3).transform((value) => value.toLowerCase()),
+  // Expose the transform output to OpenAPI generation.
+  currency: external_exports.string().length(3).transform((value) => value.toLowerCase()).pipe(external_exports.string()),
   billingInterval: EnterpriseBillingIntervalSchema,
   creditsPerPeriod: external_exports.number().int().positive(),
   contractEndAt: external_exports.string().datetime().optional(),
@@ -13511,10 +13621,13 @@ var publicContract = c16.router(
       complete: uploadContract.complete
     },
     asset: {
-      // Semantic/filename search of the team's Files (DAM) library, and
-      // placing a found asset onto a canvas by reference (no duplicate).
-      // Both are gated to Pro + Enterprise by the handlers.
+      // Semantic/filename search of the team's Files (DAM) library,
+      // listing the library's folders (to resolve a folder name → id for a
+      // folder-scoped search), and placing a found asset onto a canvas by
+      // reference (no duplicate). All gated to Pro + Enterprise by the
+      // handlers.
       search: filesContract.searchAgentAssets,
+      folders: filesContract.listAgentAssetFolders,
       place: canvasContract.placeLibraryAssets
     },
     model: {
@@ -13781,7 +13894,7 @@ function isMajorUpgrade(current, latest) {
   return l[0] > c17[0];
 }
 function shouldShowUpgradeNotice(ctx = {}) {
-  const current = ctx.current ?? "0.5.2";
+  const current = ctx.current ?? "0.7.0";
   const latest = ctx.latest ?? serverLatestVersion;
   const env = ctx.env ?? process.env;
   const isTty = ctx.isTty ?? Boolean(process.stderr.isTTY);
@@ -13802,7 +13915,7 @@ Upgrade: npm install -g @melius-ai/cli@latest  (or: brew update && brew upgrade
 function printUpgradeNoticeIfNeeded(ctx = {}) {
   try {
     if (!shouldShowUpgradeNotice(ctx)) return;
-    const current = ctx.current ?? "0.5.2";
+    const current = ctx.current ?? "0.7.0";
     const latest = ctx.latest ?? serverLatestVersion;
     process.stderr.write(formatUpgradeNotice(current, latest));
   } catch {
@@ -18486,37 +18599,65 @@ function registerAssetCommands(program2, getOutputOpts) {
     "Search and place the team's Files (DAM) library assets. Requires a Pro or Enterprise plan"
   );
   asset.command("search").description(
-    "Search the team's Files/DAM library (uploads + past generations) by meaning (semantic), with exact filename/title matches ranked first. Returns up to 5 relevant matches"
+    "Search the team's Files/DAM library (uploads + past generations) by meaning (semantic), with exact filename/title matches ranked first. Returns up to 20 relevant matches per page. Scope to a folder with --folder-id; omit the query and pass --folder-id to bring in the WHOLE folder"
   ).argument(
-    "<query>",
-    'Search terms \u2014 a filename or a description of the content, e.g. "Product_Shot_05" or "black jacket shot"'
-  ).option("--limit <n>", "Max results (1-5, default 5)", "5").option(
+    "[query]",
+    'Search terms \u2014 a filename or a description of the content, e.g. "Product_Shot_05" or "black jacket shot". Optional: OMIT it and pass --folder-id to list EVERY asset in that folder'
+  ).option("--limit <n>", "Max results per page (1-20, default 20)", "20").option(
+    "--offset <n>",
+    "Skip the first N matches to page deeper (default 0). Page with --limit until the running count reaches the response's total",
+    "0"
+  ).option(
     "--file-type <type>",
     "Filter by media type: image, video, audio, pdf, or text"
   ).option(
     "--canvas-id <canvasId>",
     "Scope to one canvas's assets (a filename match within that canvas). Omit to search the whole team library by meaning, exact matches first (the default)"
+  ).option(
+    "--folder-id <folderId>",
+    "Scope to one Files folder AND its subfolders. WITH a query, filters within the folder; WITHOUT a query, returns every asset in the folder. Get folder ids from mel asset folders"
   ).addHelpText(
     "after",
     `
 Returns: { query, total, results: [{ assetId, filename, displayName, fileType, contentType, previewUrl, assetUrl, durationInMs }] }.
+total is the full match count; page through it with --limit + --offset.
 Use the returned assetId values with mel asset place to bring them onto a canvas.
+Resolve a folder name to an id with mel asset folders first.
 
 Examples:
   $ mel asset search "black jacket shot"
-  $ mel asset search "logo" --file-type image --limit 3`
+  $ mel asset search "logo" --file-type image --limit 10
+  $ mel asset search "logo" --limit 20 --offset 20
+  $ mel asset search "shark" --folder-id <folderId>   # find within a folder
+  $ mel asset search --folder-id <folderId>           # bring in the WHOLE folder`
   ).action(
     async (query, opts) => {
+      if (query === void 0 && opts.folderId === void 0) {
+        writeError(
+          formatError(
+            "USAGE_ERROR",
+            "Provide a search query, or --folder-id to bring in a whole folder",
+            {
+              suggestion: "Run mel asset folders to list folder ids, then: mel asset search --folder-id <folderId>"
+            }
+          ),
+          EXIT_USAGE_ERROR
+        );
+      }
       const client = getClient();
       const result = await client.asset.search({
         query: {
-          query,
+          ...query !== void 0 && { query },
           limit: Number(opts.limit),
+          offset: Number(opts.offset),
           ...opts.fileType !== void 0 && {
             fileType: opts.fileType
           },
           ...opts.canvasId !== void 0 && {
             canvasId: opts.canvasId
+          },
+          ...opts.folderId !== void 0 && {
+            folderId: opts.folderId
           }
         }
       });
@@ -18530,6 +18671,31 @@ Examples:
       writeJson(result.body, getOutputOpts());
     }
   );
+  asset.command("folders").description(
+    "List the team's Files/DAM folders (id, name, full path, file count). Use a folder's id with mel asset search --folder-id to scope a search or bring in the whole folder"
+  ).addHelpText(
+    "after",
+    `
+Returns: an array of { id, name, path, fileCount }.
+path is the folder's location from the library root (e.g. "Brand / Logos") \u2014 use it to disambiguate same-named folders.
+Pass a folder id to mel asset search --folder-id <folderId>.
+
+Examples:
+  $ mel asset folders
+  $ mel asset folders --text`
+  ).action(async () => {
+    const client = getClient();
+    const result = await client.asset.folders();
+    if (result.status !== 200) {
+      handleApiError(
+        result.status,
+        result.body,
+        result.status === 403 ? ASSET_PLAN_REQUIRED_SUGGESTION : void 0
+      );
+    }
+    const body = result.body;
+    writeJson(body.folders, getOutputOpts());
+  });
   asset.command("place").description(
     "Place existing library assets onto a canvas by id, referencing the ORIGINAL asset (no duplicate, no re-upload). Creates file nodes server-side (writes to CRDT) and returns their node ids"
   ).argument(
@@ -18699,7 +18865,7 @@ function withDefaultHelp(args) {
 }
 function createProgram() {
   const program2 = new Command();
-  program2.name("mel").description("Mel \u2014 Melius agent CLI").version("0.5.2").showSuggestionAfterError(true).option("--json", "Force JSON output (default)").option("--text", "Human-readable output").option(
+  program2.name("mel").description("Mel \u2014 Melius agent CLI").version("0.7.0").showSuggestionAfterError(true).option("--json", "Force JSON output (default)").option("--text", "Human-readable output").option(
     "--fields <fields>",
     "Select specific output fields (comma-separated)"
   ).option("--quiet", "Suppress output, exit code only").option("--verbose", "Log request/response metadata to stderr").addHelpText(

package/dist/src/index.js

@@ -2,7 +2,7 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 import {
   createProgram,
   withDefaultHelp
-} from "../chunk-4GUG5TD2.js";
+} from "../chunk-5QT6WMID.js";
 export {
   createProgram,
   withDefaultHelp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melius-ai/cli",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "The Melius command-line interface — create canvases and run AI image/video generations from your terminal",
   "keywords": [
     "ai",