dataiku-sdk 0.8.0 → 0.10.0

package/dist/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash, } from "node:crypto";
-import { readFileSync, } from "node:fs";
+import { readFileSync, writeFileSync, } from "node:fs";
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve, } from "node:path";
 import { fileURLToPath, } from "node:url";
@@ -72,6 +72,9 @@ function gitRevision(packageRoot) {
 const PACKAGE_ROOT = findPackageRoot();
 const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
+const AGENT_CONTRACT_VERSION = 1;
+const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v1.json";
 function cliVersionResult() {
     return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
 }
@@ -1064,7 +1067,7 @@ function resolveSqlInput(args, flags) {
     }
     return query;
 }
-const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--project-key KEY]";
+const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--max-log-bytes N] [--project-key KEY]";
 function resolveCodeInput(args, flags) {
     if (args.length > 0) {
         throw new UsageError(`code run takes no positional arguments; pass the script via --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
@@ -1128,13 +1131,13 @@ let pendingCliWarnings = [];
 function enqueueCliWarning(warning) {
     pendingCliWarnings.push(warning);
 }
-/** Emit queued warnings as a single `{ warnings: [...] }` object on stderr. Idempotent. */
+/** Emit queued warnings as one JSONL warning event on stderr. Idempotent. */
 function flushCliWarnings() {
     if (pendingCliWarnings.length === 0)
         return;
     const warnings = pendingCliWarnings;
     pendingCliWarnings = [];
-    process.stderr.write(`${JSON.stringify({ warnings, }, null, 2)}\n`);
+    process.stderr.write(`${JSON.stringify({ type: "warning", warnings, })}\n`);
 }
 function resolveFieldPath(source, field) {
     let current = source;
@@ -1499,6 +1502,7 @@ const BOOLEAN_FLAGS = new Set([
     "errors-only",
     "keep",
     "full-log",
+    "drop-data",
 ]);
 const SHORT_FLAGS = {
     v: "verbose",
@@ -1517,6 +1521,12 @@ const FLAG_ALIASES = {
 };
 const VALUE_FLAGS = new Set([
     "fields",
+    "owner",
+    "topic",
+    "reply",
+    "text",
+    "partitions",
+    "since",
     "activity",
     "agent",
     "api-key",
@@ -1554,6 +1564,7 @@ const VALUE_FLAGS = new Set([
     "max-edges",
     "max-lines",
     "max-log-lines",
+    "max-log-bytes",
     "listed",
     "max-nodes",
     "max-rows",
@@ -1748,6 +1759,1227 @@ const commands = {
                 "dss project map --include-raw",
             ],
         },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss project create <projectKey> <name> [--owner LOGIN] [--data JSON|--data-file PATH|--stdin]");
+                return c.projects.createProject(a[0], a[1], f["owner"], jsonInput(f));
+            },
+            usage: "dss project create <projectKey> <name> [--owner LOGIN] [--data JSON|--data-file PATH|--stdin]",
+            description: "Create a new project (optionally with owner login and settings).",
+            examples: ["dss project create MY_PROJ MyProject",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project delete <projectKey> [--drop-data]");
+                await c.projects.deleteProject(a[0], f["drop-data"] === true);
+                return { deleted: a[0], };
+            },
+            usage: "dss project delete <projectKey> [--drop-data]",
+            description: "Delete a project (destructive). --drop-data also clears managed datasets.",
+            examples: ["dss project delete MY_PROJ",],
+        },
+        duplicate: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss project duplicate <sourceKey> <targetKey> <targetName> [--data JSON|--data-file PATH|--stdin]");
+                return c.projects.duplicate(a[0], a[1], a[2], jsonInput(f));
+            },
+            usage: "dss project duplicate <sourceKey> <targetKey> <targetName> [--data JSON|--data-file PATH|--stdin]",
+            description: "Duplicate a project into a new project key.",
+            examples: ["dss project duplicate SRC NEW NewProject",],
+        },
+        export: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project export <projectKey> --output PATH [--data JSON|--data-file PATH|--stdin]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                await c.projects.exportArchive(a[0], out, jsonInput(f));
+                return { path: out, };
+            },
+            usage: "dss project export <projectKey> --output PATH [--data JSON|--data-file PATH|--stdin]",
+            description: "Export a project to a local archive (.zip).",
+            examples: ["dss project export MY_PROJ --output ./my_proj.zip",],
+        },
+        import: {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project import <filePath>");
+                return c.projects.importProjectFromArchive(a[0]);
+            },
+            usage: "dss project import <filePath>",
+            description: "Upload a project archive to prepare an import (returns a temporary import id).",
+            examples: ["dss project import ./my_proj.zip",],
+        },
+        "permissions-get": {
+            handler: (c, _a, f) => c.projects.getPermissions(f["project-key"]),
+            usage: "dss project permissions-get [--project-key KEY]",
+            description: "Get a project's permissions.",
+            examples: ["dss project permissions-get --project-key MY_PROJ",],
+        },
+        "permissions-set": {
+            handler: async (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (permissions object).");
+                await c.projects.setPermissions(f["project-key"], body);
+                return { updated: true, };
+            },
+            usage: "dss project permissions-set (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a project's permissions.",
+            examples: ["dss project permissions-set --data-file perms.json --project-key MY_PROJ",],
+        },
+        "settings-get": {
+            handler: (c, _a, f) => c.projects.getSettings(f["project-key"]),
+            usage: "dss project settings-get [--project-key KEY]",
+            description: "Get a project's settings.",
+            examples: ["dss project settings-get --project-key MY_PROJ",],
+        },
+        "settings-set": {
+            handler: async (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (settings object).");
+                await c.projects.setSettings(f["project-key"], body);
+                return { updated: true, };
+            },
+            usage: "dss project settings-set (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a project's settings.",
+            examples: ["dss project settings-set --data-file settings.json --project-key MY_PROJ",],
+        },
+    },
+    app: {
+        list: {
+            handler: (c) => c.applications.listApps(),
+            usage: "dss app list",
+            description: "List all Dataiku App templates.",
+            examples: ["dss app list",],
+        },
+        manifest: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss app manifest <appId>");
+                return c.applications.getAppManifest(a[0]);
+            },
+            usage: "dss app manifest <appId>",
+            description: "Get the manifest of a Dataiku App template.",
+            examples: ["dss app manifest my-app",],
+        },
+        instances: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss app instances <appId>");
+                return c.applications.listInstances(a[0]);
+            },
+            usage: "dss app instances <appId>",
+            description: "List instances created from a Dataiku App template.",
+            examples: ["dss app instances my-app",],
+        },
+        "create-instance": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (instance creation payload).");
+                return c.applications.createInstance(a[0], body);
+            },
+            usage: "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an app instance from a Dataiku App template.",
+            examples: ['dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\'',],
+        },
+        "instance-manifest": {
+            handler: (c, _a, f) => c.applications.getInstanceManifest(f["project-key"]),
+            usage: "dss app instance-manifest [--project-key KEY]",
+            description: "Get the app manifest of an app-instance project.",
+            examples: ["dss app instance-manifest --project-key MYINSTANCE",],
+        },
+        "save-instance-manifest": {
+            handler: (c, _a, f) => {
+                const manifest = requiredJsonInput(f, "--data, --data-file, or --stdin is required (manifest JSON).");
+                return c.applications.saveInstanceManifest(manifest, f["project-key"]);
+            },
+            usage: "dss app save-instance-manifest (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Save the app manifest of an app-instance project (homepage sections, use-as-recipe settings).",
+            examples: ["dss app save-instance-manifest --data-file manifest.json --project-key MYINSTANCE",],
+        },
+        "delete-instance": {
+            handler: async (c, _a, f) => {
+                await c.applications.deleteInstance(f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss app delete-instance [--project-key KEY]",
+            description: "Delete an app-instance project (destructive: removes the instance project).",
+            examples: ["dss app delete-instance --project-key MYINSTANCE",],
+        },
+        "business-app-instance-permissions": {
+            handler: (c, a) => {
+                requireArgs(a, 3, "dss app business-app-instance-permissions <businessAppId> <instanceProjectKey> <userLogin>");
+                return c.applications.getBusinessAppInstanceUserPermissions(a[0], a[1], a[2]);
+            },
+            usage: "dss app business-app-instance-permissions <businessAppId> <instanceProjectKey> <userLogin>",
+            description: "Get a user's effective permissions on a Business App instance.",
+            examples: ["dss app business-app-instance-permissions my-bapp INSTANCEPROJ alice",],
+        },
+    },
+    "business-app": {
+        list: {
+            handler: (c) => c.applications.listBusinessApps(),
+            usage: "dss business-app list",
+            description: "List all Business Apps.",
+            examples: ["dss business-app list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app get <id>");
+                return c.applications.getBusinessApp(a[0]);
+            },
+            usage: "dss business-app get <id>",
+            description: "Get Business App details.",
+            examples: ["dss business-app get my-bapp",],
+        },
+        settings: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app settings <id>");
+                return c.applications.getBusinessAppSettings(a[0]);
+            },
+            usage: "dss business-app settings <id>",
+            description: "Get Business App settings.",
+            examples: ["dss business-app settings my-bapp",],
+        },
+        "save-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss business-app save-settings <id> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (settings JSON).");
+                return c.applications.saveBusinessAppSettings(a[0], body);
+            },
+            usage: "dss business-app save-settings <id> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save Business App settings (admin only; includes connection remapping).",
+            examples: ["dss business-app save-settings my-bapp --data-file settings.json",],
+        },
+        instances: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss business-app instances <id>");
+                return c.applications.listBusinessAppInstances(a[0]);
+            },
+            usage: "dss business-app instances <id>",
+            description: "List instances of a Business App.",
+            examples: ["dss business-app instances my-bapp",],
+        },
+        "create-instance": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss business-app create-instance <id> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (instance payload).");
+                return c.applications.createBusinessAppInstance(a[0], body);
+            },
+            usage: "dss business-app create-instance <id> (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an instance of a Business App.",
+            examples: ["dss business-app create-instance my-bapp --data '{}'",],
+        },
+        "upgrade-instance": {
+            handler: (c, a) => {
+                requireArgs(a, 2, "dss business-app upgrade-instance <id> <projectKey>");
+                return c.applications.upgradeBusinessAppInstance(a[0], a[1]);
+            },
+            usage: "dss business-app upgrade-instance <id> <projectKey>",
+            description: "Upgrade a Business App instance to the latest version.",
+            examples: ["dss business-app upgrade-instance my-bapp INSTANCEPROJ",],
+        },
+        "install-from-archive": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss business-app install-from-archive <filePath>");
+                await c.applications.installBusinessAppFromArchive(a[0]);
+                return { installed: true, };
+            },
+            usage: "dss business-app install-from-archive <filePath>",
+            description: "Install or upgrade a Business App from a zip archive (admin only).",
+            examples: ["dss business-app install-from-archive ./my-bapp.zip",],
+        },
+    },
+    webapp: {
+        list: {
+            handler: (c, _a, f) => c.webapps.list(f["project-key"]),
+            usage: "dss webapp list [--project-key KEY]",
+            description: "List webapps in a project.",
+            examples: ["dss webapp list",],
+        },
+        "get-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp get-settings <webappId> [--project-key KEY]");
+                return c.webapps.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss webapp get-settings <webappId> [--project-key KEY]",
+            description: "Get a webapp's settings.",
+            examples: ["dss webapp get-settings WEBAPP_ID",],
+        },
+        create: {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp definition).");
+                return c.webapps.create(body, f["project-key"]);
+            },
+            usage: "dss webapp create (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Create a webapp from a JSON definition.",
+            examples: ["dss webapp create --data-file webapp.json",],
+        },
+        "update-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp settings).");
+                return c.webapps.updateSettings(a[0], body, f["project-key"]);
+            },
+            usage: "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a webapp's settings.",
+            examples: ["dss webapp update-settings WEBAPP_ID --data-file webapp.json",],
+        },
+        "stop-backend": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss webapp stop-backend <webappId> [--project-key KEY]");
+                await c.webapps.stopBackend(a[0], f["project-key"]);
+                return { stopped: true, };
+            },
+            usage: "dss webapp stop-backend <webappId> [--project-key KEY]",
+            description: "Stop a webapp's backend.",
+            examples: ["dss webapp stop-backend WEBAPP_ID",],
+        },
+        "restart-backend": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss webapp restart-backend <webappId> [--project-key KEY]");
+                await c.webapps.startOrRestartBackend(a[0], f["project-key"]);
+                return { restarted: true, };
+            },
+            usage: "dss webapp restart-backend <webappId> [--project-key KEY]",
+            description: "Start or restart a webapp's backend.",
+            examples: ["dss webapp restart-backend WEBAPP_ID",],
+        },
+        "backend-state": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss webapp backend-state <webappId> [--project-key KEY]");
+                return c.webapps.getBackendState(a[0], f["project-key"]);
+            },
+            usage: "dss webapp backend-state <webappId> [--project-key KEY]",
+            description: "Get a webapp backend's runtime state.",
+            examples: ["dss webapp backend-state WEBAPP_ID",],
+        },
+    },
+    "api-service": {
+        list: {
+            handler: (c, _a, f) => c.apiServices.list(f["project-key"]),
+            usage: "dss api-service list [--project-key KEY]",
+            description: "List API services in a project.",
+            examples: ["dss api-service list",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service create <serviceId> [--project-key KEY]");
+                return c.apiServices.create(a[0], f["project-key"]);
+            },
+            usage: "dss api-service create <serviceId> [--project-key KEY]",
+            description: "Create an empty API service.",
+            examples: ["dss api-service create my-service",],
+        },
+        "get-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service get-settings <serviceId> [--project-key KEY]");
+                return c.apiServices.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss api-service get-settings <serviceId> [--project-key KEY]",
+            description: "Get an API service's settings (endpoint definitions).",
+            examples: ["dss api-service get-settings my-service",],
+        },
+        "save-settings": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service settings).");
+                return c.apiServices.saveSettings(a[0], body, f["project-key"]);
+            },
+            usage: "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Save an API service's settings.",
+            examples: ["dss api-service save-settings my-service --data-file service.json",],
+        },
+        "list-packages": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss api-service list-packages <serviceId> [--project-key KEY]");
+                return c.apiServices.listPackages(a[0], f["project-key"]);
+            },
+            usage: "dss api-service list-packages <serviceId> [--project-key KEY]",
+            description: "List deployable packages of an API service.",
+            examples: ["dss api-service list-packages my-service",],
+        },
+        "package-summary": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service package-summary <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.getPackageSummary(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service package-summary <serviceId> <packageId> [--project-key KEY]",
+            description: "Get a package summary.",
+            examples: ["dss api-service package-summary my-service v1",],
+        },
+        "create-package": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service create-package <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.createPackage(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service create-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Build a deployable package from the current service state.",
+            examples: ["dss api-service create-package my-service v1",],
+        },
+        "delete-package": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss api-service delete-package <serviceId> <packageId> [--project-key KEY]");
+                await c.apiServices.deletePackage(a[0], a[1], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss api-service delete-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Delete an API service package.",
+            examples: ["dss api-service delete-package my-service v1",],
+        },
+        "download-package": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const res = await c.apiServices.downloadPackageArchive(a[0], a[1], f["project-key"]);
+                const buf = Buffer.from(await res.arrayBuffer());
+                writeFileSync(out, buf);
+                return { path: out, bytes: buf.length, };
+            },
+            usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",
+            description: "Download an API service package archive to a local file.",
+            examples: ["dss api-service download-package my-service v1 --output ./pkg.zip",],
+        },
+        "publish-package": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]");
+                return c.apiServices.publishPackage(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]",
+            description: "Publish a package to the API Deployer.",
+            examples: ["dss api-service publish-package my-service v1",],
+        },
+    },
+    "api-deployer": {
+        "list-infras": {
+            handler: (c) => c.apiDeployer.listInfras(),
+            usage: "dss api-deployer list-infras",
+            description: "List API Deployer infrastructures.",
+            examples: ["dss api-deployer list-infras",],
+        },
+        "create-infra": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (infra settings).");
+                return c.apiDeployer.createInfra(body);
+            },
+            usage: "dss api-deployer create-infra (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an API Deployer infrastructure.",
+            examples: ["dss api-deployer create-infra --data-file infra.json",],
+        },
+        "get-infra": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-infra <infraId>");
+                return c.apiDeployer.getInfra(a[0]);
+            },
+            usage: "dss api-deployer get-infra <infraId>",
+            description: "Get an API Deployer infrastructure status.",
+            examples: ["dss api-deployer get-infra prod-infra",],
+        },
+        "delete-infra": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-infra <infraId>");
+                await c.apiDeployer.deleteInfra(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-infra <infraId>",
+            description: "Delete an API Deployer infrastructure.",
+            examples: ["dss api-deployer delete-infra prod-infra",],
+        },
+        "list-stages": {
+            handler: (c) => c.apiDeployer.listStages(),
+            usage: "dss api-deployer list-stages",
+            description: "List API Deployer lifecycle stages.",
+            examples: ["dss api-deployer list-stages",],
+        },
+        "list-services": {
+            handler: (c) => c.apiDeployer.listServices(),
+            usage: "dss api-deployer list-services",
+            description: "List published API Deployer services.",
+            examples: ["dss api-deployer list-services",],
+        },
+        "create-service": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service definition).");
+                return c.apiDeployer.createService(body);
+            },
+            usage: "dss api-deployer create-service (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a published API Deployer service.",
+            examples: ['dss api-deployer create-service --data \'{"id":"my-service"}\'',],
+        },
+        "get-service": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-service <serviceId>");
+                return c.apiDeployer.getService(a[0]);
+            },
+            usage: "dss api-deployer get-service <serviceId>",
+            description: "Get a published service's status (versions + deployments).",
+            examples: ["dss api-deployer get-service my-service",],
+        },
+        "delete-service": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-service <serviceId>");
+                await c.apiDeployer.deleteService(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-service <serviceId>",
+            description: "Delete a published API Deployer service.",
+            examples: ["dss api-deployer delete-service my-service",],
+        },
+        "publish-version": {
+            handler: async (c, a) => {
+                requireArgs(a, 2, "dss api-deployer publish-version <serviceId> <archive.zip>");
+                await c.apiDeployer.publishServiceVersion(a[0], a[1]);
+                return { published: true, };
+            },
+            usage: "dss api-deployer publish-version <serviceId> <archive.zip>",
+            description: "Publish (upload) a service version package to the API Deployer.",
+            examples: ["dss api-deployer publish-version my-service ./pkg.zip",],
+        },
+        "delete-version": {
+            handler: async (c, a) => {
+                requireArgs(a, 2, "dss api-deployer delete-version <serviceId> <version>");
+                await c.apiDeployer.deleteServiceVersion(a[0], a[1]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-version <serviceId> <version>",
+            description: "Delete a published service version.",
+            examples: ["dss api-deployer delete-version my-service v1",],
+        },
+        "list-deployments": {
+            handler: (c) => c.apiDeployer.listDeployments(),
+            usage: "dss api-deployer list-deployments",
+            description: "List API Deployer deployments.",
+            examples: ["dss api-deployer list-deployments",],
+        },
+        "create-deployment": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                return c.apiDeployer.createDeployment(body);
+            },
+            usage: "dss api-deployer create-deployment (--data JSON|--data-file PATH|--stdin)",
+            description: "Create an API Deployer deployment (maps a service version to an infra).",
+            examples: ["dss api-deployer create-deployment --data-file deployment.json",],
+        },
+        "get-deployment": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer get-deployment <deploymentId>");
+                return c.apiDeployer.getDeployment(a[0]);
+            },
+            usage: "dss api-deployer get-deployment <deploymentId>",
+            description: "Get an API Deployer deployment.",
+            examples: ["dss api-deployer get-deployment my-deployment",],
+        },
+        "deployment-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deployment-status <deploymentId>");
+                return c.apiDeployer.getDeploymentStatus(a[0]);
+            },
+            usage: "dss api-deployer deployment-status <deploymentId>",
+            description: "Get an API Deployer deployment's full health/status.",
+            examples: ["dss api-deployer deployment-status my-deployment",],
+        },
+        "deployment-settings": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deployment-settings <deploymentId>");
+                return c.apiDeployer.getDeploymentSettings(a[0]);
+            },
+            usage: "dss api-deployer deployment-settings <deploymentId>",
+            description: "Get an API Deployer deployment's settings.",
+            examples: ["dss api-deployer deployment-settings my-deployment",],
+        },
+        "save-deployment-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss api-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                await c.apiDeployer.saveDeploymentSettings(a[0], body);
+                return { saved: true, };
+            },
+            usage: "dss api-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save an API Deployer deployment's settings.",
+            examples: ["dss api-deployer save-deployment-settings my-deployment --data-file settings.json",],
+        },
+        deploy: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss api-deployer deploy <deploymentId>");
+                return c.apiDeployer.startDeploymentUpdate(a[0]);
+            },
+            usage: "dss api-deployer deploy <deploymentId>",
+            description: "Apply a deployment's settings to its infrastructure (start update).",
+            examples: ["dss api-deployer deploy my-deployment",],
+        },
+        "delete-deployment": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss api-deployer delete-deployment <deploymentId>");
+                await c.apiDeployer.deleteDeployment(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss api-deployer delete-deployment <deploymentId>",
+            description: "Delete an API Deployer deployment.",
+            examples: ["dss api-deployer delete-deployment my-deployment",],
+        },
+    },
+    bundle: {
+        "list-exported": {
+            handler: (c, _a, f) => c.bundles.listExported(f["project-key"]),
+            usage: "dss bundle list-exported [--project-key KEY]",
+            description: "List bundles exported from a project on the Design node.",
+            examples: ["dss bundle list-exported",],
+        },
+        export: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle export <bundleId> [--project-key KEY]");
+                await c.bundles.exportBundle(a[0], f["project-key"]);
+                return { exported: a[0], };
+            },
+            usage: "dss bundle export <bundleId> [--project-key KEY]",
+            description: "Create (or overwrite) an exported Design-node bundle.",
+            examples: ["dss bundle export v1",],
+        },
+        "delete-exported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle delete-exported <bundleId> [--project-key KEY]");
+                await c.bundles.deleteExported(a[0], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss bundle delete-exported <bundleId> [--project-key KEY]",
+            description: "Delete an exported Design-node bundle.",
+            examples: ["dss bundle delete-exported v1",],
+        },
+        "download-exported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const res = await c.bundles.downloadExportedArchive(a[0], f["project-key"]);
+                const buf = Buffer.from(await res.arrayBuffer());
+                writeFileSync(out, buf);
+                return { path: out, bytes: buf.length, };
+            },
+            usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",
+            description: "Download an exported Design-node bundle archive to a local file.",
+            examples: ["dss bundle download-exported v1 --output ./bundle.zip",],
+        },
+        publish: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle publish <bundleId> [--project-key KEY]");
+                return c.bundles.publish(a[0], f["project-key"]);
+            },
+            usage: "dss bundle publish <bundleId> [--project-key KEY]",
+            description: "Publish a Design-node bundle to the Project Deployer.",
+            examples: ["dss bundle publish v1",],
+        },
+        "list-imported": {
+            handler: (c, _a, f) => c.bundles.listImported(f["project-key"]),
+            usage: "dss bundle list-imported [--project-key KEY]",
+            description: "List bundles imported into a project on the Automation node.",
+            examples: ["dss bundle list-imported",],
+        },
+        "import-from-archive": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle import-from-archive <serverArchivePath> [--project-key KEY]");
+                return c.bundles.importFromArchive(a[0], f["project-key"]);
+            },
+            usage: "dss bundle import-from-archive <serverArchivePath> [--project-key KEY]",
+            description: "Import a server-side bundle archive into an Automation-node project.",
+            examples: ["dss bundle import-from-archive /data/bundles/v1.zip",],
+        },
+        "import-from-stream": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle import-from-stream <filePath> [--project-key KEY]");
+                await c.bundles.importFromStream(a[0], f["project-key"]);
+                return { imported: true, };
+            },
+            usage: "dss bundle import-from-stream <filePath> [--project-key KEY]",
+            description: "Upload and import a local bundle archive into an Automation-node project.",
+            examples: ["dss bundle import-from-stream ./v1.zip",],
+        },
+        activate: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle activate <bundleId> [--project-key KEY]");
+                return c.bundles.activate(a[0], f["project-key"]);
+            },
+            usage: "dss bundle activate <bundleId> [--project-key KEY]",
+            description: "Activate an imported Automation-node bundle.",
+            examples: ["dss bundle activate v1",],
+        },
+        preload: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss bundle preload <bundleId> [--project-key KEY]");
+                return c.bundles.preload(a[0], f["project-key"]);
+            },
+            usage: "dss bundle preload <bundleId> [--project-key KEY]",
+            description: "Preload an imported Automation-node bundle (stage data/models).",
+            examples: ["dss bundle preload v1",],
+        },
+        "delete-imported": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss bundle delete-imported <bundleId> [--project-key KEY]");
+                await c.bundles.deleteImported(a[0], f["project-key"]);
+                return { deleted: true, };
+            },
+            usage: "dss bundle delete-imported <bundleId> [--project-key KEY]",
+            description: "Delete an imported Automation-node bundle.",
+            examples: ["dss bundle delete-imported v1",],
+        },
+    },
+    "project-deployer": {
+        "list-projects": {
+            handler: (c) => c.projectDeployer.listProjects(),
+            usage: "dss project-deployer list-projects",
+            description: "List published projects on the Project Deployer.",
+            examples: ["dss project-deployer list-projects",],
+        },
+        "create-project": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (published project settings).");
+                return c.projectDeployer.createProject(body);
+            },
+            usage: "dss project-deployer create-project (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a published project on the Project Deployer.",
+            examples: ["dss project-deployer create-project --data-file project.json",],
+        },
+        "upload-bundle": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project-deployer upload-bundle <filePath>");
+                await c.projectDeployer.uploadBundle(a[0]);
+                return { uploaded: true, };
+            },
+            usage: "dss project-deployer upload-bundle <filePath>",
+            description: "Upload a project bundle archive to the Project Deployer.",
+            examples: ["dss project-deployer upload-bundle ./v1.zip",],
+        },
+        "project-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer project-status <publishedProjectKey>");
+                return c.projectDeployer.getProjectStatus(a[0]);
+            },
+            usage: "dss project-deployer project-status <publishedProjectKey>",
+            description: "Get a published project's status and available bundles.",
+            examples: ["dss project-deployer project-status MYPROJ",],
+        },
+        "list-deployments": {
+            handler: (c) => c.projectDeployer.listDeployments(),
+            usage: "dss project-deployer list-deployments",
+            description: "List Project Deployer deployments.",
+            examples: ["dss project-deployer list-deployments",],
+        },
+        "create-deployment": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                return c.projectDeployer.createDeployment(body);
+            },
+            usage: "dss project-deployer create-deployment (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a Project Deployer deployment (bundle to infra mapping).",
+            examples: ["dss project-deployer create-deployment --data-file deployment.json",],
+        },
+        "get-deployment": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer get-deployment <deploymentId>");
+                return c.projectDeployer.getDeployment(a[0]);
+            },
+            usage: "dss project-deployer get-deployment <deploymentId>",
+            description: "Get a Project Deployer deployment.",
+            examples: ["dss project-deployer get-deployment my-deployment",],
+        },
+        "deployment-status": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer deployment-status <deploymentId>");
+                return c.projectDeployer.getDeploymentStatus(a[0]);
+            },
+            usage: "dss project-deployer deployment-status <deploymentId>",
+            description: "Get a Project Deployer deployment's full health/status.",
+            examples: ["dss project-deployer deployment-status my-deployment",],
+        },
+        "save-deployment-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (deployment settings).");
+                await c.projectDeployer.saveDeploymentSettings(a[0], body);
+                return { saved: true, };
+            },
+            usage: "dss project-deployer save-deployment-settings <deploymentId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Save a Project Deployer deployment's settings (e.g. bundleId).",
+            examples: [
+                "dss project-deployer save-deployment-settings my-deployment --data-file settings.json",
+            ],
+        },
+        deploy: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss project-deployer deploy <deploymentId>");
+                return c.projectDeployer.startUpdate(a[0]);
+            },
+            usage: "dss project-deployer deploy <deploymentId>",
+            description: "Apply a deployment to the Automation node (start update).",
+            examples: ["dss project-deployer deploy my-deployment",],
+        },
+        "delete-deployment": {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss project-deployer delete-deployment <deploymentId>");
+                await c.projectDeployer.deleteDeployment(a[0]);
+                return { deleted: true, };
+            },
+            usage: "dss project-deployer delete-deployment <deploymentId>",
+            description: "Delete a Project Deployer deployment.",
+            examples: ["dss project-deployer delete-deployment my-deployment",],
+        },
+        "list-infras": {
+            handler: (c) => c.projectDeployer.listInfras(),
+            usage: "dss project-deployer list-infras",
+            description: "List Project Deployer infrastructures.",
+            examples: ["dss project-deployer list-infras",],
+        },
+        "create-infra": {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (infra settings).");
+                return c.projectDeployer.createInfra(body);
+            },
+            usage: "dss project-deployer create-infra (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a Project Deployer infrastructure.",
+            examples: ["dss project-deployer create-infra --data-file infra.json",],
+        },
+    },
+    "project-library": {
+        list: {
+            handler: (c, _a, f) => c.projectLibrary.listContents(f["project-key"]),
+            usage: "dss project-library list [--project-key KEY]",
+            description: "List the project code library (lib/) contents.",
+            examples: ["dss project-library list",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss project-library get <path> [--project-key KEY]");
+                return c.projectLibrary.getFile(a[0], f["project-key"]);
+            },
+            usage: "dss project-library get <path> [--project-key KEY]",
+            description: "Print the text content of a project library file.",
+            examples: ["dss project-library get python/mylib/utils.py",],
+        },
+        "get-bytes": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library get-bytes <path> --output PATH [--project-key KEY]");
+                const out = f["output"];
+                if (!out)
+                    throw new UsageError("--output PATH is required.", "missing_required_flag");
+                const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
+                writeFileSync(out, bytes);
+                return { path: out, bytes: bytes.length, };
+            },
+            usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
+            description: "Download a project library file's raw bytes to a local file.",
+            examples: ["dss project-library get-bytes static/logo.png --output ./logo.png",],
+        },
+        "create-file": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library create-file <path> [--project-key KEY]");
+                await c.projectLibrary.addFile(a[0], f["project-key"]);
+                return { created: a[0], };
+            },
+            usage: "dss project-library create-file <path> [--project-key KEY]",
+            description: "Create an empty file in the project library.",
+            examples: ["dss project-library create-file python/mylib/new.py",],
+        },
+        "create-folder": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library create-folder <path> [--project-key KEY]");
+                await c.projectLibrary.addFolder(a[0], f["project-key"]);
+                return { created: a[0], };
+            },
+            usage: "dss project-library create-folder <path> [--project-key KEY]",
+            description: "Create a folder in the project library.",
+            examples: ["dss project-library create-folder python/mylib",],
+        },
+        put: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--project-key KEY]");
+                const content = typeof f["content"] === "string"
+                    ? f["content"]
+                    : typeof f["file"] === "string"
+                        ? readFileSync(f["file"], "utf-8")
+                        : await readStdinText();
+                await c.projectLibrary.addOrUpdateFile(a[0], content, f["project-key"]);
+                return { updated: a[0], };
+            },
+            usage: "dss project-library put <path> (--content TEXT|--file PATH|--stdin) [--project-key KEY]",
+            description: "Create or overwrite a project library file with raw text content.",
+            examples: ["dss project-library put python/mylib/utils.py --file ./utils.py",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss project-library delete <path> [--project-key KEY]");
+                await c.projectLibrary.deleteFile(a[0], f["project-key"]);
+                return { deleted: a[0], };
+            },
+            usage: "dss project-library delete <path> [--project-key KEY]",
+            description: "Delete a project library file or folder.",
+            examples: ["dss project-library delete python/mylib/old.py",],
+        },
+        rename: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss project-library rename <path> <new-name> [--project-key KEY]");
+                await c.projectLibrary.rename(a[0], a[1], f["project-key"]);
+                return { renamed: a[0], to: a[1], };
+            },
+            usage: "dss project-library rename <path> <new-name> [--project-key KEY]",
+            description: "Rename a project library file or folder within its parent.",
+            examples: ["dss project-library rename python/mylib/old.py new.py",],
+        },
+        move: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss project-library move <path> <destination-folder> [--project-key KEY]");
+                await c.projectLibrary.move(a[0], a[1], f["project-key"]);
+                return { moved: a[0], to: a[1], };
+            },
+            usage: "dss project-library move <path> <destination-folder> [--project-key KEY]",
+            description: "Move a project library file or folder into another folder.",
+            examples: ["dss project-library move python/old.py python/mylib",],
+        },
+    },
+    "streaming-endpoint": {
+        list: {
+            handler: (c, _a, f) => c.streamingEndpoints.list(f["project-key"]),
+            usage: "dss streaming-endpoint list [--project-key KEY]",
+            description: "List streaming endpoints in a project.",
+            examples: ["dss streaming-endpoint list",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint get <id> [--project-key KEY]");
+                return c.streamingEndpoints.getSettings(a[0], f["project-key"]);
+            },
+            usage: "dss streaming-endpoint get <id> [--project-key KEY]",
+            description: "Get a streaming endpoint's settings.",
+            examples: ["dss streaming-endpoint get my-stream",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+                const body = jsonInput(f) ?? {};
+                return c.streamingEndpoints.create(a[0], a[1], body, f["project-key"]);
+            },
+            usage: "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
+            description: "Create a streaming endpoint of the given type.",
+            examples: ["dss streaming-endpoint create my-stream kafka",],
+        },
+        "update-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (endpoint settings).");
+                await c.streamingEndpoints.updateSettings(a[0], body, f["project-key"]);
+                return { updated: a[0], };
+            },
+            usage: "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a streaming endpoint's settings.",
+            examples: ["dss streaming-endpoint update-settings my-stream --data-file settings.json",],
+        },
+        delete: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss streaming-endpoint delete <id> [--project-key KEY]");
+                await c.streamingEndpoints.delete(a[0], f["project-key"]);
+                return { deleted: a[0], };
+            },
+            usage: "dss streaming-endpoint delete <id> [--project-key KEY]",
+            description: "Delete a streaming endpoint.",
+            examples: ["dss streaming-endpoint delete my-stream",],
+        },
+    },
+    "continuous-activity": {
+        list: {
+            handler: (c, _a, f) => c.continuousActivities.list(f["project-key"]),
+            usage: "dss continuous-activity list [--project-key KEY]",
+            description: "List continuous activities in a project.",
+            examples: ["dss continuous-activity list",],
+        },
+        status: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity status <recipeId> [--project-key KEY]");
+                return c.continuousActivities.getStatus(a[0], f["project-key"]);
+            },
+            usage: "dss continuous-activity status <recipeId> [--project-key KEY]",
+            description: "Get a continuous recipe's desired and effective state.",
+            examples: ["dss continuous-activity status compute_stream",],
+        },
+        start: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+                return c.continuousActivities.start(a[0], jsonInput(f), f["project-key"]);
+            },
+            usage: "dss continuous-activity start <recipeId> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
+            description: "Start a continuous recipe (optional loop restart params via JSON).",
+            examples: ["dss continuous-activity start compute_stream",],
+        },
+        stop: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss continuous-activity stop <recipeId> [--project-key KEY]");
+                await c.continuousActivities.stop(a[0], f["project-key"]);
+                return { stopped: a[0], };
+            },
+            usage: "dss continuous-activity stop <recipeId> [--project-key KEY]",
+            description: "Stop a continuous recipe.",
+            examples: ["dss continuous-activity stop compute_stream",],
+        },
+    },
+    statistics: {
+        "list-worksheets": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss statistics list-worksheets <dataset> [--project-key KEY]");
+                return c.statistics.listWorksheets(a[0], f["project-key"]);
+            },
+            usage: "dss statistics list-worksheets <dataset> [--project-key KEY]",
+            description: "List EDA statistics worksheets for a dataset.",
+            examples: ["dss statistics list-worksheets customers",],
+        },
+        "get-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                return c.statistics.getWorksheet(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Get one statistics worksheet definition.",
+            examples: ["dss statistics get-worksheet customers ws_1",],
+        },
+        "create-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
+                return c.statistics.createWorksheet(a[0], body, f["project-key"]);
+            },
+            usage: "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Create a statistics worksheet from a JSON definition.",
+            examples: ["dss statistics create-worksheet customers --data-file ws.json",],
+        },
+        "update-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
+                return c.statistics.updateWorksheet(a[0], a[1], body, f["project-key"]);
+            },
+            usage: "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Replace a statistics worksheet definition.",
+            examples: ["dss statistics update-worksheet customers ws_1 --data-file ws.json",],
+        },
+        "delete-worksheet": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss statistics delete-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                await c.statistics.deleteWorksheet(a[0], a[1], f["project-key"]);
+                return { deleted: a[1], };
+            },
+            usage: "dss statistics delete-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Delete a statistics worksheet.",
+            examples: ["dss statistics delete-worksheet customers ws_1",],
+        },
+        "run-worksheet": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-worksheet <dataset> <worksheetId> [--project-key KEY]");
+                return c.statistics.runWorksheet(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss statistics run-worksheet <dataset> <worksheetId> [--project-key KEY]",
+            description: "Run a statistics worksheet and return the DSS future response.",
+            examples: ["dss statistics run-worksheet customers ws_1",],
+        },
+        "run-card": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const card = requiredJsonInput(f, "--data, --data-file, or --stdin is required (card settings).");
+                return c.statistics.runCard(a[0], a[1], card, f["project-key"]);
+            },
+            usage: "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Run a single card in a worksheet context.",
+            examples: ["dss statistics run-card customers ws_1 --data-file card.json",],
+        },
+        "run-computation": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+                const computation = requiredJsonInput(f, "--data, --data-file, or --stdin is required (computation settings).");
+                return c.statistics.runComputation(a[0], a[1], computation, f["project-key"]);
+            },
+            usage: "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
+            description: "Run a single computation in a worksheet context.",
+            examples: ["dss statistics run-computation customers ws_1 --data-file comp.json",],
+        },
+    },
+    discussion: {
+        list: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss discussion list <objectType> <objectId> [--project-key KEY]");
+                return c.discussions.list(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss discussion list <objectType> <objectId> [--project-key KEY]",
+            description: "List discussions attached to a project object.",
+            examples: ["dss discussion list DATASET customers",],
+        },
+        get: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]");
+                return c.discussions.get(a[0], a[1], a[2], f["project-key"]);
+            },
+            usage: "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]",
+            description: "Get one discussion with its replies.",
+            examples: ["dss discussion get DATASET customers d123",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]");
+                const topic = f["topic"];
+                const reply = f["reply"];
+                if (!topic || !reply) {
+                    throw new UsageError("--topic and --reply are required.", "missing_required_flag");
+                }
+                return c.discussions.create(a[0], a[1], topic, reply, f["project-key"]);
+            },
+            usage: "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]",
+            description: "Create a discussion with its first reply.",
+            examples: ["dss discussion create DATASET customers --topic Schema --reply Please-review",],
+        },
+        reply: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]");
+                const text = f["text"];
+                if (!text)
+                    throw new UsageError("--text is required.", "missing_required_flag");
+                return c.discussions.reply(a[0], a[1], a[2], text, f["project-key"]);
+            },
+            usage: "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]",
+            description: "Add a reply to an existing discussion.",
+            examples: ["dss discussion reply DATASET customers d123 --text Done",],
+        },
+    },
+    meaning: {
+        list: {
+            handler: (c) => c.meanings.list(),
+            usage: "dss meaning list",
+            description: "List user-defined meanings (column semantic types) on the instance.",
+            examples: ["dss meaning list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss meaning get <meaningId>");
+                return c.meanings.get(a[0]);
+            },
+            usage: "dss meaning get <meaningId>",
+            description: "Get a user-defined meaning definition.",
+            examples: ["dss meaning get customer_type",],
+        },
+        create: {
+            handler: (c, a, f) => {
+                requireArgs(a, 3, "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin]");
+                return c.meanings.create(a[0], a[1], a[2], jsonInput(f) ?? {});
+            },
+            usage: "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin]",
+            description: "Create a user-defined meaning (type e.g. VALUES_LIST, VALUES_MAPPING, PATTERN).",
+            examples: ["dss meaning create vip VIP VALUES_LIST",],
+        },
+        update: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (meaning definition).");
+                return c.meanings.update(a[0], body);
+            },
+            usage: "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin)",
+            description: "Replace a user-defined meaning definition.",
+            examples: ["dss meaning update vip --data-file meaning.json",],
+        },
+    },
+    workspace: {
+        list: {
+            handler: (c) => c.workspaces.list(),
+            usage: "dss workspace list",
+            description: "List collaboration workspaces on the instance.",
+            examples: ["dss workspace list",],
+        },
+        get: {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss workspace get <workspaceKey>");
+                return c.workspaces.get(a[0]);
+            },
+            usage: "dss workspace get <workspaceKey>",
+            description: "Get a workspace's settings.",
+            examples: ["dss workspace get MY_WS",],
+        },
+        create: {
+            handler: (c, _a, f) => {
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace definition).");
+                return c.workspaces.create(body);
+            },
+            usage: "dss workspace create (--data JSON|--data-file PATH|--stdin)",
+            description: "Create a collaboration workspace.",
+            examples: ["dss workspace create --data-file ws.json",],
+        },
+        "update-settings": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+                const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace settings).");
+                await c.workspaces.updateSettings(a[0], body);
+                return { updated: a[0], };
+            },
+            usage: "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
+            description: "Replace a workspace's settings (admin).",
+            examples: ["dss workspace update-settings MY_WS --data-file ws.json",],
+        },
+        delete: {
+            handler: async (c, a) => {
+                requireArgs(a, 1, "dss workspace delete <workspaceKey>");
+                await c.workspaces.delete(a[0]);
+                return { deleted: a[0], };
+            },
+            usage: "dss workspace delete <workspaceKey>",
+            description: "Delete a workspace (admin).",
+            examples: ["dss workspace delete MY_WS",],
+        },
+        "list-objects": {
+            handler: (c, a) => {
+                requireArgs(a, 1, "dss workspace list-objects <workspaceKey>");
+                return c.workspaces.listObjects(a[0]);
+            },
+            usage: "dss workspace list-objects <workspaceKey>",
+            description: "List objects shared in a workspace.",
+            examples: ["dss workspace list-objects MY_WS",],
+        },
+        "add-object": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+                const object = requiredJsonInput(f, "--data, --data-file, or --stdin is required (object definition).");
+                return c.workspaces.addObject(a[0], object);
+            },
+            usage: "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
+            description: "Add an object (link or DSS object) to a workspace.",
+            examples: ["dss workspace add-object MY_WS --data-file object.json",],
+        },
+    },
+    metrics: {
+        "dataset-get": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics dataset-get <dataset> [--project-key KEY]");
+                return c.metrics.getDatasetMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics dataset-get <dataset> [--project-key KEY]",
+            description: "Get the last computed metric values for a dataset.",
+            examples: ["dss metrics dataset-get customers",],
+        },
+        "dataset-compute": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics dataset-compute <dataset> [--project-key KEY]");
+                return c.metrics.computeDatasetMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics dataset-compute <dataset> [--project-key KEY]",
+            description: "Compute the DSS-configured metrics for a dataset.",
+            examples: ["dss metrics dataset-compute customers",],
+        },
+        "dataset-history": {
+            handler: (c, a, f) => {
+                requireArgs(a, 2, "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]");
+                return c.metrics.getDatasetMetricHistory(a[0], a[1], f["project-key"]);
+            },
+            usage: "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]",
+            description: "Get the history of one dataset metric.",
+            examples: ["dss metrics dataset-history customers records:COUNT_RECORDS",],
+        },
+        "folder-get": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss metrics folder-get <folderId> [--project-key KEY]");
+                return c.metrics.getFolderMetrics(a[0], f["project-key"]);
+            },
+            usage: "dss metrics folder-get <folderId> [--project-key KEY]",
+            description: "Get the last computed metric values for a managed folder.",
+            examples: ["dss metrics folder-get aBcDeFgH",],
+        },
     },
     doctor: {
         run: {
@@ -2685,6 +3917,36 @@ const commands = {
             description: "List all datasets in a project.",
             examples: ["dss dataset list", "dss dataset list --project-key MYPROJ",],
         },
+        rename: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss dataset rename <oldName> <newName> [--project-key KEY]");
+                await c.datasets.rename(a[0], a[1], f["project-key"]);
+                return { renamed: a[0], to: a[1], };
+            },
+            usage: "dss dataset rename <oldName> <newName> [--project-key KEY]",
+            description: "Rename a dataset (updates downstream flow references).",
+            examples: ["dss dataset rename old_ds new_ds",],
+        },
+        "list-partitions": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss dataset list-partitions <name> [--project-key KEY]");
+                return c.datasets.listPartitions(a[0], f["project-key"]);
+            },
+            usage: "dss dataset list-partitions <name> [--project-key KEY]",
+            description: "List the partitions of a partitioned dataset.",
+            examples: ["dss dataset list-partitions events",],
+        },
+        clear: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]");
+                const partitions = f["partitions"];
+                await c.datasets.clear(a[0], partitions, f["project-key"]);
+                return { cleared: a[0], partitions: partitions ?? "ALL", };
+            },
+            usage: "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]",
+            description: "Clear a dataset's data (all, or a partition spec); keeps the dataset.",
+            examples: ["dss dataset clear staging", "dss dataset clear events --partitions 2024-01",],
+        },
         get: {
             handler: (c, a, f) => {
                 requireArgs(a, 1, "dss dataset get <name>");
@@ -4483,6 +5745,7 @@ const commands = {
                     projectKey: f["project-key"],
                     timeoutMs: num(f["timeout"]),
                     keepScenario: f["keep"] === true,
+                    maxLogBytes: num(f["max-log-bytes"]),
                 });
                 const result = {
                     outcome: run.outcome,
@@ -4491,6 +5754,8 @@ const commands = {
                     elapsedMs: run.elapsedMs,
                     pollCount: run.pollCount,
                     output: run.output ?? "",
+                    logTruncated: run.logTruncated,
+                    maxLogBytes: run.maxLogBytes,
                 };
                 if (f["full-log"] === true || run.output === undefined) {
                     result.log = run.log;
@@ -4498,7 +5763,7 @@ const commands = {
                 return result;
             },
             usage: CODE_RUN_USAGE,
-            description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Pass --full-log for the raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
+            description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Log retrieval is capped by --max-log-bytes (default 1048576); pass --full-log to include the capped raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
             examples: [
                 "dss code run --file inspect.py",
                 "dss code run --file inspect.py --env py39_pandas",
@@ -5218,6 +6483,8 @@ async function runFixtures(flags) {
 const READ_ACTIONS = new Set([
     "cat",
     "contents",
+    "deployment-settings",
+    "deployment-status",
     "diff",
     "download",
     "download-code",
@@ -5253,6 +6520,7 @@ const READ_ACTIONS = new Set([
     "status",
     "rules",
     "settings",
+    "settings-get",
     "status-by-partition",
     "usages",
 ]);
@@ -5284,6 +6552,9 @@ const AUTHENTICATED_AGENT_FLAGS = [
 const COMMANDS_USAGE = "dss commands run [--json]";
 const COMMANDS_DESCRIPTION = "Print the machine-readable command registry for agent planning.";
 const COMMANDS_EXAMPLES = ["dss commands run", "dss commands run --json",];
+const AGENT_CONTRACT_USAGE = "dss agent contract";
+const AGENT_CONTRACT_DESCRIPTION = "Print the versioned JSON contract agents should use to drive dss.";
+const AGENT_CONTRACT_EXAMPLES = ["dss agent contract",];
 const VERSION_USAGE = "dss version";
 const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
@@ -5330,6 +6601,118 @@ function flagKind(name) {
 function registryKey(resource, action) {
     return `${resource}.${action}`;
 }
+function splitShellLike(input) {
+    const tokens = [];
+    let current = "";
+    let quote;
+    for (let index = 0; index < input.length; index++) {
+        const char = input[index];
+        if (quote) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            else if (char === "\\" && quote === '"' && index + 1 < input.length) {
+                current += input[++index];
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        if (char === "|" || char === "<" || char === ">" || char === ";" || char === "&") {
+            return undefined;
+        }
+        current += char;
+    }
+    if (quote)
+        return undefined;
+    if (current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+function exampleArgv(example) {
+    const tokens = splitShellLike(example);
+    if (!tokens || tokens[0] !== "dss")
+        return undefined;
+    return tokens.slice(1);
+}
+function structuredExamples(examples, examplePayload) {
+    return (examples ?? []).map((shell) => {
+        const argv = exampleArgv(shell);
+        return {
+            shell,
+            ...(argv ? { argv, } : {}),
+            ...(examplePayload !== undefined && shell.includes("--data")
+                ? { payload: examplePayload, }
+                : {}),
+        };
+    });
+}
+function outputJsonSchema(shape) {
+    if (shape === "array")
+        return { type: "array", items: true, };
+    if (shape === "string")
+        return { type: "string", };
+    return { type: "object", additionalProperties: true, };
+}
+function payloadJsonSchema(payloadSchema) {
+    if (!payloadSchema)
+        return undefined;
+    return payloadSchema.jsonShape === "array"
+        ? { type: "array", items: true, }
+        : { type: "object", additionalProperties: true, };
+}
+function argvJsonSchema(resource, action, _flags, _positionals, _requiredFlags, _requiredOneOf) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        required: ["argv",],
+        properties: {
+            argv: { type: "array", items: { type: "string", }, minItems: 1, },
+            resource: { const: resource, },
+            action: { const: action, },
+        },
+    };
+}
+function unsafeOutputs(resource, action, flags, producesLocalFile) {
+    const outputs = [];
+    if (flags.some((flag) => flag.name === "raw")) {
+        outputs.push({
+            condition: "--raw without --output",
+            kind: "raw-stdout",
+            detail: `${resource} ${action} can intentionally write raw payload bytes/text instead of JSON.`,
+            safeAlternative: flags.some((flag) => flag.name === "output")
+                ? "Pass --output PATH so stdout remains a JSON string containing the path."
+                : "Omit --raw when a JSON stdout value is required.",
+        });
+    }
+    if (producesLocalFile) {
+        outputs.push({
+            condition: "--output or --output-file",
+            kind: "local-file",
+            detail: "Command writes bytes to a local path and returns JSON metadata on stdout.",
+        });
+    }
+    return outputs.length > 0 ? outputs : undefined;
+}
+function buildCommandSchemas(resource, action, flags, positionals, requiredFlags, requiredOneOf, payloadSchema, outputShape) {
+    return {
+        argv: argvJsonSchema(resource, action, flags, positionals, requiredFlags, requiredOneOf),
+        ...(payloadSchema ? { input: payloadJsonSchema(payloadSchema), } : {}),
+        output: outputJsonSchema(outputShape),
+    };
+}
 const EXPLICIT_REGISTRY_OVERRIDES = {
     "dashboard.create": {
         examplePayload: { pages: [], },
@@ -5385,7 +6768,8 @@ function extractPositionals(usage) {
 function inferSideEffect(resource, action) {
     if (resource === "auth")
         return "auth";
-    if (resource === "doctor" || resource === "commands" || resource === "fixtures"
+    if (resource === "agent" || resource === "doctor" || resource === "commands"
+        || resource === "fixtures"
         || resource === "version") {
         return "read";
     }
@@ -5395,20 +6779,23 @@ function inferSideEffect(resource, action) {
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove)/
-        .test(action)) {
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|start|stop|restart|duplicate|put|rename|reply|compute|organize)/
+        .test(action)
+        // Compound actions whose mutating verb is a suffix (e.g. permissions-set, dataset-compute).
+        || /-(set|compute)$/.test(action)) {
         return "write";
     }
     return "read";
 }
 function inferRequiresAuth(resource) {
-    return resource !== "auth"
+    return resource !== "agent"
+        && resource !== "auth"
         && resource !== "commands"
         && resource !== "install-skill"
         && resource !== "version";
 }
 function inferRequiresProject(resource, action, usage) {
-    if (resource === "auth" || resource === "doctor" || resource === "commands"
+    if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
         || resource === "install-skill" || resource === "version") {
         return false;
     }
@@ -5426,6 +6813,7 @@ const ARRAY_OUTPUT_ACTIONS = new Set([
     "list",
     "list-jupyter",
     "list-sql",
+    "project-timeline",
     "rules",
     "schemas",
     "sessions-jupyter",
@@ -5441,14 +6829,19 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "log-url",
 ]);
 function inferOutputShape(resource, action) {
-    if (resource === "auth" || resource === "commands" || resource === "install-skill"
+    if (resource === "agent" || resource === "auth" || resource === "commands"
+        || resource === "install-skill"
         || resource === "version") {
         return "object";
     }
+    if (/^list(-|$)/.test(action))
+        return "array";
     if (ARRAY_OUTPUT_ACTIONS.has(action))
         return "array";
     if (resource === "dataset" && action === "download")
         return "object";
+    if (resource === "project-library" && action === "get")
+        return "string";
     if (STRING_OUTPUT_ACTIONS.has(action))
         return "string";
     return "object";
@@ -5681,47 +7074,58 @@ function buildRegistryEntry(resource, action, meta) {
     const cleanupCommand = meta.cleanupCommand
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.cleanupCommand
         ?? cleanupCommandFromDeleteUsage(resource, action);
+    const flagMetadata = flags.map((name) => {
+        const kind = flagKind(name);
+        if (kind === "boolean")
+            return { name, kind, };
+        const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
+        if (!hint)
+            return { name, kind, };
+        return {
+            name,
+            kind,
+            valueType: hint.valueType,
+            ...(hint.enumValues ? { enumValues: hint.enumValues, } : {}),
+        };
+    });
+    const positionals = extractPositionals(meta.usage);
+    const outputShape = inferOutputShape(resource, action);
+    const producesLocalFile = meta.usage.includes("--output PATH")
+        || meta.usage.includes("--output-file PATH");
+    const uniqueRequiredFlags = uniqueStrings(requiredFlags);
+    const uniqueOptionalFlags = uniqueStrings(optionalFlags);
+    const unsafe = unsafeOutputs(resource, action, flagMetadata, producesLocalFile);
     return {
         resource,
         action,
         usage: meta.usage,
         description: meta.description,
         examples: meta.examples,
-        flags: flags.map((name) => {
-            const kind = flagKind(name);
-            if (kind === "boolean")
-                return { name, kind, };
-            const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
-            if (!hint)
-                return { name, kind, };
-            return {
-                name,
-                kind,
-                valueType: hint.valueType,
-                ...(hint.enumValues ? { enumValues: hint.enumValues, } : {}),
-            };
-        }),
-        positionals: extractPositionals(meta.usage),
+        structuredExamples: structuredExamples(meta.examples, examplePayload),
+        flags: flagMetadata,
+        positionals,
         sideEffect,
         requiresAuth,
         requiresProject,
-        outputShape: inferOutputShape(resource, action),
+        outputShape,
         inputContract,
         destructive,
-        producesLocalFile: meta.usage.includes("--output PATH")
-            || meta.usage.includes("--output-file PATH"),
+        producesLocalFile,
         mutatesDss,
         async: asyncKind,
         idempotency: inferIdempotency(sideEffect, action, meta.usage),
         dryRun: meta.usage.includes("--dry-run"),
-        requiredFlags: uniqueStrings(requiredFlags),
-        optionalFlags: uniqueStrings(optionalFlags),
+        requiredFlags: uniqueRequiredFlags,
+        optionalFlags: uniqueOptionalFlags,
         ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
         ...(payloadSchema ? { payloadSchema, } : {}),
+        schemas: buildCommandSchemas(resource, action, flagMetadata, positionals, uniqueRequiredFlags, requiredOneOf, payloadSchema, outputShape),
+        ...(unsafe ? { unsafeOutputs: unsafe, } : {}),
         ...(examplePayload !== undefined ? { examplePayload, } : {}),
         ...(cleanupCommand ? { cleanupCommand, } : {}),
         exitCodes: inferExitCodes(asyncKind),
         ...(cleanupHint ? { cleanupHint, } : {}),
+        agentContractVersion: AGENT_CONTRACT_VERSION,
     };
 }
 function buildCommandRegistry() {
@@ -5740,6 +7144,14 @@ function buildCommandRegistry() {
             examples: COMMANDS_EXAMPLES,
         }),
     };
+    registry.agent = {
+        contract: buildRegistryEntry("agent", "contract", {
+            handler: async () => undefined,
+            usage: AGENT_CONTRACT_USAGE,
+            description: AGENT_CONTRACT_DESCRIPTION,
+            examples: AGENT_CONTRACT_EXAMPLES,
+        }),
+    };
     registry.version = {
         run: buildRegistryEntry("version", "run", {
             handler: async () => undefined,
@@ -5794,6 +7206,191 @@ function buildCommandRegistry() {
     }
     return registry;
 }
+function commandFlagJsonSchema() {
+    return {
+        type: "object",
+        required: ["name", "kind",],
+        additionalProperties: false,
+        properties: {
+            name: { type: "string", },
+            kind: { enum: ["boolean", "value",], },
+            valueType: { type: "string", },
+            enumValues: { type: "array", items: { type: "string", }, },
+        },
+    };
+}
+function commandRegistryEntryJsonSchema() {
+    return {
+        type: "object",
+        required: [
+            "resource",
+            "action",
+            "usage",
+            "flags",
+            "positionals",
+            "sideEffect",
+            "requiresAuth",
+            "requiresProject",
+            "outputShape",
+            "inputContract",
+            "schemas",
+            "exitCodes",
+            "agentContractVersion",
+        ],
+        additionalProperties: true,
+        properties: {
+            resource: { type: "string", },
+            action: { type: "string", },
+            usage: { type: "string", },
+            description: { type: "string", },
+            examples: { type: "array", items: { type: "string", }, },
+            structuredExamples: { type: "array", items: { type: "object", additionalProperties: true, }, },
+            flags: { type: "array", items: commandFlagJsonSchema(), },
+            positionals: { type: "array", items: { type: "string", }, },
+            sideEffect: { enum: ["read", "write", "auth",], },
+            requiresAuth: { type: "boolean", },
+            requiresProject: { type: "boolean", },
+            outputShape: { enum: ["object", "array", "string", "void",], },
+            inputContract: { type: "object", additionalProperties: { type: "boolean", }, },
+            destructive: { enum: ["none", "reversible", "destructive",], },
+            producesLocalFile: { type: "boolean", },
+            mutatesDss: { type: "boolean", },
+            async: { enum: ["none", "job", "future",], },
+            idempotency: { enum: ["safe", "convergent", "if-not-exists", "if-exists", "none",], },
+            dryRun: { type: "boolean", },
+            requiredFlags: { type: "array", items: { type: "string", }, },
+            optionalFlags: { type: "array", items: { type: "string", }, },
+            schemas: { type: "object", additionalProperties: true, },
+            unsafeOutputs: { type: "array", items: { type: "object", additionalProperties: true, }, },
+            exitCodes: { type: "object", additionalProperties: { type: "number", }, },
+            agentContractVersion: { const: AGENT_CONTRACT_VERSION, },
+        },
+    };
+}
+function commandRegistryJsonSchema() {
+    return {
+        $schema: JSON_SCHEMA_DRAFT,
+        type: "object",
+        additionalProperties: {
+            type: "object",
+            additionalProperties: commandRegistryEntryJsonSchema(),
+        },
+    };
+}
+function errorEnvelopeJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "ok", "error", "code", "category", "exitCode",],
+        additionalProperties: true,
+        properties: {
+            type: { const: "error", },
+            ok: { const: false, },
+            error: { type: "string", },
+            code: { type: "string", },
+            category: { enum: ["usage", "dss", "internal",], },
+            exitCode: { type: "number", },
+            resource: { type: "string", },
+            action: { type: "string", },
+            projectKey: { type: "string", },
+        },
+    };
+}
+function warningEventJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "warnings",],
+        additionalProperties: false,
+        properties: {
+            type: { const: "warning", },
+            warnings: { type: "array", items: { type: "object", additionalProperties: true, }, },
+        },
+    };
+}
+function traceEventJsonSchema() {
+    return {
+        type: "object",
+        required: ["type", "phase", "method", "url", "attempt", "maxAttempts",],
+        additionalProperties: false,
+        properties: {
+            type: { const: "trace", },
+            phase: { enum: ["request", "response", "error",], },
+            method: { type: "string", },
+            url: { type: "string", },
+            attempt: { type: "number", },
+            maxAttempts: { type: "number", },
+            status: { type: "number", },
+            elapsedMs: { type: "number", },
+            detail: { type: "string", },
+        },
+    };
+}
+function agentContractJsonSchema() {
+    return {
+        $schema: JSON_SCHEMA_DRAFT,
+        $id: AGENT_CONTRACT_SCHEMA_ID,
+        type: "object",
+        required: ["protocol", "agentContractVersion", "cli", "commands", "schemas", "stdio",],
+        additionalProperties: true,
+        properties: {
+            protocol: { const: "dataiku-sdk-agent", },
+            agentContractVersion: { const: AGENT_CONTRACT_VERSION, },
+            cli: { type: "object", additionalProperties: true, },
+            commands: { type: "object", additionalProperties: true, },
+            schemas: { type: "object", additionalProperties: true, },
+            stdio: { type: "object", additionalProperties: true, },
+        },
+    };
+}
+function commandActionSummary(registry) {
+    const summary = {};
+    for (const [resource, actions,] of Object.entries(registry)) {
+        summary[resource] = Object.keys(actions).sort();
+    }
+    return summary;
+}
+function buildAgentContract() {
+    const registry = buildCommandRegistry();
+    return {
+        protocol: "dataiku-sdk-agent",
+        agentContractVersion: AGENT_CONTRACT_VERSION,
+        cli: cliVersionResult(),
+        commands: {
+            discoveryCommand: "dss commands run",
+            actions: commandActionSummary(registry),
+        },
+        schemas: {
+            agentContract: agentContractJsonSchema(),
+            commandRegistry: commandRegistryJsonSchema(),
+            commandRegistryEntry: commandRegistryEntryJsonSchema(),
+            errorEnvelope: errorEnvelopeJsonSchema(),
+            warningEvent: warningEventJsonSchema(),
+            traceEvent: traceEventJsonSchema(),
+        },
+        stdio: {
+            stdout: {
+                success: "single-json-value",
+                rawEscapeHatches: [
+                    "recipe get-payload --raw without --output",
+                    "recipe cat --raw without --output",
+                ],
+            },
+            stderr: {
+                format: "jsonl",
+                events: ["warning", "trace", "error",],
+                error: "single-final-error-event-on-nonzero-exit",
+            },
+        },
+        planning: {
+            discoveryCommand: "dss commands run",
+            contractCommand: AGENT_CONTRACT_USAGE,
+            mutatingCommandsAdvertisePlan: true,
+        },
+        compatibility: {
+            fieldsAreAdditiveWithinMajor: true,
+            failFastWhenUnsupported: "Check agentContractVersion before planning commands.",
+        },
+    };
+}
 function exitCodesOnFailure(entry) {
     return {
         usage: entry.exitCodes.usage,
@@ -6354,6 +7951,31 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                 identifiers: { id, cellId: flags["cell-id"], },
                 payload: { retain: num(flags["retain"]), },
             };
+        case "project.permissions-set":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint("/permissions"),
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "continuous-activity.start":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/continuous-activities/${encodeURIComponent(id)}/start`),
+                identifiers: { recipeId: id, },
+                payload: jsonInput(flags) ?? {},
+            };
+        case "metrics.dataset-compute":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}/actions/computeMetrics?partition=`),
+                identifiers: { dataset: id, },
+            };
+        case "flow-zone.organize":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/flow/zones"),
+                payload: jsonInput(flags),
+            };
         default:
             return {
                 method: action.startsWith("delete") || action === "abort" ? "DELETE" : "POST",
@@ -6703,6 +8325,7 @@ function buildErrorReport(err) {
     const exitCode = errorExitCode(err);
     if (err instanceof UsageError) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: err.code,
@@ -6715,6 +8338,7 @@ function buildErrorReport(err) {
     }
     if (err instanceof CommandResultFailure) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: "long_running_failure",
@@ -6726,6 +8350,7 @@ function buildErrorReport(err) {
     }
     if (err instanceof DataikuError) {
         return {
+            type: "error",
             ok: false,
             error: err.message,
             code: dataikuErrorCode(err.category),
@@ -6746,6 +8371,7 @@ function buildErrorReport(err) {
     }
     const message = err instanceof Error ? err.message : String(err);
     return {
+        type: "error",
         ok: false,
         error: message,
         code: "internal_error",
@@ -6755,7 +8381,7 @@ function buildErrorReport(err) {
     };
 }
 function writeErrorReport(err) {
-    process.stderr.write(`${JSON.stringify(buildErrorReport(err), null, 2)}\n`);
+    process.stderr.write(`${JSON.stringify(buildErrorReport(err))}\n`);
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -6867,6 +8493,16 @@ async function main() {
         });
         return;
     }
+    if (resource === "agent") {
+        const action = positional[1];
+        if (!action)
+            throw missingActionError("agent", ["contract",], AGENT_CONTRACT_USAGE);
+        currentCommandContext.action = action;
+        if (action !== "contract")
+            throw unknownActionError("agent", action, ["contract",]);
+        writeCommandResult(buildAgentContract());
+        return;
+    }
     if (resource === "commands") {
         const action = positional[1];
         if (!action)