zinkee 0.1.24 → 0.1.25

package/.claude/settings.local.json

@@ -43,7 +43,11 @@
       "Bash(git -C /home/guillermo/dev/cli branch --show-current)",
       "Bash(git -C /home/guillermo/dev/cli diff --stat)",
       "Bash(git fetch *)",
-      "Bash(pnpm exec *)"
+      "Bash(pnpm exec *)",
+      "Bash(echo \"=== exit $? \\(grep\\) ===\")",
+      "Bash(grep -rn \"resourceType\" src/)",
+      "Bash(grep -rn \"automation-folders/\\\\${\\\\|/automations:move\\\\|{folderId}/automations\" src/)",
+      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)"
     ]
   }
 }

package/README.md

@@ -338,7 +338,7 @@ zinkee --json logs list <schema-slug> <record-uuid>
 
 ## Navigation
 
-Organize schemas into database folders.
+Organize schemas into database folders. The navigation menu holds databases, so only schemas can be moved here.
 
 ```bash
 # List folders with contents
@@ -348,13 +348,16 @@ zinkee --json navigation folders list
 zinkee navigation folders create --name "CRM" --order 1
 
 # Move a schema into a folder
-zinkee navigation resources move <schema-uuid> --type SCHEMA --to "CRM"
+zinkee navigation resources move <schema-uuid> --to "CRM"
 
-# Delete folder (resources move back to root silently)
+# Move a schema back to the workspace root
+zinkee navigation resources move <schema-uuid> --to 00000000-0000-0000-0000-000000000000
+
+# Delete folder (schemas move back to root silently)
 zinkee navigation folders delete "CRM"
 ```
 
-Root folder cannot be deleted.
+Only schemas can be moved (schedules and sub-schemas follow their parent schema). Root folder cannot be deleted; its UUID is always `00000000-0000-0000-0000-000000000000`.
 
 ---
 
@@ -388,6 +391,27 @@ zinkee teamspace resources publish projects --to "Other Folder"
 
 Displays are dashboards composed of widgets that visualize data from schemas.
 
+### Display folders
+
+Organize displays into folders in the displays menu. Folders are flat (name only) and only displays can be moved into them.
+
+```bash
+# List display folders (non-root folders plus the root bucket)
+zinkee --json displays folders list
+
+# Create a folder
+zinkee displays folders create --name "Executive Dashboards"
+
+# Rename a folder
+zinkee displays folders update "Executive Dashboards" --name "Executive Dashboards (2026)"
+
+# Move a display into a folder
+zinkee displays folders move <display-uuid> --to "Executive Dashboards"
+
+# Delete a folder (its displays move back to the root folder)
+zinkee displays folders delete "Executive Dashboards"
+```
+
 ### Creation flow
 
 1. Create the display

package/dist/index.js

@@ -275,6 +275,41 @@ var commandRegistry = {
     supportsRaw: false,
     output: writeOutput
   },
+  "displays folders list": {
+    command: "displays folders list",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput
+  },
+  "displays folders create": {
+    command: "displays folders create",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders update": {
+    command: "displays folders update",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders delete": {
+    command: "displays folders delete",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders move": {
+    command: "displays folders move",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
   "displays layout get": {
     command: "displays layout get",
     accessLevel: "read",
@@ -2919,11 +2954,10 @@ var specificExamples = {
   ]),
   "navigation resources move": buildCommandExamples([
     {
-      description: "Move a schema into a navigation folder.",
-      command: "zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --type SCHEMA --to Sales",
+      description: "Move a schema into a navigation folder. Only schemas can be moved; the navigation menu holds databases.",
+      command: "zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --to Sales",
       raw: `{
   "resourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-  "resourceType": "SCHEMA",
   "targetFolderId": "84a0fca4-37ef-4c83-a8ed-9ef67ad9324a"
 }`,
       response: `{
@@ -2932,39 +2966,11 @@ var specificExamples = {
 }`
     },
     {
-      description: "Move a workflow.",
-      command: "zinkee --json navigation resources move 3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456 --type WORKFLOW --to Operations",
-      raw: `{
-  "resourceId": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-  "resourceType": "WORKFLOW",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`
-    },
-    {
-      description: "Move a display.",
-      command: "zinkee --json navigation resources move 0f6f062f-1478-4df2-96a1-c495d037d260 --type DISPLAY --to Operations",
-      raw: `{
-  "resourceId": "0f6f062f-1478-4df2-96a1-c495d037d260",
-  "resourceType": "DISPLAY",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`
-    },
-    {
-      description: "Move a resource back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
-      command: "zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --type SCHEMA --to 00000000-0000-0000-0000-000000000000",
+      description: "Move a schema back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
+      command: "zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --to 00000000-0000-0000-0000-000000000000",
       raw: `{
   "resourceId": "5223cbc8-8c6c-4694-93bc-dd176364df9b",
-  "resourceType": "SCHEMA",
   "targetFolderId": "00000000-0000-0000-0000-000000000000"
-}`
-    },
-    {
-      description: "Move a schedule resource.",
-      command: "zinkee --json navigation resources move a1b2c3d4-e5f6-7890-1234-567890abcdef --type SCHEDULE --to Operations",
-      raw: `{
-  "resourceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
-  "resourceType": "SCHEDULE",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
 }`
     }
   ]),
@@ -4453,7 +4459,7 @@ var specificExamples = {
     "resources": [
       {
         "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-        "name": "Contacts",
+        "name": "Customer records",
         "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
@@ -4477,19 +4483,10 @@ var specificExamples = {
     "resources": [
       {
         "id": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-        "name": "Quote approval",
-        "type": "WORKFLOW",
+        "name": "Shipments",
+        "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
-      },
-      {
-        "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
-        "name": "Executive Revenue",
-        "type": "DISPLAY",
-        "isInSpace": true,
-        "additionalProperties": {
-          "pinned": true
-        }
       }
     ],
     "additionalProperties": {
@@ -4536,8 +4533,13 @@ var specificExamples = {
     "name": "Shared Dashboards",
     "order": 1,
     "isRoot": false,
-    "resourceCount": 1,
+    "resourceCount": 2,
     "resources": [
+      {
+        "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+        "name": "Customer records",
+        "type": "SCHEMA"
+      },
       {
         "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
         "name": "Executive Revenue",
@@ -4756,6 +4758,83 @@ var specificExamples = {
       command: "zinkee --json displays delete 0f6f062f-1478-4df2-96a1-c495d037d260"
     }
   ]),
+  "displays folders list": buildCommandExamples([
+    {
+      description: "List flat display folders (non-root folders plus the root bucket).",
+      command: "zinkee --json displays folders list",
+      response: `[
+  {
+    "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+    "name": "Executive Dashboards",
+    "isRoot": false,
+    "displayCount": 2
+  },
+  {
+    "id": "8b22282b-3db3-4dd7-87f7-b29365dcf3f6",
+    "name": null,
+    "isRoot": true,
+    "displayCount": 4
+  }
+]`
+    }
+  ]),
+  "displays folders create": buildCommandExamples([
+    {
+      description: "Create one flat display folder.",
+      command: 'zinkee --json displays folders create --name "Executive Dashboards"',
+      raw: `{
+  "name": "Executive Dashboards"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 0
+}`
+    }
+  ]),
+  "displays folders update": buildCommandExamples([
+    {
+      description: "Rename a display folder. The folder argument accepts a UUID or an exact name.",
+      command: 'zinkee --json displays folders update "Executive Dashboards" --name "Executive Dashboards (2026)"',
+      raw: `{
+  "name": "Executive Dashboards (2026)"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards (2026)",
+  "isRoot": false,
+  "displayCount": 2
+}`
+    }
+  ]),
+  "displays folders delete": buildCommandExamples([
+    {
+      description: "Delete a non-root display folder. Its displays move back to the root folder.",
+      command: 'zinkee --json displays folders delete "Executive Dashboards"',
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 2
+}`
+    }
+  ]),
+  "displays folders move": buildCommandExamples([
+    {
+      description: "Move one display into a target folder by exact folder name.",
+      command: 'zinkee --json displays folders move 0f6f062f-1478-4df2-96a1-c495d037d260 --to "Executive Dashboards"',
+      raw: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "targetFolderId": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false
+}`
+    }
+  ]),
   "displays layout get": buildCommandExamples([
     {
       description: "Get the layout block of a display (template + tabs/freeformLayouts/slots).",
@@ -5769,7 +5848,8 @@ var specificExamples = {
       description: "Move one automation into a target folder by exact folder name.",
       command: 'zinkee --json automations folders move automation-1 --to "Codex Frontend Demo"',
       raw: `{
-  "automationId": "automation-1"
+  "automationId": "automation-1",
+  "targetFolderId": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f"
 }`,
       response: `{
   "id": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f",
@@ -6415,7 +6495,7 @@ var AutomationsApi = class {
   }
   moveAutomation(input) {
     return this.client.requestJson(
-      `/api/v2/automation-folders/${segment(input.targetFolderId)}/automations:move`,
+      "/api/v2/automation-folders/automations:move",
       jsonOptions(input, "POST")
     );
   }
@@ -7560,8 +7640,8 @@ function registerAutomationsCommands(program, options = {}) {
   const filePath = options.configPath ?? defaultConfigPath;
   const stdout = getCommandIo2(options.stdout);
   const automations = program.command("automations").description("Manage automations, triggers, actions, and connections");
-  const folders = automations.command("folders").description("Manage automation folders");
-  folders.command("list").description("List automation folders").action(async function action() {
+  const folders = automations.command("folders").description("Manage automation folders (flat: a folder only has a name, no order or properties)");
+  folders.command("list").description("List automation folders (non-root folders plus the root bucket, whose name is null)").action(async function action() {
     const { api, json } = createAutomationsApi(this, filePath);
     const data = await api.listFolders();
     if (json) {
@@ -7611,7 +7691,11 @@ function registerAutomationsCommands(program, options = {}) {
     }
     writeLine2(stdout, `Deleted automation folder "${folder.value}".`);
   });
-  folders.command("move").description("Move an automation into a folder").argument("<automation>", "automation UUID", parseUuidOrSlugSelector).requiredOption("--to <folder>", "target folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(automation, commandOptions) {
+  folders.command("move").description("Move an automation into a folder").argument("<automation>", "automation UUID", parseUuidOrSlugSelector).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (use the root folder to move it out of any folder)",
+    parseUuidOrSlugSelector
+  ).action(async function action(automation, commandOptions) {
     const { api, json, readOnly } = createAutomationsApi(this, filePath);
     ensureWritable("automations folders move", readOnly, "write");
     if (!commandOptions.to) {
@@ -8296,6 +8380,33 @@ var DisplaysApi = class {
       { method: "DELETE" }
     );
   }
+  listFolders() {
+    return this.client.getJson("/api/v2/display-folders");
+  }
+  createFolder(body) {
+    return this.client.requestJson(
+      "/api/v2/display-folders",
+      jsonOptions3(body, "POST")
+    );
+  }
+  updateFolder(folder, body) {
+    return this.client.requestJson(
+      `/api/v2/display-folders/${selectorValue3(folder)}`,
+      jsonOptions3(body, "PATCH")
+    );
+  }
+  deleteFolder(folder) {
+    return this.client.requestJson(
+      `/api/v2/display-folders/${selectorValue3(folder)}`,
+      { method: "DELETE" }
+    );
+  }
+  moveDisplay(input) {
+    return this.client.requestJson(
+      "/api/v2/display-folders/displays:move",
+      jsonOptions3(input, "POST")
+    );
+  }
 };
 
 // src/parsers/expressions.ts
@@ -8523,6 +8634,31 @@ function getDisplaySubresource(value) {
   }
   return value.filter((entry) => Boolean(entry) && typeof entry === "object");
 }
+function displayFolderRows(folders) {
+  return folders.map((folder) => ({
+    id: folder.id ?? "",
+    name: folder.name ?? "",
+    isRoot: folder.isRoot ?? "",
+    displayCount: folder.displayCount ?? ""
+  }));
+}
+async function resolveDisplayFolderId(api, selector) {
+  if (selector.kind === "uuid") {
+    return selector.value;
+  }
+  const folders = await api.listFolders();
+  const matches = folders.filter((folder) => folder.name === selector.value);
+  if (matches.length === 1 && typeof matches[0]?.id === "string" && matches[0].id.length > 0) {
+    return matches[0].id;
+  }
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`
+    );
+  }
+  throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+}
 function buildVariableBody(options) {
   const body = {
     ...readRawObject2(options.raw, options.rawFile)
@@ -8728,6 +8864,72 @@ function registerDisplaysCommands(program, options = {}) {
     }
     writeLine4(stdout, `Deleted display "${display.value}".`);
   });
+  const folders = displays.command("folders").description("Manage display folders (flat: a folder only has a name, no order or properties)");
+  folders.command("list").description("List display folders (non-root folders plus the root bucket, whose name is null)").action(async function action() {
+    const { api, json } = createDisplaysApi(this, filePath);
+    const data = await api.listFolders();
+    if (json) {
+      emitJson4(stdout, "displays folders list", data);
+      return;
+    }
+    printTable(displayFolderRows(data), ["id", "name", "isRoot", "displayCount"], stdout);
+  });
+  folders.command("create").description("Create a display folder").requiredOption("--name <name>", "folder name").action(async function action(commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders create", readOnly, "write");
+    if (commandOptions.name === void 0) {
+      throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+    }
+    const data = await api.createFolder({ name: commandOptions.name });
+    if (json) {
+      emitJson4(stdout, "displays folders create", data);
+      return;
+    }
+    writeLine4(stdout, `Created display folder "${String(data.name ?? commandOptions.name)}".`);
+  });
+  folders.command("update").description("Rename a display folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector3).requiredOption("--name <name>", "folder name").action(async function action(folder, commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders update", readOnly, "write");
+    if (commandOptions.name === void 0) {
+      throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+    }
+    const folderId = await resolveDisplayFolderId(api, folder);
+    const data = await api.updateFolder({ kind: "uuid", value: folderId }, { name: commandOptions.name });
+    if (json) {
+      emitJson4(stdout, "displays folders update", data);
+      return;
+    }
+    writeLine4(stdout, `Updated display folder "${String(data.name ?? folder.value)}".`);
+  });
+  folders.command("delete").description("Delete a display folder (its displays move back to the root folder)").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector3).action(async function action(folder) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders delete", readOnly, "destructive");
+    const folderId = await resolveDisplayFolderId(api, folder);
+    const data = await api.deleteFolder({ kind: "uuid", value: folderId });
+    if (json) {
+      emitJson4(stdout, "displays folders delete", data);
+      return;
+    }
+    writeLine4(stdout, `Deleted display folder "${folder.value}".`);
+  });
+  folders.command("move").description("Move a display into a folder").argument("<display>", "display UUID", parseUuidOrSlugSelector3).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (use the root folder to move it out of any folder)",
+    parseUuidOrSlugSelector3
+  ).action(async function action(display, commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders move", readOnly, "write");
+    if (!commandOptions.to) {
+      throw new CliError("invalid_cli_usage", 'Provide target folder via "--to".');
+    }
+    const targetFolderId = await resolveDisplayFolderId(api, commandOptions.to);
+    const data = await api.moveDisplay({ displayId: display.value, targetFolderId });
+    if (json) {
+      emitJson4(stdout, "displays folders move", data);
+      return;
+    }
+    writeLine4(stdout, `Moved display "${display.value}" to folder "${targetFolderId}".`);
+  });
   const layout = displays.command("layout").description("Manage display layout");
   layout.command("get").description("Get display layout").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).action(async function action(display) {
     const { api, json } = createDisplaysApi(this, filePath);
@@ -9901,7 +10103,7 @@ function registerNavigationCommands(program, options = {}) {
     }
     printTable(folderRows2([resolved]), ["id", "order", "name", "resourceCount"], stdout);
   });
-  folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "folder order").option("--props <json>", "folder additionalProperties JSON").option("--props-file <path>", "folder additionalProperties JSON file").action(async function action(commandOptions) {
+  folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation folders create", readOnly, "write");
     const data = await api.createFolder(buildFolderBody(commandOptions));
@@ -9911,7 +10113,7 @@ function registerNavigationCommands(program, options = {}) {
     }
     writeLine8(stdout, `Created navigation folder "${String(data.name ?? commandOptions.name)}".`);
   });
-  folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector7).option("--name <name>", "folder name").option("--order <n>", "folder order").option("--props <json>", "folder additionalProperties JSON").option("--props-file <path>", "folder additionalProperties JSON file").action(async function action(folder, commandOptions) {
+  folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector7).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation folders update", readOnly, "write");
     const allFolders = await api.listFolders();
@@ -9939,14 +10141,15 @@ function registerNavigationCommands(program, options = {}) {
     }
     writeLine8(stdout, `Deleted navigation folder "${resolved.name ?? resolved.id}".`);
   });
-  navigation.command("resources").description("Manage navigation resources").command("move").description("Move a resource into a folder").argument("<resource>", "resource UUID").requiredOption("--type <type>", "resource type").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
+  navigation.command("resources").description("Manage navigation resources").command("move").description(
+    "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use the root folder UUID 00000000-0000-0000-0000-000000000000 to move it back to the workspace root."
+  ).argument("<resource>", "schema UUID").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation resources move", readOnly, "write");
     const allFolders = await api.listFolders();
     const resolved = resolveFolder2(allFolders, parseUuidOrSlugSelector7(commandOptions.to));
     const data = await api.moveResource({
       resourceId,
-      resourceType: commandOptions.type.toUpperCase(),
       targetFolderId: resolved.id
     });
     if (json) {
@@ -11479,7 +11682,7 @@ function registerTeamspaceCommands(program, options = {}) {
   const stdout = getCommandIo12(options.stdout);
   const teamspace = program.command("teamspace").description("Manage teamspace folders and resources");
   const folders = teamspace.command("folders").description("Manage teamspace folders");
-  folders.command("list").description("List teamspace folders").option("--include-resources", "include nested resources").action(async function action(commandOptions) {
+  folders.command("list").description("List teamspace folders").option("--include-resources", "include the published resources inside each folder").action(async function action(commandOptions) {
     const { api, json } = createTeamspaceApi(this, filePath);
     const data = await api.listFolders(Boolean(commandOptions.includeResources));
     if (json) {
@@ -11488,7 +11691,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     emitTable5(stdout, data);
   });
-  folders.command("get").description("Get a teamspace folder by exact name or UUID").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--include-resources", "include nested resources").action(async function action(folder, commandOptions) {
+  folders.command("get").description("Get a teamspace folder by exact name or UUID").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--include-resources", "include the published resources inside each folder").action(async function action(folder, commandOptions) {
     const { api, json } = createTeamspaceApi(this, filePath);
     const resolvedFolder = await resolveFolderSelector2(api, folder);
     const allFolders = await api.listFolders(Boolean(commandOptions.includeResources));
@@ -11499,7 +11702,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     emitTable5(stdout, data);
   });
-  folders.command("create").description("Create a teamspace folder").requiredOption("--name <name>", "folder name").option("--order <n>", "folder order", parseNonNegativeInteger3).option("--props <json>", "folder properties payload").option("--props-file <path>", "path to a folder properties JSON payload").action(async function action(commandOptions) {
+  folders.command("create").description("Create a teamspace folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger3).option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"icon":"folder-users","color":"gold"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace folders create", readOnly, "write");
     const data = await api.createFolder(buildFolderCreateInput(commandOptions));
@@ -11509,7 +11712,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     writeLine12(stdout, `Created folder "${getFolderIdentifier(data)}".`);
   });
-  folders.command("update").description("Update a teamspace folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--name <name>", "folder name").option("--order <n>", "folder order", parseNonNegativeInteger3).option("--props <json>", "folder properties payload").option("--props-file <path>", "path to a folder properties JSON payload").action(async function action(folder, commandOptions) {
+  folders.command("update").description("Update a teamspace folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger3).option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"icon":"folder-users","color":"gold"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace folders update", readOnly, "write");
     const resolvedFolder = await resolveFolderSelector2(api, folder);
@@ -11532,7 +11735,13 @@ function registerTeamspaceCommands(program, options = {}) {
     writeLine12(stdout, `Deleted folder "${resolvedFolder.value}".`);
   });
   const resources = teamspace.command("resources").description("Manage teamspace resources");
-  resources.command("publish").description("Publish a resource to a teamspace folder").argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector10).requiredOption("--to <folder>", "target folder", parseUuidOrSlugSelector10).action(async function action(resource, commandOptions) {
+  resources.command("publish").description(
+    "Publish a resource to a teamspace folder. Publishing an already-published resource moves it to the new folder."
+  ).argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector10).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (root folder UUID is 00000000-0000-0000-0000-000000000000)",
+    parseUuidOrSlugSelector10
+  ).action(async function action(resource, commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace resources publish", readOnly, "write");
     const folder = await resolveFolderSelector2(api, commandOptions.to);
@@ -11546,7 +11755,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     writeLine12(stdout, `Published resource "${resource.value}" to folder "${folder.value}".`);
   });
-  resources.command("unpublish").description("Unpublish a resource from teamspace").argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector10).action(async function action(resource) {
+  resources.command("unpublish").description("Unpublish a resource from teamspace (removes it from its shared folder)").argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector10).action(async function action(resource) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace resources unpublish", readOnly, "write");
     const data = await api.unpublishResource(resource.value);