dataiku-sdk 0.12.6 → 0.12.7

package/dist/src/cli/commands/dashboard.js

@@ -1,5 +1,7 @@
+import * as fs from "node:fs";
+import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { jsonInput, } from "../coerce.js";
+import { jsonInput, parseBooleanOption, } from "../coerce.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const dashboardCommands = {
@@ -18,12 +20,91 @@ export const dashboardCommands = {
         description: "Get dashboard definition.",
         examples: ["dss dashboard get DASHBOARD_ID",],
     },
+    export: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dashboard export <id> --output PATH [--paper-size SIZE] [--orientation PORTRAIT|LANDSCAPE] [--file-type PDF] [--slide-index N] [--project-key KEY]");
+            const outputPath = f["output"];
+            if (typeof outputPath !== "string" || !outputPath.trim()) {
+                throw new UsageError("--output PATH is required.", "missing_required_flag");
+            }
+            const paperSizeFlag = f["paper-size"];
+            if (paperSizeFlag !== undefined && typeof paperSizeFlag !== "string") {
+                throw new UsageError("--paper-size requires a value.");
+            }
+            const paperSize = (paperSizeFlag ?? "A4").trim();
+            if (!paperSize)
+                throw new UsageError("--paper-size must not be empty.");
+            const orientationFlag = f["orientation"];
+            if (orientationFlag !== undefined && typeof orientationFlag !== "string") {
+                throw new UsageError("--orientation requires a value.");
+            }
+            const orientation = (orientationFlag ?? "LANDSCAPE").trim().toUpperCase();
+            if (orientation !== "PORTRAIT" && orientation !== "LANDSCAPE") {
+                throw new UsageError("--orientation must be PORTRAIT or LANDSCAPE.", "invalid_enum");
+            }
+            const fileTypeFlag = f["file-type"];
+            if (fileTypeFlag !== undefined && typeof fileTypeFlag !== "string") {
+                throw new UsageError("--file-type requires a value.");
+            }
+            const fileType = (fileTypeFlag ?? "PDF").trim().toUpperCase();
+            if (fileType !== "PDF") {
+                throw new UsageError("--file-type must be PDF.", "invalid_enum");
+            }
+            const slideIndexFlag = f["slide-index"];
+            if (slideIndexFlag !== undefined
+                && (typeof slideIndexFlag !== "string" || !/^(0|[1-9]\d*)$/u.test(slideIndexFlag))) {
+                throw new UsageError("--slide-index must be a non-negative integer.");
+            }
+            const slideIndex = slideIndexFlag === undefined ? 0 : Number(slideIndexFlag);
+            const response = await c.dashboards.export(a[0], {
+                paperSize,
+                orientation,
+                fileType,
+                slideIndex,
+                projectKey: f["project-key"],
+            });
+            const bytes = Buffer.from(await response.arrayBuffer());
+            const isPdf = bytes.length >= 5
+                && bytes[0] === 0x25
+                && bytes[1] === 0x50
+                && bytes[2] === 0x44
+                && bytes[3] === 0x46
+                && bytes[4] === 0x2d;
+            if (!isPdf) {
+                throw new ClientValidationError("DSS dashboard export did not return a PDF.", "validation_failed", "Confirm DSS graphics export is configured and retry the export.");
+            }
+            fs.writeFileSync(outputPath, bytes);
+            return {
+                path: outputPath,
+                bytes: bytes.length,
+                contentType: response.headers.get("content-type") ?? undefined,
+                dashboardId: a[0],
+                paperSize,
+                orientation,
+                fileType,
+                slideIndex,
+            };
+        },
+        usage: "dss dashboard export <id> --output PATH [--paper-size SIZE] [--orientation PORTRAIT|LANDSCAPE] [--file-type PDF] [--slide-index N] [--project-key KEY]",
+        description: "Render a dashboard page as PDF. Requires DSS graphics export to be configured.",
+        examples: [
+            "dss dashboard export DASHBOARD_ID --output dashboard.pdf",
+            "dss dashboard export DASHBOARD_ID --output dashboard.pdf --orientation LANDSCAPE --slide-index 0",
+        ],
+    },
     create: {
         handler: async (c, _a, f) => {
-            const name = f["name"];
-            if (!name)
-                throw new UsageError("--name is required. Usage: dss dashboard create --name NAME");
             const settings = jsonInput(f);
+            const flagName = f["name"];
+            const settingsName = settings?.["name"];
+            const name = flagName ?? (typeof settingsName === "string" ? settingsName : undefined);
+            const listed = parseBooleanOption(f["listed"], "--listed");
+            if (!name) {
+                throw new UsageError("--name or dashboard settings containing a string name are required. Usage: dss dashboard create --name NAME");
+            }
+            const payload = { ...(settings ?? { pages: [], }), name, };
+            if (listed !== undefined)
+                payload.listed = listed;
             const pk = f["project-key"];
             if (f["if-not-exists"] === true || f["dry-run"] === true) {
                 const existing = (await c.dashboards.list(pk)).find((dashboard) => dashboard.name === name);
@@ -36,46 +117,54 @@ export const dashboardCommands = {
                         action: "create",
                         resource: "dashboard",
                         name,
-                        payload: settings ?? { pages: [], },
+                        payload,
                         ...(existing ? { current: existing, } : {}),
                     };
                 }
             }
             const created = await c.dashboards.create({
                 name,
+                listed,
                 settings,
                 projectKey: pk,
             });
             return { created: created.id, resource: "dashboard", ...created, };
         },
-        usage: "dss dashboard create --name NAME [--data JSON|--data-file PATH|--stdin] [--if-not-exists] [--dry-run] [--project-key KEY]",
-        description: "Create a dashboard. Defaults to an empty pages array.",
-        examples: ["dss dashboard create --name 'Agent dashboard' --dry-run",],
+        usage: "dss dashboard create (--name NAME|--data JSON|--data-file PATH|--stdin) [--listed true|false] [--if-not-exists] [--dry-run] [--project-key KEY]",
+        description: "Create a dashboard from raw settings or minimal name/listed fields. Defaults to an empty pages array.",
+        examples: [
+            "dss dashboard create --name 'Agent dashboard' --listed true --dry-run",
+            'dss dashboard create --data \'{"name":"Agent dashboard","pages":[]}\'',
+        ],
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dashboard update <id> [--name NAME|--data JSON]");
+            requireArgs(a, 1, "dss dashboard update <id> [--name NAME|--listed true|false|--data JSON]");
             const name = f["name"];
+            const listed = parseBooleanOption(f["listed"], "--listed");
             const data = jsonInput(f);
-            if (!name && !data) {
-                throw new UsageError("--name, --data, --data-file, or --stdin is required.");
+            if (name === undefined && listed === undefined && !data) {
+                throw new UsageError("--name, --listed, --data, --data-file, or --stdin is required.");
             }
             if (f["dry-run"] === true) {
                 const current = await c.dashboards.get(a[0], f["project-key"]);
                 const next = deepMerge(current, data ?? {});
                 if (name !== undefined)
                     next.name = name;
+                if (listed !== undefined)
+                    next.listed = listed;
                 return { dryRun: true, action: "update", resource: "dashboard", id: a[0], current, next, };
             }
             return c.dashboards.update(a[0], {
                 name,
+                listed,
                 data,
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss dashboard update <id> (--name NAME|--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
+        usage: "dss dashboard update <id> (--name NAME|--listed true|false|--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Update dashboard settings via merge.",
-        examples: ["dss dashboard update DASHBOARD_ID --name 'New name' --dry-run",],
+        examples: ["dss dashboard update DASHBOARD_ID --listed true --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {

package/dist/src/cli/contract.js

@@ -519,7 +519,7 @@ export function buildCommandSchemas(resource, action, flags, requiredFlags, requ
 }
 const EXPLICIT_REGISTRY_OVERRIDES = {
     "dashboard.create": {
-        examplePayload: { pages: [], },
+        examplePayload: { name: "Agent dashboard", pages: [], },
     },
     "dashboard.update": {
         examplePayload: { name: "Updated dashboard", },
@@ -583,10 +583,9 @@ function inferSideEffect(resource, action) {
     }
     if (resource === "install-skill")
         return "write";
-    // `project export` streams an archive over the API and writes it to a local
-    // path; the DSS-side project is untouched, so it reads remotely and only
-    // mutates the local filesystem.
-    if (resource === "project" && action === "export")
+    // Project and dashboard exports stream a rendered/archive artifact and write it
+    // locally; the DSS-side resource is untouched.
+    if ((resource === "project" || resource === "dashboard") && action === "export")
         return "read";
     if (resource === "data-quality" && action === "compute")
         return "write";
@@ -1449,18 +1448,31 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { article: id, },
             };
         case "dashboard.create": {
-            const name = requiredPlanFlag(flags, "name", entry.usage);
+            const data = jsonInput(flags);
+            const flagName = flags["name"];
+            const dataName = data?.["name"];
+            const name = flagName ?? (typeof dataName === "string" ? dataName : undefined);
+            if (!name) {
+                throw new UsageError("--name or dashboard settings containing a string name are required. Usage: dss dashboard create --name NAME");
+            }
+            const listed = parseBooleanOption(flags["listed"], "--listed");
+            const payload = { ...(data ?? { pages: [], }), name, };
+            if (listed !== undefined)
+                payload.listed = listed;
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/dashboards/"),
                 identifiers: { name, },
-                payload: { ...(jsonInput(flags) ?? { pages: [], }), name, },
+                payload,
             };
         }
         case "dashboard.update": {
             const payload = { ...jsonInput(flags), };
             if (typeof flags["name"] === "string")
                 payload.name = flags["name"];
+            const listed = parseBooleanOption(flags["listed"], "--listed");
+            if (listed !== undefined)
+                payload.listed = listed;
             return {
                 method: "PUT",
                 endpoint: projectEndpoint(`/dashboards/${encodeURIComponent(id)}/`),

package/dist/src/cli/flags.js

@@ -91,6 +91,7 @@ export const VALUE_FLAGS = new Set([
     "database",
     "dataset",
     "file",
+    "file-type",
     "env",
     "install-core-packages",
     "fuzzy-on",
@@ -133,7 +134,9 @@ export const VALUE_FLAGS = new Set([
     "output-file",
     "output-connection",
     "output-folder",
+    "orientation",
     "page",
+    "paper-size",
     "partition",
     "parent",
     "path",
@@ -157,6 +160,7 @@ export const VALUE_FLAGS = new Set([
     "retain",
     "saved-model",
     "session-name",
+    "slide-index",
     "sql",
     "schema",
     "sql-file",

package/dist/src/client.d.ts

@@ -173,6 +173,7 @@ export declare class DataikuClient {
         retryMaxAttempts?: number;
     }): Promise<T>;
     postText(path: string, body?: unknown): Promise<string>;
+    postStream(path: string, body?: unknown): Promise<Response>;
     put<T = unknown>(path: string, body: unknown): Promise<T>;
     del(path: string): Promise<void>;
     putVoid(path: string, body: unknown): Promise<void>;

package/dist/src/client.js

@@ -431,6 +431,13 @@ export class DataikuClient {
         });
         return res.text();
     }
+    async postStream(path, body) {
+        return this.fetchWithRetry(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { ...this.getAnyHeaders(), "Content-Type": "application/json", },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
     async put(path, body) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "PUT",

package/dist/src/resources/dashboards.d.ts

@@ -2,18 +2,32 @@ import type { DashboardDetails, DashboardSummary } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export interface DashboardCreateOptions {
     name: string;
+    listed?: boolean;
     settings?: Record<string, unknown>;
     projectKey?: string;
 }
 export interface DashboardUpdateOptions {
     name?: string;
+    listed?: boolean;
     data?: Record<string, unknown>;
     projectKey?: string;
 }
+export type DashboardExportOrientation = "PORTRAIT" | "LANDSCAPE";
+export type DashboardExportFileType = "PDF";
+export interface DashboardExportOptions {
+    paperSize?: string;
+    orientation?: DashboardExportOrientation;
+    fileType?: DashboardExportFileType;
+    slideIndex?: number;
+    projectKey?: string;
+}
 export declare class DashboardsResource extends BaseResource {
     list(projectKey?: string): Promise<DashboardSummary[]>;
     get(dashboardId: string, projectKey?: string): Promise<DashboardDetails>;
+    private referencedInsightIds;
+    private validateReferences;
     create(opts: DashboardCreateOptions): Promise<DashboardDetails>;
     update(dashboardId: string, opts: DashboardUpdateOptions): Promise<DashboardDetails>;
+    export(dashboardId: string, opts?: DashboardExportOptions): Promise<Response>;
     delete(dashboardId: string, projectKey?: string): Promise<void>;
 }

package/dist/src/resources/dashboards.js

@@ -1,6 +1,17 @@
-import { DashboardDetailsSchema, DashboardSummaryArraySchema, } from "../schemas.js";
+import { ClientValidationError, DataikuError, } from "../errors.js";
+import { DashboardDetailsSchema, DashboardSummaryArraySchema, InsightDetailsSchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { BaseResource, } from "./base.js";
+const REFERENCE_VALIDATION_CONCURRENCY = 8;
+async function validateInBatches(items, validate) {
+    for (let offset = 0; offset < items.length; offset += REFERENCE_VALIDATION_CONCURRENCY) {
+        const batch = items.slice(offset, offset + REFERENCE_VALIDATION_CONCURRENCY);
+        const results = await Promise.allSettled(batch.map(validate));
+        const failure = results.find((result) => result.status === "rejected");
+        if (failure)
+            throw failure.reason;
+    }
+}
 export class DashboardsResource extends BaseResource {
     async list(projectKey) {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/dashboards/`);
@@ -10,19 +21,160 @@ export class DashboardsResource extends BaseResource {
         const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/dashboards/${encodeURIComponent(dashboardId)}/`);
         return this.client.safeParse(DashboardDetailsSchema, raw, "dashboards.get");
     }
+    referencedInsightIds(settings) {
+        const pages = settings.pages;
+        if (pages === undefined)
+            return [];
+        if (!Array.isArray(pages)) {
+            throw new ClientValidationError("Dashboard pages must be an array.");
+        }
+        const insightIds = new Set();
+        for (const [pageIndex, page,] of pages.entries()) {
+            if (!page || typeof page !== "object" || Array.isArray(page)) {
+                throw new ClientValidationError(`Dashboard page ${pageIndex} must be an object.`);
+            }
+            const grid = page.grid;
+            if (grid === undefined)
+                continue;
+            if (!grid || typeof grid !== "object" || Array.isArray(grid)) {
+                throw new ClientValidationError(`Dashboard page ${pageIndex} grid must be an object.`);
+            }
+            const tiles = grid.tiles;
+            if (tiles === undefined)
+                continue;
+            if (!Array.isArray(tiles)) {
+                throw new ClientValidationError(`Dashboard page ${pageIndex} grid tiles must be an array.`);
+            }
+            for (const [tileIndex, tile,] of tiles.entries()) {
+                if (!tile || typeof tile !== "object" || Array.isArray(tile)) {
+                    throw new ClientValidationError(`Dashboard page ${pageIndex} tile ${tileIndex} must be an object.`);
+                }
+                const record = tile;
+                const insightId = record.insightId ?? undefined;
+                const targetInsightId = record.targetInsightId ?? undefined;
+                const isInsight = record.tileType === "INSIGHT"
+                    || insightId !== undefined
+                    || targetInsightId !== undefined;
+                if (!isInsight)
+                    continue;
+                if (insightId !== undefined
+                    && (typeof insightId !== "string" || insightId.trim().length === 0)) {
+                    throw new ClientValidationError(`Dashboard page ${pageIndex} tile ${tileIndex} insightId must be a non-empty string.`);
+                }
+                if (targetInsightId !== undefined
+                    && (typeof targetInsightId !== "string" || targetInsightId.trim().length === 0)) {
+                    throw new ClientValidationError(`Dashboard page ${pageIndex} tile ${tileIndex} targetInsightId must be a non-empty string.`);
+                }
+                const normalizedInsightId = typeof insightId === "string" ? insightId.trim() : undefined;
+                const normalizedTargetId = typeof targetInsightId === "string"
+                    ? targetInsightId.trim()
+                    : undefined;
+                if (normalizedInsightId !== undefined
+                    && normalizedTargetId !== undefined
+                    && normalizedInsightId !== normalizedTargetId) {
+                    throw new ClientValidationError(`Dashboard page ${pageIndex} tile ${tileIndex} has mismatched insightId and targetInsightId.`);
+                }
+                const reference = normalizedInsightId ?? normalizedTargetId;
+                if (!reference) {
+                    throw new ClientValidationError(`Dashboard page ${pageIndex} tile ${tileIndex} requires insightId or targetInsightId.`);
+                }
+                insightIds.add(reference);
+            }
+        }
+        return [...insightIds,];
+    }
+    async validateReferences(settings, projectKey) {
+        const insightIds = this.referencedInsightIds(settings);
+        const datasetNames = new Set();
+        await validateInBatches(insightIds, async (insightId) => {
+            let raw;
+            try {
+                raw = await this.client.get(`/public/api/projects/${encodeURIComponent(projectKey)}/insights/${encodeURIComponent(insightId)}/`);
+            }
+            catch (error) {
+                if (error instanceof DataikuError && error.status === 404) {
+                    throw new ClientValidationError(`Dashboard references missing insight ${insightId}.`, "validation_failed", "Create or restore the insight, then update the tile reference before saving the dashboard.", { insightId, });
+                }
+                throw error;
+            }
+            const insight = this.client.safeParse(InsightDetailsSchema, raw, `dashboards.validateReferences.insight.${insightId}`);
+            const params = raw && typeof raw === "object" && !Array.isArray(raw)
+                ? raw.params
+                : undefined;
+            const datasetSmartName = params && typeof params === "object" && !Array.isArray(params)
+                ? params.datasetSmartName
+                : undefined;
+            if (insight.type === "dataset_table" && (typeof datasetSmartName !== "string" || datasetSmartName.trim().length === 0)) {
+                throw new ClientValidationError(`Dashboard insight ${insightId} does not name a backing dataset.`, "validation_failed", "Retarget the dataset-table insight before saving the dashboard.", { insightId, });
+            }
+            if (typeof datasetSmartName === "string" && datasetSmartName.trim().length > 0) {
+                datasetNames.add(datasetSmartName.trim());
+            }
+        });
+        await validateInBatches([...datasetNames,], async (datasetSmartName) => {
+            const separatorIndex = datasetSmartName.indexOf(".");
+            if (separatorIndex === 0 || separatorIndex === datasetSmartName.length - 1) {
+                throw new ClientValidationError(`Dashboard insight has invalid dataset smart name ${datasetSmartName}.`, "validation_failed", "Use DATASET for the current project or PROJECT.DATASET for a cross-project dataset.", { datasetSmartName, });
+            }
+            const datasetProjectKey = separatorIndex > 0
+                ? datasetSmartName.slice(0, separatorIndex)
+                : projectKey;
+            const datasetName = separatorIndex > 0
+                ? datasetSmartName.slice(separatorIndex + 1)
+                : datasetSmartName;
+            try {
+                await this.client.get(`/public/api/projects/${encodeURIComponent(datasetProjectKey)}/datasets/${encodeURIComponent(datasetName)}/`);
+            }
+            catch (error) {
+                if (error instanceof DataikuError && error.status === 403) {
+                    throw new ClientValidationError(`Dashboard cannot validate inaccessible dataset ${datasetSmartName}.`, "validation_failed", "Grant the API key read access to the dataset project before saving the dashboard.", { datasetSmartName, datasetProjectKey, datasetName, });
+                }
+                if (error instanceof DataikuError && error.status === 404) {
+                    throw new ClientValidationError(`Dashboard insight references missing dataset ${datasetSmartName}.`, "validation_failed", "Create or restore the dataset, or retarget the insight before saving the dashboard.", { datasetSmartName, datasetProjectKey, datasetName, });
+                }
+                throw error;
+            }
+        });
+    }
     async create(opts) {
         const pk = this.resolveProjectKey(opts.projectKey);
         const body = { ...(opts.settings ?? { pages: [], }), name: opts.name, };
+        if (opts.listed !== undefined)
+            body.listed = opts.listed;
+        await this.validateReferences(body, pk);
         const created = await this.client.post(`/public/api/projects/${encodeURIComponent(pk)}/dashboards/`, body);
         return this.get(created.id, pk);
     }
     async update(dashboardId, opts) {
-        const current = await this.get(dashboardId, opts.projectKey);
+        const pk = this.resolveProjectKey(opts.projectKey);
+        const current = await this.get(dashboardId, pk);
         const next = deepMerge(current, opts.data ?? {});
         if (opts.name !== undefined)
             next.name = opts.name;
-        const raw = await this.client.put(`/public/api/projects/${this.enc(opts.projectKey)}/dashboards/${encodeURIComponent(dashboardId)}/`, next);
-        return this.client.safeParse(DashboardDetailsSchema, raw, "dashboards.update");
+        if (opts.listed !== undefined)
+            next.listed = opts.listed;
+        await this.validateReferences(next, pk);
+        await this.client.put(`/public/api/projects/${encodeURIComponent(pk)}/dashboards/${encodeURIComponent(dashboardId)}/`, next);
+        return this.get(dashboardId, pk);
+    }
+    async export(dashboardId, opts = {}) {
+        const pk = this.resolveProjectKey(opts.projectKey);
+        const paperSize = (opts.paperSize ?? "A4").trim();
+        if (!paperSize)
+            throw new ClientValidationError("Dashboard export paperSize must not be empty.");
+        const orientation = (opts.orientation ?? "LANDSCAPE").trim().toUpperCase();
+        if (orientation !== "PORTRAIT" && orientation !== "LANDSCAPE") {
+            throw new ClientValidationError("Dashboard export orientation must be PORTRAIT or LANDSCAPE.");
+        }
+        const fileType = (opts.fileType ?? "PDF").trim().toUpperCase();
+        if (fileType !== "PDF") {
+            throw new ClientValidationError("Dashboard export fileType must be PDF.");
+        }
+        const slideIndex = opts.slideIndex ?? 0;
+        if (!Number.isInteger(slideIndex) || slideIndex < 0) {
+            throw new ClientValidationError("Dashboard export slideIndex must be a non-negative integer.");
+        }
+        return this.client.postStream(`/public/api/projects/${encodeURIComponent(pk)}/dashboards/${encodeURIComponent(dashboardId)}/action/export`, { paperSize, orientation, fileType, slideIndex, });
     }
     async delete(dashboardId, projectKey) {
         await this.client.del(`/public/api/projects/${this.enc(projectKey)}/dashboards/${encodeURIComponent(dashboardId)}/`);

package/dist/src/skill.js

@@ -2,218 +2,16 @@ import { execFileSync, } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-const SKILL_BODY = `# Dataiku DSS agent CLI
-
-Use \`dss\` when an agent needs to inspect or change Dataiku DSS resources: projects, datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables, code envs, and connections.
-If the installed \`dss\` binary is unavailable but the repository checkout is the current workspace, prefer \`bun --no-env-file src/cli.ts ...\` or \`bun --no-env-file ./bin/dss.js ...\`. Node users can invoke the same cross-runtime launcher as \`node ./bin/dss.js ...\`; when \`dist/\` has not been built, it delegates to Bun. From another working directory, pass the checkout's absolute \`bin/dss.js\` path to Bun or Node.
-\`--no-env-file\` disables Bun's automatic preloading only; the CLI still applies its documented \`.env\` handling unless \`DATAIKU_DISABLE_ENV=1\` is set.
-
-## Contract
-
-- Command results write exactly one JSON value to stdout, including \`doctor\`, \`batch\`, and \`cleanup\` failure reports; use the exit code and result fields.
-- Dispatch/runtime failures write one JSONL error event to stderr with \`type:"error"\`, \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`, while stdout stays empty.
-- Non-fatal warnings and \`--verbose\` HTTP traces are JSONL stderr events (\`type:"warning"\` / \`type:"trace"\`), never prose.
-- No prompts, help screens, tables, banners, or prose output are part of the contract.
-- Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 a failed long-running result or synchronous assertion.
-- Pass \`--json\` for compact single-line JSON on stdout; use it for agent discovery and other JSON results to minimize tokens. Without it, success JSON is pretty-printed.
-- \`--raw\` is the only stdout escape hatch: recipe payload commands emit raw bytes to stdout unless \`--output PATH\` is also set; with \`--output\`, stdout is the JSON string equal to \`PATH\` and the file receives exact raw bytes.
-- \`--fields a,b,c\` projects those fields from object or array-of-objects results; dotted paths (\`a.b.c\`) drill into nested objects, and missing fields become \`null\`; string and scalar results pass through unchanged.
-
-## Discover commands
-
-\`\`\`text
-dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --json
-dss commands run --fields dataset.create --json
-dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples --json
-dss commands run --fields dataset --json
-dss agent contract --fields commands.actions --json
-\`\`\`
-
-Bootstrap with the scoped \`agent contract\` call above: \`protocol,agentContractVersion,cli,stdio,planning,compatibility\` cover protocol/schema compatibility, stderr event semantics, preferred discovery commands, non-JSON escape hatches, planning rules, and compatibility guarantees in ~250 tokens. Request \`schemas\` (the JSON schemas) or \`commands\` (the contract's discovery section) only when you actually need them.
-
-Before choosing command syntax, look the action up in the command registry: \`--fields RESOURCE.ACTION\` returns one complete entry, and appended \`.FIELD\` paths return only the metadata you need. Prefer the four-field projection \`usage,description,flags,examples\` by default — it is the smallest self-sufficient starting point for constructing an invocation. The registry entry is the canonical schema for flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, structured examples, payload schemas, unsafe outputs, cleanup hints, and exit codes.
-
-\`--fields\` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (\`--fields dataset.create\` returns \`{"dataset.create": {...}}\`). Enumerate every resource and action with \`dss agent contract --fields commands.actions --json\` (~1k tokens); the hundreds-of-thousands-token unscoped registry is compatibility-only. An unknown resource or action exits with code 1 and a JSON error envelope on stderr containing the valid options.
-Credential lookup order is flags first, then \`DATAIKU_*\` environment variables, then saved credentials.
-Set \`DATAIKU_DISABLE_ENV=1\` when a test must ignore both \`.env\` files and \`DATAIKU_*\` environment variables.
-When \`.env\` loading is enabled, the CLI reads \`.env\` from the command's current working directory first and then the CLI build/root directory; the invocation directory wins on conflicting keys. Put test-specific \`.env\` files in the directory where you invoke \`dss\`.
-For disposable agent tests, set \`DSS_CONFIG_DIR\` to a temporary directory so saved credentials never touch the real profile.
-
-## Planning, safety, and generic inputs
-
-- Before any registry entry with \`sideEffect:"write"\`, run the exact argv with \`--plan\` first. Planning is local: it returns the derived operation without resolving credentials or calling DSS. Check \`destructive\`, \`idempotency\`, \`async\`, \`unsafeOutputs\`, and \`exitCodes\` before execution.
-- Use \`--dry-run\` only when that action's registry entry has \`dryRun:true\`. \`--plan\` explains the operation; \`--dry-run\` exercises the action-specific simulation path. Never add an unsupported flag.
-- When a create/upload action advertises \`--record-cleanup\`, pass \`--record-cleanup cleanup.jsonl\`. \`dss cleanup --file cleanup.jsonl\` previews the recorded cleanup steps in reverse order and does not mutate DSS; add \`--apply\` only after checking the preview.
-- For JSON payload actions, follow \`inputContract\`, \`requiredFlags\`, and \`requiredOneOf\`. Prefer \`--data-file PATH\` or \`--stdin\` when advertised instead of inline \`--data\`; this preserves exact JSON across shells and keeps large or sensitive payloads out of process arguments.
-- Authenticated actions advertise \`--request-timeout MS\` and \`--retries N\`; \`--retries\` applies to idempotent GET requests. Long-running actions separately advertise controls such as \`--timeout MS\`, \`--poll-interval MS\`, and log limits; use only the flags in that action's registry entry.
-- Before live mutation tests, use \`dss fixtures --json\` to discover compatible test resources instead of guessing project objects.
-
-## Authentication
-
-Prefer environment variables for ephemeral agent runs. Use the syntax for the active shell:
-
-POSIX shell:
-
-\`\`\`sh
-export DATAIKU_URL=https://dss.example.com
-export DATAIKU_API_KEY=your-api-key
-export DATAIKU_PROJECT_KEY=MYPROJ
-\`\`\`
-
-PowerShell:
-
-\`\`\`powershell
-$env:DATAIKU_URL = "https://dss.example.com"
-$env:DATAIKU_API_KEY = "your-api-key"
-$env:DATAIKU_PROJECT_KEY = "MYPROJ"
-\`\`\`
-
-Windows Command Prompt:
-
-\`\`\`bat
-set "DATAIKU_URL=https://dss.example.com"
-set "DATAIKU_API_KEY=your-api-key"
-set "DATAIKU_PROJECT_KEY=MYPROJ"
-\`\`\`
-
-To persist credentials for later invocations:
-
-\`\`\`bash
-dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ
-\`\`\`
-
-The command saves credentials and returns \`{"saved":true,"path":"..."}\`. \`DSS_CONFIG_DIR\` wins when set. Otherwise credentials use \`XDG_CONFIG_HOME/dataiku/credentials.json\`, the \`dataiku/credentials.json\` directory under \`APPDATA\` on Windows, or \`~/.config/dataiku/credentials.json\`.
-\`auth login\` validates by listing accessible projects before saving credentials, so the API key must be allowed to call DSS project-list APIs.
-
-TLS flags: \`--insecure\` disables certificate verification; \`--ca-cert PATH\` adds a PEM CA bundle. Environment equivalents: \`NODE_TLS_REJECT_UNAUTHORIZED\`, \`NODE_EXTRA_CA_CERTS\`.
-
-## Common workflows
-
-\`\`\`text
-dss version
-dss project list
-dss dataset list --project-key MYPROJ
-dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
-dss recipe diff compute_orders --file code.py --project-key MYPROJ
-dss recipe set-payload compute_orders --file code.py --project-key MYPROJ
-dss job build-and-wait orders --include-logs --project-key MYPROJ
-dss sql query --connection analytics --sql "select 1" --project-key MYPROJ
-dss batch --data-file steps.json
-\`\`\`
-For fake-DSS smoke tests, return project lists as JSON arrays such as \`[{"projectKey":"MYPROJ","name":"My Project"}]\` from \`/public/api/projects/\`; recipe payload commands read \`/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true\` and expect a JSON object shaped like \`{"recipe":{"name":"<NAME>","type":"python"},"payload":"..."}\`.
-
-## Application release safety
-
-Treat app release as explicit validate, compare, version, successor, verify, and permission gates.
-The public app-manifest \`version\` field is raw metadata: writing it is NOT a publish transaction.
-New instances inherit the template's raw \`version\`; existing instances are never upgraded in
-place — create an additive successor (the old instance is preserved), verify it, then retire the
-old one as a separate guarded step. Never infer private publish/recreate/rename,
-recipient-sharing, or UI-click operations that the public DSS API does not expose.
-
-\`\`\`text
-dss app validate-manifest --project-key APP_TEMPLATE
-dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
-dss app manifest-version --project-key APP_TEMPLATE
-dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
-# targetProjectKey in instance.json must be confirmed absent
-dss app create-instance APP_ID --data-file instance.json --wait --record-cleanup cleanup.jsonl
-dss app create-successor-instance APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
-dss app verify-instance APP_ID --project-key RELEASE_INSTANCE_V2 --expect-version 1.4.0
-dss cleanup --file cleanup.jsonl
-dss app permissions-snapshot --project-key RELEASE_INSTANCE --output permissions.json
-dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
-dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
-\`\`\`
-
-An invalid manifest exits non-zero with the validation result in the structured error details.
-Review the cleanup preview before \`dss cleanup --file cleanup.jsonl --apply\`. Every new entry is
-bound to the canonical DSS URL. App cleanup records a \`creationTag\` hash observed after the DSS
-future identifies its target key; unconfirmed creation stops unresolved. The future target and
-later \`creationTag\` are independent, non-atomic observations because the public API exposes
-neither an immutable project ID joined to the future nor a conditional DELETE. Cleanup rechecks
-type and \`creationTag\` immediately before deletion, rejecting detected key reuse but unable to
-eliminate replacement in the remaining check-to-DELETE gap. Apply validates the full ledger before
-any request and rejects legacy, mixed-server, mismatched-server, or unbound app cleanup entries.
-The successor's cleanup ledger entry targets only the new project key;
-the predecessor is never targeted. Some DSS deployments return 403 for an unknown target project:
-instance creation requires confirmed target absence before POST, so an inaccessible target absent
-from the visible project list is still rejected as unconfirmed rather than risking cleanup against
-a pre-existing project. A definitive create rejection never produces a cleanup entry.
-
-\`app set-manifest-version\` reports
-\`concurrencyControl:"client-side-non-atomic-stale-read-check"\`. \`--expect-hash SHA256\` refuses the
-write when the manifest already changed, but the PUT itself stays unconditional: this command can
-overwrite a writer that commits inside the read-then-write window, and the post-write read cannot
-detect that lost update when this command's payload wins. Never treat the hash as a serializing lock.
-An ambiguous manifest PUT or verification read exits non-zero with \`persisted:null\`,
-\`after:null\`, and \`outcome:"indeterminate"\`; it never claims success or rejection.
-
-The API key authenticates public REST only. \`app verify-instance\` reports \`apiReady:true\`,
-\`status:"API_VERIFIED_UI_PENDING"\`, and \`uiPublicationVerified:false\`. Its \`visual-ui\` gate
-requires a pre-authenticated SSO browser session or dedicated UI test identity and evidence from
-exercising the affected tiles, forms, and actions; the CLI never marks that external gate complete.
-Permission snapshots have an integrity hash bound to the canonical DSS URL, project key, and
-observed concrete project incarnation from \`creationTag\`; diff and restore reject detected server,
-key, or incarnation mismatches. DSS exposes no conditional permission PUT, so these client-side checks
-narrow and detect key-reuse races but cannot serialize the final check with the write. Snapshots
-contain access-control identities; keep them mode \`0600\` and commit them only when repository
-policy permits.
-
-## Confirming mutations
-
-Mutations print a small JSON ack to stdout and exit 0 on success (e.g. \`{"updated":"NAME","resource":"recipe"}\`); on failure they print the error envelope to stderr and exit non-zero. The exit code is the source of truth.
-
-- For portable multi-step writes, prefer \`dss batch\` (payload: a JSON array of argv arrays). It runs fail-fast, returns one envelope with per-step \`ok\`/\`result\`/\`error\`, and exits non-zero if any step fails.
-- If separate processes are required, inspect each exit code and stop before launching the next step. Do not rely on shell chaining: syntax differs between POSIX shells, Windows PowerShell 5.1, PowerShell 7, and Command Prompt.
-- Never pipe a mutation into a command that prints a fixed string or merges stderr: a pipeline may return the helper's exit code and report a failed mutation as success.
-- To branch in code, key off the exit code or the JSON ack on stdout — never a hardcoded label.
-
-## Platform & debugging notes
-
-- Pass code and SQL via \`--file\`/\`--sql-file\`, not inline: shells (especially PowerShell) mangle quotes, \`$\`, and newlines in multi-line snippets.
-- On a non-UTF-8 console (e.g. Windows cp1252), don't print non-ASCII results; write them to a UTF-8 file and read that, or use \`--output PATH\`.
-- Build failures: \`dss job log <id> --errors-only\` surfaces just error/traceback lines, and \`--output PATH\` saves the full log to a file. Logs are one long line with JVM noise; the \`Error in Python process: At line <N>\` marker maps \`<N>\` straight to your recipe payload's source line.
-- Schema changes aren't automatic for code recipes: after changing a python/SQL/prepare recipe's output columns run \`dss dataset refresh-schema\` (or rebuild) before downstream reads, and \`dss dataset validate-build\` to catch file-backed misconfig before launching a build. Exception: \`dss recipe create --type sync\` copies the input schema onto a schemaless dataset output at create time (see \`syncOutputSchemaPropagated\` in the result), so a fresh sync output builds populated without a manual refresh.
-- \`dss dataset download\` is capped (default 100k rows) and returns \`{ path, rows, truncated, limit }\`: check \`truncated\` and raise \`--limit N\` when you need more — treat it as a sample, not a guaranteed full export. Without \`--output\` the file lands in the current working directory (and a \`dataset_download_default_location\` warning names that path); pass \`--output PATH\` to control the destination. For very large tables, aggregate in SQL or read inside a recipe instead.
-- \`dss api-service list-packages SERVICE\` first verifies the parent service through its settings. A \`not_found\` error means the service is missing (verify the service ID and project key); an empty array means the service exists but has no deployable packages. Do not reinterpret \`not_found\` as an empty package list or retry the lower-level packages route.
-- \`dss notebook clear-jupyter-outputs NAME --dry-run\` returns the full \`current\` and \`next\` notebook states. Applying it clears \`outputs\` and resets \`execution_count\` to \`0\` only on code cells, preserving markdown and raw cells unchanged.
-- \`dss sql query ... --dataset PROJECT.NAME\` first queries through the dataset. If DSS rejects that dataset connection as neither SQL nor HDFS, the CLI reads dataset metadata and retries with \`params.connection\` (using its schema or catalog as the database when available). A readable dataset with no usable connection exits with \`validation_failed\` and advises \`--connection\`; dataset metadata \`404\` and \`403\` errors propagate as \`not_found\` and \`permission_denied\`.
-- \`dss sql query ... --start-retries N\` opts the query-start POST into transient retries with exponential backoff. A lost response can cause DSS to execute the SQL more than once, so use it only for SQL whose repetition is safe; ordinary \`--retries N\` remains GET-only.
-
-## Error envelope
-
-For dispatch/runtime failures, parse stderr as JSONL; the final line is an error event:
-
-\`\`\`json
-{
-  "type": "error",
-  "ok": false,
-  "error": "Missing API key.",
-  "code": "usage_error",
-  "category": "usage",
-  "exitCode": 1,
-  "resource": "dataset",
-  "action": "list"
-}
-\`\`\`
-
-\`doctor\`, \`batch\`, and \`cleanup\` report command-level failures on stdout and leave stderr empty. Use the exit code before choosing a stream.
-Use \`code\`, \`category\`, \`exitCode\`, \`retryable\`, \`status\`, and \`details\` for recovery logic. Do not scrape message text when a structured field is available.
-Treat \`details.body\` as sanitized metadata only: it contains at most \`requestId\`/\`request_id\`/\`errorId\`/\`elapsedMs\` plus locally trusted target/timing fields, not the arbitrary DSS response body. \`details.statusText\` is canonical text derived from the numeric status, not a remote reason phrase. Base recovery on top-level \`code\`, \`category\`, \`status\`, \`retryable\`, \`requestId\`, \`hint\`, and \`details.dssCategory\`; never parse or expose assumed server-body fields.
-`;
-const SKILL_FRONTMATTER = `---
-name: dataiku-dss
-description: >-
-  Agent-only JSON CLI for Dataiku DSS. Use to inspect or mutate DSS projects,
-  datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables,
-  code envs, and connections. Discover scoped command metadata with
-  dss commands run --fields RESOURCE.ACTION --json.
----
-
-`;
+const SKILL_URLS = [
+    new URL("../skills/dataiku-dss/SKILL.md", import.meta.url),
+    new URL("../../skills/dataiku-dss/SKILL.md", import.meta.url),
+];
 function skillContent() {
-    return SKILL_FRONTMATTER + SKILL_BODY;
+    for (const skillUrl of SKILL_URLS) {
+        if (fs.existsSync(skillUrl))
+            return fs.readFileSync(skillUrl, "utf-8");
+    }
+    throw new Error(`Bundled Dataiku skill not found. Checked: ${SKILL_URLS.map((url) => url.pathname).join(", ")}`);
 }
 export const AGENTS = {
     claude: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "0.12.6",
+	"version": "0.12.7",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
 	"workspaces": [
@@ -13,6 +13,8 @@
 	},
 	"files": [
 		"dist/",
+		"plugin.json",
+		"skills/",
 		"bin/dss.js",
 		"packages/types/dist/"
 	],
@@ -22,9 +24,10 @@
 	},
 	"scripts": {
 		"build": "tsc && tsc -p packages/types/tsconfig.json",
-		"prepack": "tsc && tsc -p packages/types/tsconfig.json",
-		"prepublishOnly": "tsc && tsc -p packages/types/tsconfig.json",
-		"check": "tsc --noEmit",
+		"prepack": "node scripts/sync-plugin-version.mjs --check && tsc && tsc -p packages/types/tsconfig.json",
+		"prepublishOnly": "node scripts/sync-plugin-version.mjs --check && tsc && tsc -p packages/types/tsconfig.json",
+		"check": "tsc --noEmit && node scripts/sync-plugin-version.mjs --check",
+		"version": "node scripts/sync-plugin-version.mjs && git add plugin.json",
 		"lint": "oxlint src/",
 		"lint:fix": "oxlint --fix src/",
 		"format": "dprint fmt",

package/plugin.json

@@ -0,0 +1,15 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "dataiku-sdk",
+	"version": "0.12.7",
+	"description": "Dataiku DSS SDK and agent-oriented CLI for programmatic access to DSS REST APIs.",
+	"homepage": "https://github.com/clssck/dataiku-sdk",
+	"repository": "https://github.com/clssck/dataiku-sdk",
+	"license": "MIT",
+	"keywords": [
+		"dataiku",
+		"dss",
+		"cli",
+		"agent-skills"
+	]
+}

package/skills/dataiku-dss/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: dataiku-dss
+description: >-
+  Agent-only JSON CLI for Dataiku DSS. Use to inspect or mutate DSS projects,
+  datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables,
+  code envs, and connections. Discover scoped command metadata with
+  dss commands run --fields RESOURCE.ACTION --json.
+license: MIT
+compatibility: >-
+  Requires the dss CLI, network access to a Dataiku DSS instance, and configured
+  DATAIKU_URL and DATAIKU_API_KEY credentials. Source-checkout fallback requires Bun.
+---
+
+# Dataiku DSS agent CLI
+
+Use `dss` when an agent needs to inspect or change Dataiku DSS resources: projects, datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables, code envs, and connections.
+If the installed `dss` binary is unavailable but the repository checkout is the current workspace, prefer `bun --no-env-file src/cli.ts ...` or `bun --no-env-file ./bin/dss.js ...`. Node users can invoke the same cross-runtime launcher as `node ./bin/dss.js ...`; when `dist/` has not been built, it delegates to Bun. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun or Node.
+`--no-env-file` disables Bun's automatic preloading only; the CLI still applies its documented `.env` handling unless `DATAIKU_DISABLE_ENV=1` is set.
+
+## Contract
+
+- Command results write exactly one JSON value to stdout, including `doctor`, `batch`, and `cleanup` failure reports; use the exit code and result fields.
+- Dispatch/runtime failures write one JSONL error event to stderr with `type:"error"`, `ok:false`, `error`, `code`, and `exitCode`, while stdout stays empty.
+- Non-fatal warnings and `--verbose` HTTP traces are JSONL stderr events (`type:"warning"` / `type:"trace"`), never prose.
+- No prompts, help screens, tables, banners, or prose output are part of the contract.
+- Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 a failed long-running result or synchronous assertion.
+- Pass `--json` for compact single-line JSON on stdout; use it for agent discovery and other JSON results to minimize tokens. Without it, success JSON is pretty-printed.
+- `--raw` is the only stdout escape hatch: recipe payload commands emit raw bytes to stdout unless `--output PATH` is also set; with `--output`, stdout is the JSON string equal to `PATH` and the file receives exact raw bytes.
+- `--fields a,b,c` projects those fields from object or array-of-objects results; dotted paths (`a.b.c`) drill into nested objects, and missing fields become `null`; string and scalar results pass through unchanged.
+
+## Discover commands
+
+```text
+dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --json
+dss commands run --fields dataset.create --json
+dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples --json
+dss commands run --fields dataset --json
+dss agent contract --fields commands.actions --json
+```
+
+Bootstrap with the scoped `agent contract` call above: `protocol,agentContractVersion,cli,stdio,planning,compatibility` cover protocol/schema compatibility, stderr event semantics, preferred discovery commands, non-JSON escape hatches, planning rules, and compatibility guarantees in ~250 tokens. Request `schemas` (the JSON schemas) or `commands` (the contract's discovery section) only when you actually need them.
+
+Before choosing command syntax, look the action up in the command registry: `--fields RESOURCE.ACTION` returns one complete entry, and appended `.FIELD` paths return only the metadata you need. Prefer the four-field projection `usage,description,flags,examples` by default — it is the smallest self-sufficient starting point for constructing an invocation. The registry entry is the canonical schema for flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, structured examples, payload schemas, unsafe outputs, cleanup hints, and exit codes.
+
+`--fields` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (`--fields dataset.create` returns `{"dataset.create": {...}}`). Enumerate every resource and action with `dss agent contract --fields commands.actions --json` (~1k tokens); the hundreds-of-thousands-token unscoped registry is compatibility-only. An unknown resource or action exits with code 1 and a JSON error envelope on stderr containing the valid options.
+Credential lookup order is flags first, then `DATAIKU_*` environment variables, then saved credentials.
+Set `DATAIKU_DISABLE_ENV=1` when a test must ignore both `.env` files and `DATAIKU_*` environment variables.
+When `.env` loading is enabled, the CLI reads `.env` from the command's current working directory first and then the CLI build/root directory; the invocation directory wins on conflicting keys. Put test-specific `.env` files in the directory where you invoke `dss`.
+For disposable agent tests, set `DSS_CONFIG_DIR` to a temporary directory so saved credentials never touch the real profile.
+
+## Planning, safety, and generic inputs
+
+- Before any registry entry with `sideEffect:"write"`, run the exact argv with `--plan` first. Planning is local: it returns the derived operation without resolving credentials or calling DSS. Check `destructive`, `idempotency`, `async`, `unsafeOutputs`, and `exitCodes` before execution.
+- Use `--dry-run` only when that action's registry entry has `dryRun:true`. `--plan` explains the operation; `--dry-run` exercises the action-specific simulation path. Never add an unsupported flag.
+- When a create/upload action advertises `--record-cleanup`, pass `--record-cleanup cleanup.jsonl`. `dss cleanup --file cleanup.jsonl` previews the recorded cleanup steps in reverse order and does not mutate DSS; add `--apply` only after checking the preview.
+- For JSON payload actions, follow `inputContract`, `requiredFlags`, and `requiredOneOf`. Prefer `--data-file PATH` or `--stdin` when advertised instead of inline `--data`; this preserves exact JSON across shells and keeps large or sensitive payloads out of process arguments.
+- Authenticated actions advertise `--request-timeout MS` and `--retries N`; `--retries` applies to idempotent GET requests. Long-running actions separately advertise controls such as `--timeout MS`, `--poll-interval MS`, and log limits; use only the flags in that action's registry entry.
+- Before live mutation tests, use `dss fixtures --json` to discover compatible test resources instead of guessing project objects.
+
+## Authentication
+
+Prefer environment variables for ephemeral agent runs. Use the syntax for the active shell:
+
+POSIX shell:
+
+```sh
+export DATAIKU_URL=https://dss.example.com
+export DATAIKU_API_KEY=your-api-key
+export DATAIKU_PROJECT_KEY=MYPROJ
+```
+
+PowerShell:
+
+```powershell
+$env:DATAIKU_URL = "https://dss.example.com"
+$env:DATAIKU_API_KEY = "your-api-key"
+$env:DATAIKU_PROJECT_KEY = "MYPROJ"
+```
+
+Windows Command Prompt:
+
+```bat
+set "DATAIKU_URL=https://dss.example.com"
+set "DATAIKU_API_KEY=your-api-key"
+set "DATAIKU_PROJECT_KEY=MYPROJ"
+```
+
+To persist credentials for later invocations:
+
+```bash
+dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ
+```
+
+The command saves credentials and returns `{"saved":true,"path":"..."}`. `DSS_CONFIG_DIR` wins when set. Otherwise credentials use `XDG_CONFIG_HOME/dataiku/credentials.json`, the `dataiku/credentials.json` directory under `APPDATA` on Windows, or `~/.config/dataiku/credentials.json`.
+`auth login` validates by listing accessible projects before saving credentials, so the API key must be allowed to call DSS project-list APIs.
+
+TLS flags: `--insecure` disables certificate verification; `--ca-cert PATH` adds a PEM CA bundle. Environment equivalents: `NODE_TLS_REJECT_UNAUTHORIZED`, `NODE_EXTRA_CA_CERTS`.
+
+## Common workflows
+
+```text
+dss version
+dss project list
+dss dataset list --project-key MYPROJ
+dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
+dss recipe diff compute_orders --file code.py --project-key MYPROJ
+dss recipe set-payload compute_orders --file code.py --project-key MYPROJ
+dss job build-and-wait orders --include-logs --project-key MYPROJ
+dss sql query --connection analytics --sql "select 1" --project-key MYPROJ
+dss batch --data-file steps.json
+```
+For fake-DSS smoke tests, return project lists as JSON arrays such as `[{"projectKey":"MYPROJ","name":"My Project"}]` from `/public/api/projects/`; recipe payload commands read `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` and expect a JSON object shaped like `{"recipe":{"name":"<NAME>","type":"python"},"payload":"..."}`.
+
+## Application release safety
+
+Treat app release as explicit validate, compare, version, successor, verify, and permission gates.
+The public app-manifest `version` field is raw metadata: writing it is NOT a publish transaction.
+New instances inherit the template's raw `version`; existing instances are never upgraded in
+place — create an additive successor (the old instance is preserved), verify it, then retire the
+old one as a separate guarded step. Never infer private publish/recreate/rename,
+recipient-sharing, or UI-click operations that the public DSS API does not expose.
+
+```text
+dss app validate-manifest --project-key APP_TEMPLATE
+dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
+dss app manifest-version --project-key APP_TEMPLATE
+dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+# targetProjectKey in instance.json must be confirmed absent
+dss app create-instance APP_ID --data-file instance.json --wait --record-cleanup cleanup.jsonl
+dss app create-successor-instance APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
+dss app verify-instance APP_ID --project-key RELEASE_INSTANCE_V2 --expect-version 1.4.0
+dss cleanup --file cleanup.jsonl
+dss app permissions-snapshot --project-key RELEASE_INSTANCE --output permissions.json
+dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
+dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
+```
+
+An invalid manifest exits non-zero with the validation result in the structured error details.
+Review the cleanup preview before `dss cleanup --file cleanup.jsonl --apply`. Every new entry is
+bound to the canonical DSS URL. App cleanup records a `creationTag` hash observed after the DSS
+future identifies its target key; unconfirmed creation stops unresolved. The future target and
+later `creationTag` are independent, non-atomic observations because the public API exposes
+neither an immutable project ID joined to the future nor a conditional DELETE. Cleanup rechecks
+type and `creationTag` immediately before deletion, rejecting detected key reuse but unable to
+eliminate replacement in the remaining check-to-DELETE gap. Apply validates the full ledger before
+any request and rejects legacy, mixed-server, mismatched-server, or unbound app cleanup entries.
+The successor's cleanup ledger entry targets only the new project key;
+the predecessor is never targeted. Some DSS deployments return 403 for an unknown target project:
+instance creation requires confirmed target absence before POST, so an inaccessible target absent
+from the visible project list is still rejected as unconfirmed rather than risking cleanup against
+a pre-existing project. A definitive create rejection never produces a cleanup entry.
+
+`app set-manifest-version` reports
+`concurrencyControl:"client-side-non-atomic-stale-read-check"`. `--expect-hash SHA256` refuses the
+write when the manifest already changed, but the PUT itself stays unconditional: this command can
+overwrite a writer that commits inside the read-then-write window, and the post-write read cannot
+detect that lost update when this command's payload wins. Never treat the hash as a serializing lock.
+An ambiguous manifest PUT or verification read exits non-zero with `persisted:null`,
+`after:null`, and `outcome:"indeterminate"`; it never claims success or rejection.
+
+The API key authenticates public REST only. `app verify-instance` reports `apiReady:true`,
+`status:"API_VERIFIED_UI_PENDING"`, and `uiPublicationVerified:false`. Its `visual-ui` gate
+requires a pre-authenticated SSO browser session or dedicated UI test identity and evidence from
+exercising the affected tiles, forms, and actions; the CLI never marks that external gate complete.
+Permission snapshots have an integrity hash bound to the canonical DSS URL, project key, and
+observed concrete project incarnation from `creationTag`; diff and restore reject detected server,
+key, or incarnation mismatches. DSS exposes no conditional permission PUT, so these client-side checks
+narrow and detect key-reuse races but cannot serialize the final check with the write. Snapshots
+contain access-control identities; keep them mode `0600` and commit them only when repository
+policy permits.
+
+## Confirming mutations
+
+Mutations print a small JSON ack to stdout and exit 0 on success (e.g. `{"updated":"NAME","resource":"recipe"}`); on failure they print the error envelope to stderr and exit non-zero. The exit code is the source of truth.
+
+- For portable multi-step writes, prefer `dss batch` (payload: a JSON array of argv arrays). It runs fail-fast, returns one envelope with per-step `ok`/`result`/`error`, and exits non-zero if any step fails.
+- If separate processes are required, inspect each exit code and stop before launching the next step. Do not rely on shell chaining: syntax differs between POSIX shells, Windows PowerShell 5.1, PowerShell 7, and Command Prompt.
+- Never pipe a mutation into a command that prints a fixed string or merges stderr: a pipeline may return the helper's exit code and report a failed mutation as success.
+- To branch in code, key off the exit code or the JSON ack on stdout — never a hardcoded label.
+
+## Platform & debugging notes
+
+- Pass code and SQL via `--file`/`--sql-file`, not inline: shells (especially PowerShell) mangle quotes, `$`, and newlines in multi-line snippets.
+- On a non-UTF-8 console (e.g. Windows cp1252), don't print non-ASCII results; write them to a UTF-8 file and read that, or use `--output PATH`.
+- Build failures: `dss job log <id> --errors-only` surfaces just error/traceback lines, and `--output PATH` saves the full log to a file. Logs are one long line with JVM noise; the `Error in Python process: At line <N>` marker maps `<N>` straight to your recipe payload's source line.
+- Schema changes aren't automatic for code recipes: after changing a python/SQL/prepare recipe's output columns run `dss dataset refresh-schema` (or rebuild) before downstream reads, and `dss dataset validate-build` to catch file-backed misconfig before launching a build. Exception: `dss recipe create --type sync` copies the input schema onto a schemaless dataset output at create time (see `syncOutputSchemaPropagated` in the result), so a fresh sync output builds populated without a manual refresh.
+- `dss dataset download` is capped (default 100k rows) and returns `{ path, rows, truncated, limit }`: check `truncated` and raise `--limit N` when you need more — treat it as a sample, not a guaranteed full export. Without `--output` the file lands in the current working directory (and a `dataset_download_default_location` warning names that path); pass `--output PATH` to control the destination. For very large tables, aggregate in SQL or read inside a recipe instead.
+- `dss dashboard create` and `dss dashboard update` validate every `INSIGHT` tile before mutation: `insightId` and `targetInsightId` must agree and resolve, and any `datasetSmartName` must resolve. Missing or stale references exit with `validation_failed` before POST/PUT. Cross-project `PROJECT.DATASET` references require the API key to read that dataset project; a `403` blocks the save rather than silently accepting an unverifiable dashboard.
+- `dss api-service list-packages SERVICE` first verifies the parent service through its settings. A `not_found` error means the service is missing (verify the service ID and project key); an empty array means the service exists but has no deployable packages. Do not reinterpret `not_found` as an empty package list or retry the lower-level packages route.
+- `dss notebook clear-jupyter-outputs NAME --dry-run` returns the full `current` and `next` notebook states. Applying it clears `outputs` and resets `execution_count` to `0` only on code cells, preserving markdown and raw cells unchanged.
+- `dss sql query ... --dataset PROJECT.NAME` first queries through the dataset. If DSS rejects that dataset connection as neither SQL nor HDFS, the CLI reads dataset metadata and retries with `params.connection` (using its schema or catalog as the database when available). A readable dataset with no usable connection exits with `validation_failed` and advises `--connection`; dataset metadata `404` and `403` errors propagate as `not_found` and `permission_denied`.
+- `dss sql query ... --start-retries N` opts the query-start POST into transient retries with exponential backoff. A lost response can cause DSS to execute the SQL more than once, so use it only for SQL whose repetition is safe; ordinary `--retries N` remains GET-only.
+
+## Error envelope
+
+For dispatch/runtime failures, parse stderr as JSONL; the final line is an error event:
+
+```json
+{
+  "type": "error",
+  "ok": false,
+  "error": "Missing API key.",
+  "code": "usage_error",
+  "category": "usage",
+  "exitCode": 1,
+  "resource": "dataset",
+  "action": "list"
+}
+```
+
+`doctor`, `batch`, and `cleanup` report command-level failures on stdout and leave stderr empty. Use the exit code before choosing a stream.
+Use `code`, `category`, `exitCode`, `retryable`, `status`, and `details` for recovery logic. Do not scrape message text when a structured field is available.
+Treat `details.body` as sanitized metadata only: it contains at most `requestId`/`request_id`/`errorId`/`elapsedMs` plus locally trusted target/timing fields, not the arbitrary DSS response body. `details.statusText` is canonical text derived from the numeric status, not a remote reason phrase. Base recovery on top-level `code`, `category`, `status`, `retryable`, `requestId`, `hint`, and `details.dssCategory`; never parse or expose assumed server-body fields.