callman-mcp 0.1.0 → 0.2.0

package/dist-cjs/domain/scenario/summarize.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compactReportView = exports.scenarioFullView = exports.scenarioGraphView = exports.scenarioSummaryView = void 0;
+exports.compactReportView = exports.nodeDetailView = exports.scenarioFullView = exports.scenarioNodeView = exports.scenarioGraphView = exports.scenarioSummaryView = void 0;
 const mask_js_1 = require("../../lib/mask.js");
 const truncate_js_1 = require("../../lib/truncate.js");
+const nodeConfig_js_1 = require("./nodeConfig.js");
 const scenarioSummaryView = (scenario, folderName) => ({
     id: scenario.id,
     name: scenario.name,
@@ -12,9 +13,11 @@ const scenarioSummaryView = (scenario, folderName) => ({
     ...(folderName !== undefined ? { folder: folderName } : {}),
     reviewStatus: scenario.reviewStatus,
     version: scenario.version,
+    ...(scenario.approvedVersion !== undefined && scenario.approvedVersion !== null ? { approvedVersion: scenario.approvedVersion } : {}),
     nodeCount: scenario.nodes.length,
     edgeCount: scenario.edges.length,
     environments: (scenario.environments ?? []).map((environment) => ({ id: environment.id, name: environment.name })),
+    ...(scenario.dataset ? { dataset: { columns: scenario.dataset.columns, rows: scenario.dataset.rows.length } } : {}),
     ...(scenario.groupName ? { group: scenario.groupName } : {}),
     ...(scenario.permissions ? { permissions: scenario.permissions } : {}),
     updatedAt: scenario.updatedAt ?? null,
@@ -42,33 +45,41 @@ const nodeHint = (type, config) => {
         case "wait":
             return { durationMs: config.durationMs ?? null };
         case "subscenario":
-            return { scenarioId: config.scenarioId ?? null };
+        case "foreach":
+            return { innerNodes: Array.isArray(config.nodes) ? config.nodes.length : 0 };
+        case "scenario-ref":
+            return { referencedScenario: config.referencedScenarioName ?? config.referencedScenarioId ?? null };
         default:
             return {};
     }
 };
-const maskConfig = (config, reveal) => {
-    if (reveal)
-        return config;
-    const out = { ...config };
-    if (out.auth && typeof out.auth === "object")
-        out.auth = (0, mask_js_1.maskAuth)(out.auth);
-    for (const key of ["password", "clientSecret", "token", "apiKey", "secret"]) {
-        if (typeof out[key] === "string" && out[key])
-            out[key] = (0, mask_js_1.maskSecret)(out[key]);
-    }
-    return out;
+const scenarioNodeView = (scenario, nodeId, options = {}) => {
+    const node = scenario.nodes.find((entry) => entry.id === nodeId || entry.data?.label === nodeId);
+    if (!node)
+        return null;
+    const config = node.data?.config ?? {};
+    return {
+        id: node.id,
+        type: node.type,
+        label: node.data?.label ?? null,
+        position: node.position,
+        config: options.reveal ? config : (0, nodeConfig_js_1.maskConfigInPlace)(config),
+        incoming: scenario.edges.filter((edge) => edge.target === node.id).map((edge) => ({ from: edge.source, ...(edge.type && edge.type !== "default" ? { type: edge.type } : {}) })),
+        outgoing: scenario.edges.filter((edge) => edge.source === node.id).map((edge) => ({ to: edge.target, ...(edge.type && edge.type !== "default" ? { type: edge.type } : {}) })),
+    };
 };
+exports.scenarioNodeView = scenarioNodeView;
 const scenarioFullView = (scenario, options = {}) => {
     const nodes = scenario.nodes.map((node) => {
-        const config = maskConfig(node.data?.config ?? {}, options.reveal ?? false);
+        const config = options.reveal ? (node.data?.config ?? {}) : (0, nodeConfig_js_1.maskConfigInPlace)(node.data?.config ?? {});
         const text = (0, truncate_js_1.safeStringify)(config);
         return {
             id: node.id,
             type: node.type,
             label: node.data?.label ?? null,
             position: node.position,
-            config: text.length > truncate_js_1.LIMITS.BODY_PREVIEW ? { _truncated: true, preview: (0, truncate_js_1.clip)(text, truncate_js_1.LIMITS.BODY_PREVIEW) } : config,
+            // A clipped config is marked so it can never be written back.
+            config: text.length > truncate_js_1.LIMITS.BODY_PREVIEW ? { _truncated: true, preview: (0, truncate_js_1.clip)(text, truncate_js_1.LIMITS.BODY_PREVIEW), note: `Read it whole with get_scenario node: "${node.id}".` } : config,
         };
     });
     const view = {
@@ -85,19 +96,23 @@ const scenarioFullView = (scenario, options = {}) => {
             })),
         })),
         dataset: scenario.dataset ?? null,
+        dbSettings: scenario.dbSettings ?? null,
     };
     const bytes = (0, truncate_js_1.byteLength)(view);
     if (bytes > truncate_js_1.LIMITS.SCENARIO_FULL) {
-        return { ...(0, exports.scenarioGraphView)(scenario), truncated: true, bytes, note: `Full view is ${bytes} bytes (limit ${truncate_js_1.LIMITS.SCENARIO_FULL}); graph view returned instead.` };
+        return { ...(0, exports.scenarioGraphView)(scenario), truncated: true, bytes, note: `Full view is ${bytes} bytes (limit ${truncate_js_1.LIMITS.SCENARIO_FULL}); graph view returned instead — read nodes one by one with get_scenario node: "<id>".` };
     }
     return view;
 };
 exports.scenarioFullView = scenarioFullView;
 // ── reports ───────────────────────────────────────────────────────────
 const testCounts = (results) => {
-    const passed = (results ?? []).filter((result) => result.status === "PASS").length;
-    const total = (results ?? []).length;
-    return { passed, failed: total - passed };
+    const list = results ?? [];
+    return {
+        passed: list.filter((result) => result.status === "PASS").length,
+        failed: list.filter((result) => result.status === "FAIL").length,
+        ...(list.some((result) => result.status === "SKIP") ? { skipped: list.filter((result) => result.status === "SKIP").length } : {}),
+    };
 };
 const nodeRow = (node) => ({
     nodeId: node.nodeId,
@@ -111,11 +126,50 @@ const nodeRow = (node) => ({
     tests: testCounts(node.scriptResults),
     contracts: testCounts(node.contractResults),
     ...(node.conditionResult !== undefined && node.conditionResult !== null ? { conditionResult: node.conditionResult } : {}),
+    ...(node.activeBranch ? { branch: node.activeBranch } : {}),
+});
+// failed_continued = the node failed but the execution policy went on.
+const FAILED_STATUSES = new Set(["failed", "failed_continued", "error", "timeout"]);
+const FAILED_DETAIL_MAX = 5;
+// Scalars as they are; objects as a bounded preview.
+const valuePreview = (value) => (value !== null && typeof value === "object" ? (0, truncate_js_1.jsonPreview)(value) : value);
+// Everything a model needs to fix ONE node: failed tests/checks/contracts
+// with expected vs actual, the input as resolved at run time, the script
+// error with its line, the response and the last log lines.
+const nodeDetailView = (node) => ({
+    ...nodeRow(node),
+    ...(node.continuedAfterFailure ? { continuedAfterFailure: true } : {}),
+    failedTests: (node.scriptResults ?? []).filter((result) => result.status === "FAIL").map((result) => ({ name: result.name, message: result.message ?? null })),
+    ...(node.assertionResults && node.assertionResults.length > 0
+        ? {
+            checks: node.assertionResults.map((check) => ({
+                name: check.name ?? null,
+                passed: check.passed ?? null,
+                ...(check.message ? { message: (0, truncate_js_1.clip)(String(check.message), 300) } : {}),
+                ...(check.expected !== undefined ? { expected: valuePreview(check.expected) } : {}),
+                ...(check.actual !== undefined ? { actual: valuePreview(check.actual) } : {}),
+            })),
+        }
+        : {}),
+    ...(node.contractResults && node.contractResults.some((result) => result.status === "FAIL")
+        ? {
+            failedContracts: node.contractResults
+                .filter((result) => result.status === "FAIL")
+                .slice(0, 20)
+                .map((result) => ({ name: result.name ?? result.path ?? null, message: result.message ? (0, truncate_js_1.clip)(result.message, 300) : null })),
+        }
+        : {}),
+    ...(node.contractValidationError ? { contractValidationError: node.contractValidationError } : {}),
+    ...(node.script?.runtimeError ? { scriptError: node.script.runtimeError } : {}),
+    ...(node.resolvedInputSnapshot !== undefined && node.resolvedInputSnapshot !== null ? { resolvedInput: (0, truncate_js_1.jsonPreview)((0, nodeConfig_js_1.maskConfigInPlace)(node.resolvedInputSnapshot)) } : {}),
+    response: (0, truncate_js_1.jsonPreview)(node.response ?? node.outputSnapshot),
+    logs: (node.logs ?? []).slice(-10).map((entry) => (0, truncate_js_1.clip)(String(entry.message ?? ""), 300)),
 });
-const FAILED_STATUSES = new Set(["failed", "error", "timeout"]);
+exports.nodeDetailView = nodeDetailView;
 const compactReportView = (report) => {
     const nodes = report.nodeResults ?? [];
-    const failed = nodes.find((node) => FAILED_STATUSES.has(String(node.status)));
+    const failed = nodes.filter((node) => FAILED_STATUSES.has(String(node.status)));
+    const unexpected = report.finalContext?.unexpectedError;
     return {
         reportId: report.id,
         scenarioId: report.scenarioId,
@@ -123,22 +177,25 @@ const compactReportView = (report) => {
         scenarioVersion: report.scenarioVersion,
         status: report.status,
         triggerType: report.triggerType,
+        ...(report.environmentId ? { environmentId: report.environmentId } : {}),
         startedAt: report.startedAt,
         endedAt: report.endedAt,
         durationMs: report.durationMs,
         summary: report.summary,
+        // An error outside every node (bad graph at run time, engine error) —
+        // the run failed with no failing node to show.
+        ...(unexpected ? { unexpectedError: typeof unexpected === "string" ? (0, truncate_js_1.clip)(unexpected, 1000) : (0, truncate_js_1.jsonPreview)(unexpected) } : {}),
         nodes: nodes.map(nodeRow),
-        ...(failed
+        ...(failed.length > 0 ? { failedNodes: failed.slice(0, FAILED_DETAIL_MAX).map(exports.nodeDetailView) } : {}),
+        ...(failed.length > FAILED_DETAIL_MAX ? { moreFailedNodes: failed.length - FAILED_DETAIL_MAX, note: "Read any node with get_scenario_report node: \"<nodeId>\"." } : {}),
+        ...(report.iterations && report.iterations.length > 0
             ? {
-                failedNodeDetail: {
-                    ...nodeRow(failed),
-                    failedTests: (failed.scriptResults ?? []).filter((result) => result.status === "FAIL").map((result) => ({ name: result.name, message: result.message ?? null })),
-                    response: (0, truncate_js_1.jsonPreview)(failed.response ?? failed.outputSnapshot),
-                    logs: (failed.logs ?? []).slice(-10).map((entry) => (0, truncate_js_1.clip)(String(entry.message ?? ""), 300)),
-                },
+                iterations: report.iterations.slice(0, 50).map((iteration, index) => ({
+                    row: typeof iteration.index === "number" ? iteration.index + 1 : index + 1,
+                    status: iteration.status ?? null,
+                })),
             }
             : {}),
-        ...(report.iterations && report.iterations.length > 0 ? { iterations: report.iterations.length } : {}),
     };
 };
 exports.compactReportView = compactReportView;

package/dist-cjs/lib/mask.js

@@ -1,11 +1,12 @@
 "use strict";
 // Secret masking on the way OUT to the model. The backend already masks
 // environment values for a personal token; this covers what it does not —
-// request auth secrets, sensitive headers and anything a local run resolved.
+// request auth secrets and sensitive headers (requestShape.authInputView,
+// scenario nodeConfig.maskConfigInPlace, lib/redact for local runs).
 // Same sentinel as the backend so a masked value is recognisable and can
 // never be written back by accident (the server rejects it).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maskVariableValues = exports.maskAuth = exports.maskHeaderRecord = exports.maskHeaderValue = exports.isSensitiveHeader = exports.isMasked = exports.maskSecret = exports.MASK_SENTINEL = void 0;
+exports.maskHeaderValue = exports.isSensitiveHeader = exports.isMasked = exports.maskSecret = exports.MASK_SENTINEL = void 0;
 exports.MASK_SENTINEL = "••••";
 const maskSecret = (value) => value.length >= 8 ? `${exports.MASK_SENTINEL}${value.slice(-2)}` : exports.MASK_SENTINEL;
 exports.maskSecret = maskSecret;
@@ -24,49 +25,3 @@ const isSensitiveHeader = (name) => SENSITIVE_HEADERS.has(name.trim().toLowerCas
 exports.isSensitiveHeader = isSensitiveHeader;
 const maskHeaderValue = (name, value) => (0, exports.isSensitiveHeader)(name) && value ? (0, exports.maskSecret)(value) : value;
 exports.maskHeaderValue = maskHeaderValue;
-const maskHeaderRecord = (headers) => {
-    const out = {};
-    for (const [key, value] of Object.entries(headers ?? {}))
-        out[key] = (0, exports.maskHeaderValue)(key, value);
-    return out;
-};
-exports.maskHeaderRecord = maskHeaderRecord;
-// Compact, masked view of a request's auth: enough to know HOW it
-// authenticates, never the credential itself.
-const maskAuth = (auth) => {
-    const type = auth?.type ?? "none";
-    switch (type) {
-        case "bearer":
-            return { type, token: auth?.bearerToken ? (0, exports.maskSecret)(auth.bearerToken) : "" };
-        case "basic":
-            return {
-                type,
-                username: auth?.basicUsername ?? "",
-                password: auth?.basicPassword ? (0, exports.maskSecret)(auth.basicPassword) : "",
-            };
-        case "apikey":
-            return {
-                type,
-                key: auth?.apiKeyKey ?? "",
-                value: auth?.apiKeyValue ? (0, exports.maskSecret)(auth.apiKeyValue) : "",
-                location: auth?.apiKeyLocation ?? "header",
-            };
-        case "oauth2": {
-            const oauth2 = auth?.oauth2 ?? {};
-            return {
-                type,
-                grantType: oauth2.grantType ?? "client_credentials",
-                tokenUrl: oauth2.tokenUrl ?? "",
-                clientId: oauth2.clientId ?? "",
-                clientSecret: typeof oauth2.clientSecret === "string" && oauth2.clientSecret ? (0, exports.maskSecret)(oauth2.clientSecret) : "",
-                scope: oauth2.scope ?? "",
-            };
-        }
-        default:
-            return { type: "none" };
-    }
-};
-exports.maskAuth = maskAuth;
-// Mask every `value` in a key/value list (environment / scenario variables).
-const maskVariableValues = (variables) => variables.map((variable) => ({ ...variable, value: (0, exports.maskSecret)(variable.value), valueMasked: true }));
-exports.maskVariableValues = maskVariableValues;

package/dist-cjs/lib/pagination.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sliceWithCursor = exports.nextCursorFor = exports.pageFromCursor = exports.clampLimit = exports.decodeCursor = exports.encodeCursor = void 0;
+const errors_js_1 = require("../client/errors.js");
 const truncate_js_1 = require("./truncate.js");
 const encodeCursor = (cursor) => Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
 exports.encodeCursor = encodeCursor;
@@ -13,7 +14,7 @@ const decodeCursor = (raw) => {
             return null;
         if (!Number.isInteger(parsed.page) || parsed.page < 1)
             return null;
-        return { page: parsed.page, limit: (0, exports.clampLimit)(parsed.limit) };
+        return { page: parsed.page, limit: (0, exports.clampLimit)(parsed.limit), ...(typeof parsed.q === "string" ? { q: parsed.q } : {}) };
     }
     catch {
         return null;
@@ -22,11 +23,15 @@ const decodeCursor = (raw) => {
 exports.decodeCursor = decodeCursor;
 const clampLimit = (limit) => Math.min(truncate_js_1.LIMITS.LIST_MAX, Math.max(1, Math.floor(limit ?? truncate_js_1.LIMITS.LIST_DEFAULT)));
 exports.clampLimit = clampLimit;
-const pageFromCursor = (cursor, limit) => {
+const pageFromCursor = (cursor, limit, q = "") => {
+    if (!cursor)
+        return { page: 1, limit: (0, exports.clampLimit)(limit) };
     const decoded = (0, exports.decodeCursor)(cursor);
-    if (decoded)
-        return decoded;
-    return { page: 1, limit: (0, exports.clampLimit)(limit) };
+    if (!decoded)
+        throw new errors_js_1.ToolInputError("CURSOR_INVALID", "That cursor is not one this server issued — pass the nextCursor from the previous result verbatim, or omit it for the first page.");
+    if ((decoded.q ?? "") !== q)
+        throw new errors_js_1.ToolInputError("CURSOR_QUERY_MISMATCH", "That cursor belongs to a different query — omit it to start this query from the first page.");
+    return decoded;
 };
 exports.pageFromCursor = pageFromCursor;
 const nextCursorFor = (pagination) => pagination.page < pagination.totalPages
@@ -34,15 +39,15 @@ const nextCursorFor = (pagination) => pagination.page < pagination.totalPages
     : null;
 exports.nextCursorFor = nextCursorFor;
 // Client-side slice for list endpoints that are not paginated server-side.
-const sliceWithCursor = (items, cursor, limit) => {
-    const { page, limit: size } = (0, exports.pageFromCursor)(cursor, limit);
+const sliceWithCursor = (items, cursor, limit, q = "") => {
+    const { page, limit: size } = (0, exports.pageFromCursor)(cursor, limit, q);
     const start = (page - 1) * size;
     const slice = items.slice(start, start + size);
     const totalPages = Math.max(1, Math.ceil(items.length / size));
     return {
         items: slice,
         total: items.length,
-        nextCursor: page < totalPages ? (0, exports.encodeCursor)({ page: page + 1, limit: size }) : null,
+        nextCursor: page < totalPages ? (0, exports.encodeCursor)({ page: page + 1, limit: size, ...(q ? { q } : {}) }) : null,
     };
 };
 exports.sliceWithCursor = sliceWithCursor;

package/dist-cjs/lib/redact.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedactor = void 0;
+const mask_js_1 = require("./mask.js");
+// Run output never carries variable VALUES: every value the run held is
+// turned back into its `{{key}}` wherever it shows up (the URL, headers, query
+// and body as sent, the response). The model still sees WHICH variable went
+// where — "{{baseUrl}}/users/{{userId}}" — which is what it needs to debug,
+// and a token a login script stored is as hidden as one from the environment.
+// Credentials that are not variables (a literal bearer token, an API key
+// header named by the request's auth) are masked by name.
+// Short values ("1", "yes", "GET") would shred ordinary text.
+const MIN_VALUE_LENGTH = 4;
+const createRedactor = (knownValues, options = {}) => {
+    const pairs = knownValues
+        .filter(([, value]) => value.length >= MIN_VALUE_LENGTH)
+        .sort((a, b) => b[1].length - a[1].length);
+    const secretHeaders = new Set([...(options.secretHeaders ?? [])].map((name) => name.toLowerCase()));
+    const secretQuery = new Set([...(options.secretQuery ?? [])].map((name) => name.toLowerCase()));
+    const text = (input) => {
+        let out = input;
+        for (const [key, value] of pairs)
+            if (out.includes(value))
+                out = out.split(value).join(`{{${key}}}`);
+        for (const name of secretQuery) {
+            out = out.replace(new RegExp(`([?&]${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=)([^&#]*)`, "gi"), (_match, prefix, secret) => `${prefix}${secret.startsWith("{{") ? secret : (0, mask_js_1.maskSecret)(secret)}`);
+        }
+        return out;
+    };
+    const value = (input) => {
+        if (typeof input === "string")
+            return text(input);
+        if (Array.isArray(input))
+            return input.map(value);
+        if (input && typeof input === "object") {
+            return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, value(child)]));
+        }
+        return input;
+    };
+    const masked = (name, raw, secretNames) => {
+        const redacted = text(raw);
+        if (redacted !== raw)
+            return redacted; // (part of) it came from a variable
+        return (secretNames.has(name.toLowerCase()) || (secretNames === secretHeaders && (0, mask_js_1.isSensitiveHeader)(name))) && raw ? (0, mask_js_1.maskSecret)(raw) : redacted;
+    };
+    return {
+        text,
+        value,
+        headers: (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([name, raw]) => [name, masked(name, Array.isArray(raw) ? raw.join(", ") : String(raw), secretHeaders)])),
+        query: (query) => Object.fromEntries(Object.entries(query ?? {}).map(([name, raw]) => [name, masked(name, String(raw), secretQuery)])),
+    };
+};
+exports.createRedactor = createRedactor;

package/dist-cjs/lib/strict.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.strictObject = exports.unknownKeysErrorMap = void 0;
+const zod_1 = require("zod");
+// Strict objects: an unknown or misspelled key is an ERROR naming the valid
+// keys — never silently stripped (zod's default), because a stripped key
+// means the tool quietly does something other than what was asked
+// (`workspaceId` instead of `workspace` → the default workspace; `strokeColor`
+// instead of `stroke` → an unstyled node, reported as success).
+// `noun` names one key ("style key", "argument"); `where` says whose.
+const unknownKeysErrorMap = (noun, validKeys, where) => (issue, ctx) => issue.code === zod_1.z.ZodIssueCode.unrecognized_keys
+    ? {
+        message: `Unknown ${noun}${issue.keys.length === 1 ? "" : "s"} ${issue.keys.map((key) => `"${key}"`).join(", ")}${where ? ` for ${where}` : ""}. Valid ${noun}s: ${validKeys.join(", ")}`,
+    }
+    : { message: ctx.defaultError };
+exports.unknownKeysErrorMap = unknownKeysErrorMap;
+const strictObject = (shape, noun, where) => zod_1.z.object(shape, { errorMap: (0, exports.unknownKeysErrorMap)(noun, Object.keys(shape), where) }).strict();
+exports.strictObject = strictObject;

package/dist-cjs/prompts/index.js

@@ -38,7 +38,7 @@ Steps:
 Steps:
 1. Read \`callman://diagram/components\` — use ONLY those \`type\` values.
 2. From the code and configuration (docker-compose, Kubernetes manifests, terraform, env files, package manifests) identify: services/apps, databases and caches, message brokers/queues, external APIs, auth providers, observability, cloud resources, and the boundaries they live in (VPC, cluster, namespace).
-3. Model 8–25 nodes with 1–3 word labels. Put components inside boundaries with \`parent\` (declare the container node). Give each edge a meaning: \`sync\` for request/response calls, \`async\` for events/callbacks, \`bus\` for streams/queues, \`fallback\` for retries or optional paths. Short edge labels (protocol or event name) only where they add information.
+3. Model 8–25 nodes with 1–3 word labels. Put components inside boundaries with \`parent\` — the boundary is a \`frame\` (or \`pool.horizontal\` / \`pool.vertical\`) node. Give each boundary its own color so zones read at a glance: \`style: { stroke: "#8B5CF6", fill: "rgba(139,92,246,0.07)", textColor: "#8B5CF6", strokeWidth: 2, bold: true }\` (see \`callman://docs/diagram-schema\` → Styling). Give each edge a meaning: \`sync\` for request/response calls, \`async\` for events/callbacks, \`bus\` for streams/queues, \`fallback\` for retries or optional paths. Short edge labels (protocol or event name) only where they add information.
 4. Call \`create_diagram\` with \`name: "${name ?? "<system name>"}"\`, no positions (automatic layout). If it reports unknown types, fix them with the suggestions and retry.
 5. Describe the diagram in a few sentences and tell me it is in the Callman Diagrams library (Refresh to see it). For corrections use \`patch_diagram\`, not a full rebuild.`));
     server.registerPrompt("create_scenario_from_flow", {
@@ -52,17 +52,17 @@ Steps:
     }, ({ flow, collection, workspace }) => user(`Create a Callman scenario that tests this flow${where(workspace)}: ${flow}
 
 Steps:
-1. Read \`callman://docs/scenario-nodes\` for the node types and their config fields.
-2. Find the requests to reuse with \`search_requests\`${collection ? ` in the collection "${collection}"` : ""} and read the ones you need with \`get_request\` (method, url, body, auth). Request nodes carry their own config — copy method/url/headers/body from the saved request and use \`{{variables}}\` for values produced by earlier steps.
-3. Build the graph: one \`request\` node per call; an \`assertion\` node after each important response (status code, key fields); \`set-vars\` to capture ids/tokens from responses for later steps; a \`condition\` with \`yes\`/\`no\` edges where the flow branches; \`poll\` for eventually-consistent checks; an \`end\` node last. Add a scenario environment with the variables the flow needs.
-4. Call \`create_scenario\` with \`dryRun: true\`, review the resolved graph, then create it for real.
-5. Offer to run it with \`run_scenario\` and to explain the report. On-prem: mention that the scenario is a draft until approved in the desktop app.`));
+1. Read \`callman://docs/scenario-nodes\` for the node types, their config fields, what is required, labels and graph rules.
+2. Find the requests to reuse with \`search_requests\`${collection ? ` in the collection "${collection}"` : ""} and read the ones you need with \`get_request\` (reveal: true if you need the real credentials — a masked value cannot be saved). Request nodes carry their own config — copy method/url/headers/query/body/auth from the saved request (the request tools' shapes are accepted and converted) and use \`{{Label.body.path}}\` / \`{{env.KEY}}\` for values produced by earlier steps.
+3. Build the graph: one \`request\` node per call with a unique identifier label (\`Login\`, \`CreateOrder\`); an \`assertion\` node after each important response (checks with left/operator/right); \`set-vars\` to capture ids/tokens; a \`condition\` with \`yes\`/\`no\` edges where the flow branches; \`poll\` for eventually-consistent checks; an \`end\` node last. db/redis/kafka nodes need a \`connectionId\` from \`list_connections\`. Add a scenario environment with the variables the flow needs.
+4. Call \`create_scenario\` with \`dryRun: true\`, review the resolved nodes, then create it for real. Fix anything listed under \`warnings\` (config keys the server ignored) with \`patch_scenario\`.
+5. Offer to run it with \`run_scenario\` and to explain the report (\`failedNodes\` has the failing checks with expected vs actual). On-prem: a personal token runs the APPROVED version — use \`submit_scenario\` and have it approved first.`));
     server.registerPrompt("document_collection", {
         title: "Document an API collection",
         description: "Read a Callman collection and write API documentation (Markdown or an OpenAPI skeleton) from its requests.",
         argsSchema: {
             collection: zod_1.z.string().describe("Collection id or name"),
-            format: zod_1.z.string().optional().describe("markdown (default) or openapi"),
+            format: zod_1.z.enum(["markdown", "openapi"]).optional().describe("markdown (default) or openapi"),
             workspace: zod_1.z.string().optional(),
         },
     }, ({ collection, format, workspace }) => user(`Document the Callman collection "${collection}"${where(workspace)} as ${format === "openapi" ? "an OpenAPI 3.1 skeleton" : "Markdown"}.

package/dist-cjs/resources/docs/contracts.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTRACTS_DOC = void 0;
+const callman_core_1 = require("callman-core");
+const contracts_js_1 = require("../../domain/contracts.js");
+exports.CONTRACTS_DOC = `# Contract checks on a request
+
+Two documents attached to a saved request — the desktop's Contracts tab. Every runner
+(desktop, CLI, \`run_request\`, \`run_collection\`) evaluates them after the response and
+reports them next to the \`pm.test\` results.
+
+| Tool | Does |
+|---|---|
+| \`get_contract_checks\` | read the rules (with ids) and the data contract |
+| \`add_contract_rules\` | add up to 200 rules at once (\`replace: true\` swaps the whole set) |
+| \`update_contract_rule\` | change one rule's path, rules or enabled |
+| \`delete_contract_rules\` | delete some or all rules |
+| \`test_contract_rules\` | evaluate the enabled rules against a sample body — nothing is sent or saved |
+| \`set_data_contract\` / \`delete_data_contract\` | replace / remove the data-driven contract |
+
+## Field rules
+\`{ "path": "<field path>", "rules": { … }, "enabled": true }\`
+\`\`\`jsonc
+{ "path": "users[].id",       "rules": { "required": true, "type": "string", "format": "uuid" } }
+{ "path": "users",            "rules": { "type": "array", "minItems": 1, "unique": { "mode": "byField", "fields": ["id"] } } }
+{ "path": "total",            "rules": { "type": "number", "integer": true, "min": 0 } }
+{ "path": "status",           "rules": { "enumValues": ["NEW", "PAID", "SHIPPED"] } }
+{ "path": "email",            "rules": { "format": "email", "notEmpty": true } }
+{ "path": "response.status",  "rules": { "equals": 200 } }
+{ "path": "response.headers.content-type", "rules": { "startsWith": "application/json" } }
+\`\`\`
+
+### Paths
+- Body fields with dots: \`user.address.city\`.
+- \`[]\` checks EVERY element: \`users[].id\`, \`[].name\` (top-level array) — one result per element.
+- \`[n]\` checks one element: \`items[0].price\`.
+- \`response.status\`, \`response.headers.<lower-case name>\`, \`response.duration\` (ms) check the
+  HTTP envelope instead of the body.
+
+### Rules (combine freely; at least one per rule)
+| Applies to | Rules |
+|---|---|
+| any | \`required\`, \`type\` (string · number · boolean · object · array · null), \`equals\`, \`notEmpty\`, \`enumValues\` |
+| numbers | \`min\`, \`max\`, \`greaterThan\`, \`lessThan\`, \`integer\`, \`positive\`, \`negative\`, \`nonZero\` |
+| strings | \`minLength\`, \`maxLength\`, \`pattern\` (JS regex), \`contains\`, \`notContains\`, \`startsWith\`, \`endsWith\`, \`caseSensitive\` (default true), \`format\` |
+| arrays | \`minItems\`, \`maxItems\`, \`sorted: { order: asc|desc, field? }\`, \`unique: { mode: whole|byField, fields? }\` |
+| objects | \`requiredKeys\`, \`forbiddenKeys\`, \`minProperties\`, \`maxProperties\`, \`strictSchema\` (no keys beyond requiredKeys) |
+
+\`format\`: ${callman_core_1.SCENARIO_CONTRACT_FORMATS.join(", ")}.
+
+The server also refuses contradictions: min > max, minLength > maxLength, minItems > maxItems,
+greaterThan ≥ lessThan, a key both required and forbidden, \`unique.mode: "byField"\` without
+fields, an invalid regex.
+
+## Data-driven contract
+The request runs ONCE PER ROW; the row's values are \`{{data.<column>}}\` and each row checks its
+own expected status and field assertions (same rules as above).
+\`\`\`jsonc
+{
+  "columns": ["userId", "expected"],
+  "rows": [
+    { "data": { "userId": "1",   "expected": "Ann" }, "expectedStatus": 200,
+      "assertions": [{ "path": "name", "rules": { "equals": "Ann" } }] },
+    { "data": { "userId": "404", "expected": "" },    "expectedStatus": 404 }
+  ]
+}
+\`\`\`
+Put the \`{{data.<column>}}\` tokens into the request (url, query, headers, body) with
+\`update_request\` — \`set_data_contract\` warns about columns the request does not use yet.
+Limits: ${contracts_js_1.DATA_CONTRACT_LIMITS.columns} columns, ${contracts_js_1.DATA_CONTRACT_LIMITS.rows} rows, ${contracts_js_1.DATA_CONTRACT_LIMITS.assertions} assertions per row, ${contracts_js_1.DATA_CONTRACT_LIMITS.cell} characters per cell.
+
+## Contract checks vs pm.test
+Use contract rules for the SHAPE of a response (types, formats, required fields, ranges) —
+declarative, shown per field in reports. Use \`pm.test\` in \`postResponseScript\` for logic that
+needs code (cross-field checks, saving values with \`pm.environment.set\`).
+`;