@eigenpal/cli 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @eigenpal/cli
 
+## 0.10.5
+
+### Minor Changes
+
+- d3a8b79: Workflow dataset commands now handle nested file references in example inputs, so local dataset archives can round-trip file-backed examples through the CLI without flattening the input shape.
+
+### Patch Changes
+
+- 9343b8c: Add `eigenpal workflow schema <workflow>` to print a workflow's inferred output schema — the fields and files it returns, typed from its own steps — as JSON Schema, or as a TypeScript or Python type with `--format`.
+- 9343b8c: `workflow validate` gains an `--online` flag that checks cross-workflow `action.invoke-workflow` references against the server (target existence, input type-match, missing/unknown input keys, undeclared output, and invoke cycles). Local validation can only check a workflow's own shape, so these reference errors previously surfaced only at push; run `eigenpal workflow validate --online` to catch them beforehand.
+
 ## 0.10.2
 
 ### Patch Changes

package/dist/cli.js

@@ -17083,6 +17083,251 @@ var require_picocolors = __commonJS((exports, module) => {
 // ../types/src/core/index.ts
 var init_core3 = () => {};
 
+// ../types/src/files/legacy-boundary.ts
+var LEGACY_FILE_REF_COMPATIBILITY;
+var init_legacy_boundary = __esm(() => {
+  LEGACY_FILE_REF_COMPATIBILITY = [
+    {
+      id: "legacy-workflow-execution-routes",
+      description: "Old workflow execution list/detail routes may hydrate historical { fileId } trigger inputs for display only."
+    },
+    {
+      id: "rerun-old-immutable-runs",
+      description: "Rerun may remap historical immutable { fileId } trigger inputs while copying those bytes into the new run."
+    },
+    {
+      id: "processor-adapter-runtime-handles",
+      description: "Executor/headless/CLI adapters may normalize local, S3, inline, or fileId runtime handles into private ResolvedProcessorFile objects before processor invocation."
+    }
+  ];
+});
+
+// ../types/src/files/runtime-file-ref.ts
+function isRuntimeFileRef(input) {
+  return RuntimeFileRefSchema.safeParse(input).success;
+}
+function isResolvedProcessorFile(input) {
+  return ResolvedProcessorFileSchema.safeParse(input).success;
+}
+function normalizeLegacyFileIdInput(input) {
+  return {
+    kind: "file",
+    fileId: input.fileId,
+    ...input.filename ? { filename: input.filename } : {},
+    ...input.mimeType ? { mimeType: input.mimeType } : {}
+  };
+}
+var DbFileRefSchema, LegacyFileIdInputSchema, LocalFileRefSchema, S3FileRefSchema, InlineFileRefSchema, RuntimeFileRefSchema, FilePathDescriptorSchema, ResolvedProcessorFileSchema, STRING_SCHEMA, WORKFLOW_FILE_REF_JSON_SCHEMA;
+var init_runtime_file_ref = __esm(() => {
+  init_zod();
+  DbFileRefSchema = exports_external.object({
+    kind: exports_external.literal("file"),
+    fileId: exports_external.string().describe("File ID from files table"),
+    filename: exports_external.string().optional().describe("Original filename"),
+    mimeType: exports_external.string().optional().describe("MIME type")
+  });
+  LegacyFileIdInputSchema = exports_external.object({
+    kind: exports_external.never().optional(),
+    fileId: exports_external.string().describe("File ID from files table"),
+    filename: exports_external.string().optional().describe("Original filename"),
+    mimeType: exports_external.string().optional().describe("MIME type")
+  });
+  LocalFileRefSchema = exports_external.object({
+    kind: exports_external.literal("local"),
+    path: exports_external.string().describe("Absolute path to a file on disk"),
+    filename: exports_external.string().describe("Original filename"),
+    mimeType: exports_external.string().describe("MIME type of the file")
+  });
+  S3FileRefSchema = exports_external.object({
+    kind: exports_external.literal("s3"),
+    ref: exports_external.string().describe("Storage key (suffix-only, prefix added by adapter)"),
+    filename: exports_external.string().describe("Original filename"),
+    mimeType: exports_external.string().describe("MIME type of the file")
+  });
+  InlineFileRefSchema = exports_external.object({
+    kind: exports_external.literal("inline"),
+    base64: exports_external.string().describe("Base64-encoded file bytes"),
+    filename: exports_external.string().describe("Original filename"),
+    mimeType: exports_external.string().describe("MIME type of the file")
+  });
+  RuntimeFileRefSchema = exports_external.discriminatedUnion("kind", [
+    DbFileRefSchema,
+    LocalFileRefSchema,
+    S3FileRefSchema,
+    InlineFileRefSchema
+  ]);
+  FilePathDescriptorSchema = exports_external.discriminatedUnion("kind", [
+    LocalFileRefSchema,
+    S3FileRefSchema,
+    InlineFileRefSchema
+  ]);
+  ResolvedProcessorFileSchema = exports_external.object({
+    __eigenpalFile: exports_external.literal(true),
+    source: exports_external.enum(["db", "tenant-s3", "local", "inline"]),
+    filename: exports_external.string().describe("Display filename for processor logs and parser routing"),
+    mimeType: exports_external.string().describe("MIME type for processor routing"),
+    fileId: exports_external.string().optional().describe("Legacy files-table id for db-backed handles"),
+    ref: exports_external.string().optional().describe("Tenant-scoped storage key suffix for S3-backed handles"),
+    path: exports_external.string().optional().describe("Local filesystem path for headless/CLI handles"),
+    base64: exports_external.string().optional().describe("Base64 bytes for inline handles")
+  }).strict();
+  STRING_SCHEMA = { type: "string" };
+  WORKFLOW_FILE_REF_JSON_SCHEMA = {
+    "x-eigenpal-type": "file",
+    type: "object",
+    anyOf: [
+      {
+        type: "object",
+        required: ["$file"],
+        additionalProperties: false,
+        properties: {
+          $file: STRING_SCHEMA
+        }
+      },
+      {
+        type: "object",
+        required: ["$fileId"],
+        additionalProperties: false,
+        properties: {
+          $fileId: STRING_SCHEMA
+        }
+      },
+      {
+        type: "object",
+        required: ["$inline"],
+        additionalProperties: false,
+        properties: {
+          $inline: {
+            type: "object",
+            required: ["filename", "mimeType", "base64"],
+            additionalProperties: false,
+            properties: {
+              filename: STRING_SCHEMA,
+              mimeType: STRING_SCHEMA,
+              base64: STRING_SCHEMA
+            }
+          }
+        }
+      }
+    ]
+  };
+});
+
+// ../types/src/files/scoped-file-ref.ts
+function isScopedFileRef(value) {
+  return ScopedFileRefSchema.safeParse(value).success;
+}
+function isFileIdIngressRef(value) {
+  return FileIdIngressRefSchema.safeParse(value).success;
+}
+function isInlineFileIngressRef(value) {
+  return InlineFileIngressRefSchema.safeParse(value).success;
+}
+function isFileIngressRef(value) {
+  return FileIngressRefSchema.safeParse(value).success;
+}
+function isFileReferenceSentinel(value) {
+  return FileReferenceSentinelSchema.safeParse(value).success;
+}
+function fileReferenceKind(ref) {
+  if ("$file" in ref)
+    return "file";
+  if ("$fileId" in ref)
+    return "fileId";
+  return "inline";
+}
+function validateScopedArtifactPath(path, options = {}) {
+  if (path.length === 0)
+    return { ok: false, reason: "path is empty" };
+  if (path.startsWith("/"))
+    return { ok: false, reason: "leading slash not allowed" };
+  if (path.includes("\\"))
+    return { ok: false, reason: "backslashes not allowed" };
+  if (path.includes("\x00"))
+    return { ok: false, reason: "null bytes not allowed" };
+  const segments = path.split("/");
+  for (const segment of segments) {
+    if (segment.length === 0)
+      return { ok: false, reason: "empty path segment not allowed" };
+    if (segment === ".")
+      return { ok: false, reason: "current-directory segment not allowed" };
+    if (segment === "..")
+      return { ok: false, reason: "path traversal segment not allowed" };
+  }
+  if (segments[0] === "tenants" || segments[0] === "automations" || segments[0] === "workflows" || segments[0] === "agents") {
+    return { ok: false, reason: "storage prefixes are not allowed in scoped file refs" };
+  }
+  const normalizedRoots = (options.allowedRoots ?? []).map((root) => root.replace(/^\/+|\/+$/g, ""));
+  if (normalizedRoots.length > 0 && !normalizedRoots.some((root) => path === root || path.startsWith(`${root}/`))) {
+    return { ok: false, reason: `path root must be one of: ${normalizedRoots.join(", ")}` };
+  }
+  return { ok: true, value: { path: segments.join("/"), segments, root: segments[0] } };
+}
+function collectFileReferenceSentinels(value) {
+  const matches = [];
+  walkFileReferenceSentinels(value, (match) => {
+    matches.push(match);
+  });
+  return matches;
+}
+function walkFileReferenceSentinels(value, visit, path = []) {
+  const parsed = FileReferenceSentinelSchema.safeParse(value);
+  if (parsed.success) {
+    visit({ path, ref: parsed.data, kind: fileReferenceKind(parsed.data) });
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walkFileReferenceSentinels(item, visit, [...path, String(index)]));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      walkFileReferenceSentinels(item, visit, [...path, key]);
+    }
+  }
+}
+function mapFileReferenceSentinels(value, mapper, path = []) {
+  const parsed = FileReferenceSentinelSchema.safeParse(value);
+  if (parsed.success) {
+    return mapper({ path, ref: parsed.data, kind: fileReferenceKind(parsed.data) });
+  }
+  if (Array.isArray(value)) {
+    return value.map((item, index) => mapFileReferenceSentinels(item, mapper, [...path, String(index)]));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = mapFileReferenceSentinels(item, mapper, [...path, key]);
+    }
+    return out;
+  }
+  return value;
+}
+var ScopedFileRefSchema, FileIdIngressRefSchema, InlineFileIngressPayloadSchema, InlineFileIngressRefSchema, FileIngressRefSchema, FileReferenceSentinelSchema;
+var init_scoped_file_ref = __esm(() => {
+  init_zod();
+  ScopedFileRefSchema = exports_external.object({
+    $file: exports_external.string().min(1).describe("Owner-relative artifact path")
+  }).strict();
+  FileIdIngressRefSchema = exports_external.object({
+    $fileId: exports_external.string().min(1).describe("Reusable file-pool id to materialize")
+  }).strict();
+  InlineFileIngressPayloadSchema = exports_external.object({
+    filename: exports_external.string().min(1).describe("Original filename for the materialized artifact"),
+    mimeType: exports_external.string().min(1).describe("MIME type for the materialized artifact"),
+    base64: exports_external.string().min(1).describe("Base64-encoded file bytes")
+  }).strict();
+  InlineFileIngressRefSchema = exports_external.object({
+    $inline: InlineFileIngressPayloadSchema
+  }).strict();
+  FileIngressRefSchema = exports_external.union([FileIdIngressRefSchema, InlineFileIngressRefSchema]);
+  FileReferenceSentinelSchema = exports_external.union([
+    ScopedFileRefSchema,
+    FileIdIngressRefSchema,
+    InlineFileIngressRefSchema
+  ]);
+});
+
 // ../types/src/processor/index.ts
 var init_processor = () => {};
 
@@ -23915,7 +24160,7 @@ function workflowInputTypeToJsonSchema(def) {
     case "boolean":
       return { type: "boolean" };
     case "file":
-      return { ...FILE_REF_SCHEMA };
+      return { ...WORKFLOW_FILE_REF_JSON_SCHEMA };
     case "array":
       return { type: "array", items: itemsToJsonSchema(def.items) };
     case "object":
@@ -23928,7 +24173,7 @@ function itemsToJsonSchema(items) {
   if (!items)
     return {};
   if (items.type === "file")
-    return { ...FILE_REF_SCHEMA };
+    return { ...WORKFLOW_FILE_REF_JSON_SCHEMA };
   if (items.type === "enum" && items.values && items.values.length > 0) {
     return { type: "string", enum: items.values };
   }
@@ -24032,9 +24277,7 @@ function withPendingFileRefs(input, files) {
   const refsByField = {};
   for (const f of files) {
     (refsByField[f.fieldName] ??= []).push({
-      fileId: PENDING_FILE_REF,
-      filename: f.filename,
-      mimeType: f.mimeType
+      $file: `input/${f.fieldName}/${PENDING_FILE_REF}-${f.filename}`
     });
   }
   const merged = { ...input };
@@ -24089,8 +24332,9 @@ function coerceScalar(value, type) {
   }
   return;
 }
-var INPUT_VALIDATION_CODES, FILE_REF_SCHEMA, PENDING_FILE_REF = "__pending_upload__";
+var INPUT_VALIDATION_CODES, PENDING_FILE_REF = "__pending_upload__";
 var init_input = __esm(() => {
+  init_runtime_file_ref();
   init_ajv();
   INPUT_VALIDATION_CODES = [
     "missing_required",
@@ -24100,16 +24344,6 @@ var init_input = __esm(() => {
     "array_length",
     "invalid_value"
   ];
-  FILE_REF_SCHEMA = {
-    type: "object",
-    required: ["fileId"],
-    "x-eigenpal-type": "file",
-    properties: {
-      fileId: { type: "string" },
-      filename: { type: "string" },
-      mimeType: { type: "string" }
-    }
-  };
 });
 
 // ../types/src/validation/output.ts
@@ -62096,7 +62330,7 @@ var init_step_configs = __esm(() => {
     text: exports_external.string().describe("Extracted text from the document")
   });
   TransformXlsxToJsonConfigSchema = exports_external.object({
-    input: exports_external.string().min(1, "Input is required").describe("File input - template expression e.g. {{input.document}} resolving to fileId or file path descriptor"),
+    input: exports_external.string().min(1, "Input is required").describe("File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime"),
     sheet: exports_external.union([exports_external.number().int().min(0), exports_external.string()]).optional().describe("Sheet to read: 0-based index or sheet name. Omit for first sheet."),
     outputCsv: exports_external.boolean().default(false).describe("If true, also write CSV to storage and include fileId in output"),
     outputFilename: exports_external.string().optional().describe("Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv")
@@ -62221,12 +62455,12 @@ var init_step_configs = __esm(() => {
   });
   ActionInvokeWorkflowConfigSchema = exports_external.object({
     workflowId: exports_external.string().min(1, "Workflow ID is required").describe("ID of workflow to invoke"),
-    input: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Input to pass to workflow"),
-    wait: exports_external.boolean().optional().describe("If true, wait for the invoked workflow to complete (default: false)"),
-    timeout: exports_external.number().optional().describe("Max wait time in ms when wait=true (default: 300000)"),
-    pollInterval: exports_external.number().optional().describe("How often to poll status in ms when wait=true (default: 1000)")
+    input: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Input record keyed by the invoked workflow's declared inputs"),
+    wait: exports_external.boolean().optional().describe("Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget."),
+    timeout: exports_external.number().optional().describe("Max wait time in ms when waiting (default: 300000)"),
+    pollInterval: exports_external.number().optional().describe("How often to poll status in ms when waiting (default: 1000)")
   });
-  ActionInvokeWorkflowOutputSchema = exports_external.record(exports_external.string(), exports_external.unknown()).describe("Output from invoked workflow");
+  ActionInvokeWorkflowOutputSchema = exports_external.record(exports_external.string(), exports_external.unknown()).describe("When wait is true, the invoked workflow's declared output fields are flattened to the top level alongside a `files` array — reference them as {{ steps.<invoke>.output.<field> }} (there is no `.data` or `.result` wrapper). When wait is false, execution metadata. Call get_workflow_output_schema to see the exact resolved fields.");
   ActionWebsiteReaderConfigSchema = exports_external.object({
     url: exports_external.string().min(1, "URL is required").describe("Website URL to fetch (supports template expressions)"),
     timeout: exports_external.number().positive().default(30000).optional().describe("Timeout in milliseconds"),
@@ -62719,7 +62953,7 @@ var init_workflow = __esm(() => {
     triggerMethods: exports_external.array(TriggerMethodSchema).default([{ type: "manual" }]),
     inputs: exports_external.array(WorkflowInputDefSchema).optional(),
     steps: exports_external.array(StepSchema),
-    output: exports_external.record(exports_external.string(), exports_external.string()).optional(),
+    output: exports_external.union([exports_external.record(exports_external.string(), exports_external.string()), exports_external.string()]).optional(),
     settings: WorkflowSettingsSchema.optional(),
     defaultModel: exports_external.string().optional()
   });
@@ -63032,6 +63266,117 @@ var init_execution2 = __esm(() => {
   });
 });
 
+// ../types/src/workflow/invoke-workflow-contract.ts
+function inputToJsonSchema(input) {
+  switch (input.type) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "integer":
+      return { type: "integer" };
+    case "boolean":
+      return { type: "boolean" };
+    case "object":
+      return { type: "object" };
+    case "enum":
+      return input.values && input.values.length > 0 ? { type: "string", enum: input.values } : { type: "string" };
+    case "array": {
+      const itemType = input.items?.type;
+      if (itemType === "enum" && input.items?.values?.length) {
+        return { type: "array", items: { type: "string", enum: input.items.values } };
+      }
+      return itemType ? { type: "array", items: { type: itemType } } : { type: "array" };
+    }
+    case "file":
+      return {};
+    default:
+      return {};
+  }
+}
+function buildWorkflowInputsJsonSchema(inputs) {
+  const properties = {};
+  const required2 = [];
+  for (const input of inputs ?? []) {
+    properties[input.name] = inputToJsonSchema(input);
+    if (input.required !== false)
+      required2.push(input.name);
+  }
+  return { type: "object", additionalProperties: false, required: required2, properties };
+}
+function workflowInputAcceptsType(inputType, resolvedType) {
+  if (resolvedType === "unknown" || resolvedType === "null")
+    return true;
+  switch (inputType) {
+    case "string":
+    case "enum":
+      return resolvedType === "string";
+    case "number":
+    case "integer":
+      return resolvedType === "number" || resolvedType === "integer";
+    case "boolean":
+      return resolvedType === "boolean";
+    case "array":
+      return resolvedType === "array";
+    case "file":
+      return resolvedType === "file" || resolvedType === "object" || resolvedType === "array";
+    case "object":
+    default:
+      return true;
+  }
+}
+function buildWorkflowOutputContractSchema(output) {
+  if (typeof output === "string")
+    return;
+  const keys = Object.keys(output ?? {});
+  if (keys.length === 0)
+    return;
+  const properties = {};
+  for (const key of keys)
+    properties[key] = {};
+  return { type: "object", additionalProperties: false, required: keys, properties };
+}
+function hasDeclaredOutput(output) {
+  if (typeof output === "string")
+    return output.trim().length > 0;
+  return !!output && Object.keys(output).length > 0;
+}
+function* iterateSteps(steps) {
+  if (!Array.isArray(steps))
+    return;
+  for (const raw of steps) {
+    if (!raw || typeof raw !== "object")
+      continue;
+    const step = raw;
+    yield step;
+    for (const value of Object.values(step)) {
+      if (!Array.isArray(value))
+        continue;
+      for (const item of value) {
+        if (!item || typeof item !== "object")
+          continue;
+        const obj = item;
+        if ("type" in obj) {
+          yield* iterateSteps([obj]);
+        } else if (Array.isArray(obj.steps)) {
+          yield* iterateSteps(obj.steps);
+        }
+      }
+    }
+  }
+}
+function collectInvokeWorkflowTargetIds(definition) {
+  const ids = new Set;
+  for (const step of iterateSteps(definition?.steps)) {
+    if (step.type === "action.invoke-workflow") {
+      const id = step.with?.workflowId;
+      if (typeof id === "string" && id.length > 0)
+        ids.add(id);
+    }
+  }
+  return [...ids];
+}
+
 // ../types/src/workflow/index.ts
 var init_workflow2 = __esm(() => {
   init_step_configs();
@@ -65643,11 +65988,14 @@ __export(exports_src, {
   workspaceDependencyNameToPackagePath: () => workspaceDependencyNameToPackagePath,
   workflowTriggerConfigSchema: () => workflowTriggerConfigSchema,
   workflowInputsToJsonSchema: () => workflowInputsToJsonSchema,
+  workflowInputAcceptsType: () => workflowInputAcceptsType,
   withPendingFileRefs: () => withPendingFileRefs,
+  walkFileReferenceSentinels: () => walkFileReferenceSentinels,
   valuesMatch: () => valuesMatch,
   validateWorkspaceSchema: () => validateWorkspaceSchema,
   validateStepConfig: () => validateStepConfig,
   validateSourcePackageRequiredFiles: () => validateSourcePackageRequiredFiles,
+  validateScopedArtifactPath: () => validateScopedArtifactPath,
   validateOutput: () => validateOutput,
   validateInput: () => validateInput,
   validateFileSourceConfig: () => validateFileSourceConfig,
@@ -65690,11 +66038,13 @@ __export(exports_src, {
   parseFailureEnvelope: () => parseFailureEnvelope,
   parseAutomationTarget: () => parseAutomationTarget,
   parseAgentRerunVersion: () => parseAgentRerunVersion,
+  normalizeLegacyFileIdInput: () => normalizeLegacyFileIdInput,
   noopTracingContext: () => noopTracingContext,
   mimeTypeForExtension: () => mimeTypeForExtension,
   matchS3Path: () => matchS3Path,
   mapOCRAttributes: () => mapOCRAttributes,
   mapLLMAttributes: () => mapLLMAttributes,
+  mapFileReferenceSentinels: () => mapFileReferenceSentinels,
   listStepTypesByCategory: () => listStepTypesByCategory,
   listStepTypes: () => listStepTypes,
   listProcessorIds: () => listProcessorIds,
@@ -65703,19 +66053,27 @@ __export(exports_src, {
   isWorkflowResult: () => isWorkflowResult,
   isTerminalExecutionStatus: () => isTerminalExecutionStatus,
   isStepCategory: () => isStepCategory,
+  isScopedFileRef: () => isScopedFileRef,
   isSchemaFile: () => isSchemaFile,
+  isRuntimeFileRef: () => isRuntimeFileRef,
   isRunInSampleRank: () => isRunInSampleRank,
   isRunExpandSection: () => isRunExpandSection,
+  isResolvedProcessorFile: () => isResolvedProcessorFile,
   isOutputSchemaUnknown: () => isOutputSchemaUnknown,
   isNonSuccessTerminalExecutionStatus: () => isNonSuccessTerminalExecutionStatus,
   isManualTriggerEnabled: () => isManualTriggerEnabled,
   isLocalAgentResourcePath: () => isLocalAgentResourcePath,
+  isInlineFileIngressRef: () => isInlineFileIngressRef,
+  isFileReferenceSentinel: () => isFileReferenceSentinel,
   isFilePathDescriptor: () => isFilePathDescriptor,
   isFileOutput: () => isFileOutput,
+  isFileIngressRef: () => isFileIngressRef,
+  isFileIdIngressRef: () => isFileIdIngressRef,
   isAutomationTriggerEnabled: () => isAutomationTriggerEnabled,
   isAgentEmailExplicitlyDisabled: () => isAgentEmailExplicitlyDisabled,
   inputsWithSource: () => inputsWithSource,
   hasTriggerMethod: () => hasTriggerMethod,
+  hasDeclaredOutput: () => hasDeclaredOutput,
   goldenFileSatisfiedInResult: () => goldenFileSatisfiedInResult,
   getTriggerMethods: () => getTriggerMethods,
   getSupportedFormatsLabel: () => getSupportedFormatsLabel,
@@ -65739,6 +66097,7 @@ __export(exports_src, {
   formatReleaseTag: () => formatReleaseTag,
   formatHostedSourceExportPath: () => formatHostedSourceExportPath,
   formatDiffValue: () => formatDiffValue,
+  fileReferenceKind: () => fileReferenceKind,
   fileFieldNamesFromJsonSchema: () => fileFieldNamesFromJsonSchema,
   fieldStemFromGoldenName: () => fieldStemFromGoldenName,
   extractFieldMetadata: () => extractFieldMetadata,
@@ -65759,7 +66118,11 @@ __export(exports_src, {
   compareExpectedValues: () => compareExpectedValues,
   compareExpectedError: () => compareExpectedError,
   combineEvalScores: () => combineEvalScores,
+  collectInvokeWorkflowTargetIds: () => collectInvokeWorkflowTargetIds,
+  collectFileReferenceSentinels: () => collectFileReferenceSentinels,
   coerceInput: () => coerceInput,
+  buildWorkflowOutputContractSchema: () => buildWorkflowOutputContractSchema,
+  buildWorkflowInputsJsonSchema: () => buildWorkflowInputsJsonSchema,
   buildS3PathSuffix: () => buildS3PathSuffix,
   buildS3Path: () => buildS3Path,
   buildDiscreteJudgeSystemPrompt: () => buildDiscreteJudgeSystemPrompt,
@@ -65788,6 +66151,7 @@ __export(exports_src, {
   WaitStepSchema: () => WaitStepSchema,
   WORKFLOW_TOOL_METADATA: () => WORKFLOW_TOOL_METADATA,
   WORKFLOW_NAME_PATTERN: () => WORKFLOW_NAME_PATTERN,
+  WORKFLOW_FILE_REF_JSON_SCHEMA: () => WORKFLOW_FILE_REF_JSON_SCHEMA,
   WORKFLOW_EXECUTION_STATUSES: () => WORKFLOW_EXECUTION_STATUSES,
   UNSUPPORTED_SOURCE_MANIFEST_FILENAME: () => UNSUPPORTED_SOURCE_MANIFEST_FILENAME,
   TriggerTypeValue: () => TriggerTypeValue,
@@ -65851,6 +66215,7 @@ __export(exports_src, {
   SharedEvaluatorReferenceSchema: () => SharedEvaluatorReferenceSchema,
   SharedEvaluatorCompositionItemSchema: () => SharedEvaluatorCompositionItemSchema,
   SecretNameSchema: () => SecretNameSchema,
+  ScopedFileRefSchema: () => ScopedFileRefSchema,
   ScopeStackSchema: () => ScopeStackSchema,
   ScopeEntryTypeSchema: () => ScopeEntryTypeSchema,
   ScopeEntrySchema: () => ScopeEntrySchema,
@@ -65865,10 +66230,14 @@ __export(exports_src, {
   SOURCE_COMMIT_SHA_PATTERN: () => SOURCE_COMMIT_SHA_PATTERN,
   SCRIPT_FN_MAX_BYTES: () => SCRIPT_FN_MAX_BYTES,
   S3_PATH_GRAMMAR: () => S3_PATH_GRAMMAR,
+  S3FileRefSchema: () => S3FileRefSchema,
+  RuntimeFileRefSchema: () => RuntimeFileRefSchema,
+  RuntimeFilePathDescriptorSchema: () => FilePathDescriptorSchema,
   RunTargetStringSchema: () => RunTargetStringSchema,
   RunTargetSchema: () => RunTargetSchema,
   RunTargetObjectSchema: () => RunTargetObjectSchema,
   RootSourceManifestSchema: () => RootSourceManifestSchema,
+  ResolvedProcessorFileSchema: () => ResolvedProcessorFileSchema,
   ReleaseTagSchema: () => ReleaseTagSchema,
   RUN_TARGET_SEGMENT_PATTERN: () => RUN_TARGET_SEGMENT_PATTERN,
   RUN_EXPAND_SECTIONS: () => RUN_EXPAND_SECTIONS,
@@ -65907,16 +66276,22 @@ __export(exports_src, {
   MergeConfigSchema: () => MergeConfigSchema,
   ManualTriggerMethodSchema: () => ManualTriggerMethodSchema,
   MAX_PAGE_SIZE: () => MAX_PAGE_SIZE,
+  LocalFileRefSchema: () => LocalFileRefSchema,
   LocalEvaluatorReferenceSchema: () => LocalEvaluatorReferenceSchema,
   LocalEvaluatorCompositionItemSchema: () => LocalEvaluatorCompositionItemSchema,
   LocalAgentResourceDirectorySchema: () => LocalAgentResourceDirectorySchema,
   LlmJudgeConfigSchema: () => LlmJudgeConfigSchema,
+  LegacyFileIdInputSchema: () => LegacyFileIdInputSchema,
   LayoutElementTypeSchema: () => LayoutElementTypeSchema,
   LayoutElementSchema: () => LayoutElementSchema,
   LLM_JUDGE_PROMPT_MIN_LENGTH: () => LLM_JUDGE_PROMPT_MIN_LENGTH,
   LEGACY_RUN_EXPAND_MIGRATION: () => LEGACY_RUN_EXPAND_MIGRATION,
+  LEGACY_FILE_REF_COMPATIBILITY: () => LEGACY_FILE_REF_COMPATIBILITY,
   JudgeModeSchema: () => JudgeModeSchema,
   JsonSchemaSchema: () => JsonSchemaSchema,
+  InlineFileRefSchema: () => InlineFileRefSchema,
+  InlineFileIngressRefSchema: () => InlineFileIngressRefSchema,
+  InlineFileIngressPayloadSchema: () => InlineFileIngressPayloadSchema,
   IfStepSchema: () => IfStepSchema,
   INPUT_VALIDATION_CODES: () => INPUT_VALIDATION_CODES,
   INPUT_KINDS: () => INPUT_KINDS,
@@ -65926,7 +66301,10 @@ __export(exports_src, {
   GPFS_FILE_SOURCE_NAME: () => GPFS_FILE_SOURCE_NAME,
   GPFS_FILE_SOURCE_DESCRIPTOR: () => GPFS_FILE_SOURCE_DESCRIPTOR,
   ForeachStepSchema: () => ForeachStepSchema,
-  FilePathDescriptorSchema: () => FilePathDescriptorSchema,
+  FileReferenceSentinelSchema: () => FileReferenceSentinelSchema,
+  FilePathDescriptorSchema: () => FilePathDescriptorSchema2,
+  FileIngressRefSchema: () => FileIngressRefSchema,
+  FileIdIngressRefSchema: () => FileIdIngressRefSchema,
   FailStepSchema: () => FailStepSchema,
   ExtractedTableSchema: () => ExtractedTableSchema,
   ExtractOutputSchema: () => ExtractOutputSchema,
@@ -65983,6 +66361,7 @@ __export(exports_src, {
   DocumentParserInputSchema: () => DocumentParserInputSchema,
   DocumentParserConfigSchema: () => DocumentParserConfigSchema,
   DocumentMetadataSchema: () => DocumentMetadataSchema,
+  DbFileRefSchema: () => DbFileRefSchema,
   DatasetNameSchema: () => DatasetNameSchema,
   DatasetMetaSchema: () => DatasetMetaSchema,
   DatasetImportRequestSchema: () => DatasetImportRequestSchema,
@@ -66041,6 +66420,9 @@ __export(exports_src, {
 });
 var init_src = __esm(() => {
   init_core3();
+  init_legacy_boundary();
+  init_runtime_file_ref();
+  init_scoped_file_ref();
   init_processor();
   init_parser();
   init_otel();
@@ -187691,7 +188073,7 @@ import { fileURLToPath as fileURLToPath8 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.10.4",
+  version: "0.10.6",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -194388,6 +194770,7 @@ async function writeExecutionArtifacts(client, exampleDir, payload) {
 }
 
 // src/lib/payload.ts
+init_src();
 import { existsSync as existsSync14, readdirSync as readdirSync4, readFileSync as readFileSync13, statSync as statSync4 } from "fs";
 import { join as join8 } from "path";
 var DATASET_EXAMPLES_DIR = ["dataset", "examples"];
@@ -194423,16 +194806,17 @@ function readCanonicalInput(exampleDir, inputPath) {
   for (const [key2, value] of Object.entries(raw)) {
     const refs = topLevelFileRefs(value);
     if (refs.length === 0) {
-      scalars[key2] = value;
+      scalars[key2] = materializeNestedFileRefs(exampleDir, inputPath, value);
       continue;
     }
     for (const ref of refs) {
-      const relative3 = parseDatasetInputFileRef(ref);
-      if (!relative3) {
+      const validation2 = validateScopedArtifactPath(ref, { allowedRoots: ["input"] });
+      if (!validation2.ok) {
         throw new Error(`${inputPath}: ${key2} must reference files under input/ without path traversal.`);
       }
-      const filePath = join8(exampleDir, "input", relative3);
-      const filename = relative3.split("/").at(-1) ?? relative3;
+      const relative3 = validation2.value.segments.slice(1).join("/");
+      const filePath = join8(exampleDir, validation2.value.path);
+      const filename = validation2.value.segments.at(-1) ?? relative3;
       files.push({
         argument: key2,
         filename,
@@ -194443,29 +194827,55 @@ function readCanonicalInput(exampleDir, inputPath) {
   }
   return { scalars, files };
 }
+function materializeNestedFileRefs(exampleDir, inputPath, value) {
+  if (isScopedFileRef2(value)) {
+    const validation2 = validateScopedArtifactPath(value.$file, { allowedRoots: ["input"] });
+    if (!validation2.ok) {
+      throw new Error(`${inputPath}: $file refs must reference files under input/.`);
+    }
+    const filename = validation2.value.segments.at(-1) ?? "file";
+    const filePath = join8(exampleDir, validation2.value.path);
+    return {
+      $inline: {
+        filename,
+        mimeType: guessMimeType(filename) ?? "application/octet-stream",
+        base64: readFileSync13(filePath).toString("base64")
+      }
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => materializeNestedFileRefs(exampleDir, inputPath, item));
+  }
+  if (value && typeof value === "object") {
+    if (hasFileKey(value)) {
+      throw new Error('file refs must be exact { "$file": "input/..." } objects.');
+    }
+    const out = {};
+    for (const [key2, item] of Object.entries(value)) {
+      out[key2] = materializeNestedFileRefs(exampleDir, inputPath, item);
+    }
+    return out;
+  }
+  return value;
+}
 function topLevelFileRefs(value) {
-  if (isFileRef(value))
+  if (isScopedFileRef2(value))
     return [value.$file];
-  if (Array.isArray(value) && value.every(isFileRef))
+  if (hasFileKey(value)) {
+    throw new Error('file refs must be exact { "$file": "input/..." } objects.');
+  }
+  if (Array.isArray(value) && value.every(isScopedFileRef2))
     return value.map((item) => item.$file);
-  if (Array.isArray(value) && value.some(isFileRef)) {
-    throw new Error('file arrays must contain only { "$file": "input/..." } entries.');
+  if (Array.isArray(value) && value.some(hasFileKey)) {
+    throw new Error('file arrays must contain only exact { "$file": "input/..." } entries.');
   }
   return [];
 }
-function isFileRef(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.$file === "string";
+function isScopedFileRef2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 1 && typeof value.$file === "string";
 }
-function parseDatasetInputFileRef(path15) {
-  if (!path15.startsWith("input/"))
-    return null;
-  if (path15.startsWith("/") || path15.includes("\\") || path15.includes("\x00"))
-    return null;
-  const relative3 = path15.slice("input/".length);
-  const parts = relative3.split("/");
-  if (parts.some((part) => !part || part === "." || part === ".."))
-    return null;
-  return parts.join("/");
+function hasFileKey(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && "$file" in value;
 }
 function readOverrides(exampleDir) {
   const metaPath = join8(exampleDir, "meta.json");
@@ -196336,14 +196746,14 @@ function printIssues(label2, path15, issues) {
   console.error("");
   return false;
 }
-function isFileRef2(value) {
+function isFileRef(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.$file === "string";
 }
 function isExpectedErrorRef(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 1 && Object.prototype.hasOwnProperty.call(value, "$error");
 }
 function collectDatasetFileRefs(value, jsonPath = "<root>") {
-  if (isFileRef2(value))
+  if (isFileRef(value))
     return [{ path: value.$file, jsonPath }];
   if (Array.isArray(value)) {
     return value.flatMap((item, index) => collectDatasetFileRefs(item, `${jsonPath}.${index}`));
@@ -196387,29 +196797,50 @@ function parseDatasetFileRef(path15, root2) {
 function rootDir(opts) {
   return resolve6(opts.dir ?? process.cwd());
 }
+async function onlineInvokeIssues(yamlText, opts) {
+  const config2 = resolveConfig(opts);
+  requireApiKey(config2);
+  const client = new ApiClient(config2);
+  const res = await client.post("/api/workflows/validate", { yaml: yamlText });
+  return res.issues ?? [];
+}
 function registerAllValidateCommand(parent) {
-  parent.command("validate [path]").description("Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`.").option("--dir <path>", "Project root (defaults to cwd; resolves the three default paths from here)").action((path15, opts) => {
+  const cmd = parent.command("validate [path]").description("Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`.").option("--dir <path>", "Project root (defaults to cwd; resolves the three default paths from here)").option("--online", "Also validate cross-workflow action.invoke-workflow references against the server (needs auth). Catches target-not-found, input type mismatches, missing/unknown input keys, undeclared output, and invoke cycles that local validation cannot see.").addHelpText("after", `
+Note
+` + `  Local validation cannot resolve action.invoke-workflow targets (they live
+` + `  in the server DB), so invoke reference/type/cycle errors only surface at
+` + "  push — or run `validate --online` to check them before pushing.\n");
+  withBaseUrl(cmd).action(action(async (path15, opts) => {
     if (path15) {
       const target = resolve6(path15);
       const wfResult2 = validateWorkflowYaml(target);
       const wfOk2 = printIssues("workflow.yaml", target, wfResult2.issues);
       if (wfOk2)
         printSchemaQualityWarnings(target, wfResult2.warnings);
-      if (!wfOk2)
+      let onlineOk2 = true;
+      if (wfOk2 && opts.online) {
+        onlineOk2 = printIssues("invoke refs (server)", target, await onlineInvokeIssues(readFileSync15(target, "utf-8"), opts));
+      }
+      if (!wfOk2 || !onlineOk2)
         process.exit(1);
       return;
     }
     const root2 = rootDir(opts);
-    const wfResult = validateWorkflowYaml(join13(root2, "workflow.yaml"));
-    const wfPath = relPath(root2, join13(root2, "workflow.yaml"));
+    const wfFile = join13(root2, "workflow.yaml");
+    const wfResult = validateWorkflowYaml(wfFile);
+    const wfPath = relPath(root2, wfFile);
     const wfOk = printIssues("workflow.yaml", wfPath, wfResult.issues);
     if (wfOk)
       printSchemaQualityWarnings(wfPath, wfResult.warnings);
     const evOk = printIssues("evaluators.yaml", relPath(root2, join13(root2, "evaluators.yaml")), validateEvaluatorsYaml(join13(root2, "evaluators.yaml")));
     const dsOk = printIssues("dataset/", relPath(root2, join13(root2, "dataset")), validateDatasetFolder(join13(root2, "dataset")));
-    if (!wfOk || !evOk || !dsOk)
+    let onlineOk = true;
+    if (wfOk && opts.online && existsSync17(wfFile)) {
+      onlineOk = printIssues("invoke refs (server)", wfPath, await onlineInvokeIssues(readFileSync15(wfFile, "utf-8"), opts));
+    }
+    if (!wfOk || !evOk || !dsOk || !onlineOk)
       process.exit(1);
-  });
+  }));
 }
 function registerEvaluatorsValidateCommand(parent) {
   parent.command("validate [path]").description("Validate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml.").action((path15) => {
@@ -196588,6 +197019,23 @@ function registerWorkflowCoreCommands(parent) {
     }
     await writeOrPrint(opts.out, result.yamlContent);
   }));
+  const schemaCmd = parent.command("schema <workflow-id>").description("Show the inferred output schema for a workflow (what it returns).").option("--format <format>", "json | typescript | python", "json").option("--out <path>", "Write to file instead of stdout").addHelpText("after", `
+Examples
+` + `  eigenpal workflow schema income-assessment
+` + `  eigenpal workflow schema wf_123 --format typescript
+` + `  eigenpal workflow schema wf_123 --format python --out Output.py
+`);
+  withBaseUrl(schemaCmd).action(action(async (workflow2, opts) => {
+    const { client, workflowId } = await buildClientForWorkflow(workflow2, opts);
+    const format3 = opts.format ?? "json";
+    const result = await client.get(`/api/workflows/${workflowId}/output-schema`, { format: format3 });
+    if (format3 === "json") {
+      await writeOrPrint(opts.out, JSON.stringify(result, null, 2));
+    } else {
+      const text = result instanceof Response ? await result.text() : String(result);
+      await writeOrPrint(opts.out, text);
+    }
+  }));
   const pushCmd = parent.command("push").description(descriptionFor("workflow_set_definition")).option("--file <yaml>", "Path to YAML file").option("--workflow-id <id>", "Update existing workflow (default: create new)").option("--bump <level>", "Auto-bump from the server's current version: patch | minor | major. Mutually exclusive with `--version` and with a top-level `version:` in the YAML.").option("--set-version <semver>", "Push at this exact semver (e.g. 1.4.0). Mutually exclusive with `--bump` and with a top-level `version:` in the YAML. (Named `--set-version` to avoid the global `-v, --version` flag.)").addHelpText("after", `
 Examples:
   $ eigenpal workflow push --file workflow.yaml
@@ -196967,8 +197415,9 @@ Examples:
   $ cat expected.json | eigenpal workflow dataset example create wf_abc123 --name piped --input-json '{}' --expected-file -
 
 \`--input-json\` and \`--input-file\` (same for \`--expected-*\`) are mutually
-exclusive. File uploads still require a full \`dataset push\`; CRUD only
-handles JSON input + \`expected.json\`-style outputs.
+exclusive. To attach files without a dataset folder, pass ingress refs in JSON:
+\`{"document":{"$fileId":"file_..."}}\` or
+\`{"document":{"$inline":{"filename":"doc.pdf","mimeType":"application/pdf","base64":"..."}}}\`.
 `);
   addJsonFlag(withBaseUrl(createCmd)).action(action(async (workflow2, opts) => {
     const triggerInput = await readJsonInput(opts.inputJson, opts.inputFile, "input");

package/dist/skill/reference/cli/surface.md

@@ -15,6 +15,7 @@ eigenpal
 ├── workflow
 │   ├── list|ls
 │   ├── pull <workflow-id>
+│   ├── schema <workflow-id>
 │   ├── push
 │   ├── move <workflow-id>
 │   ├── evaluators

package/dist/skill/reference/cli/workflow.md

@@ -17,6 +17,7 @@ Manage workflows: push, pull, and evaluate.
 - [Details](#details)
   - [`eigenpal workflow list|ls [options]`](#eigenpal-workflow-listls-options)
   - [`eigenpal workflow pull [options] <workflow-id>`](#eigenpal-workflow-pull-options-workflow-id)
+  - [`eigenpal workflow schema [options] <workflow-id>`](#eigenpal-workflow-schema-options-workflow-id)
   - [`eigenpal workflow push [options]`](#eigenpal-workflow-push-options)
   - [`eigenpal workflow move [options] <workflow-id>`](#eigenpal-workflow-move-options-workflow-id)
   - [`eigenpal workflow validate [options] [path]`](#eigenpal-workflow-validate-options-path)
@@ -53,6 +54,7 @@ Manage workflows: push, pull, and evaluate.
 workflow
 ├── list|ls
 ├── pull <workflow-id>
+├── schema <workflow-id>
 ├── push
 ├── move <workflow-id>
 ├── evaluators
@@ -100,6 +102,7 @@ workflow
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `eigenpal workflow list\|ls [options]`                  | List workflows the caller can read.                                                                                                                                                                                                                                      |
 | `eigenpal workflow pull [options] <workflow-id>`        | Download the YAML definition of the workflow at its current version.                                                                                                                                                                                                     |
+| `eigenpal workflow schema [options] <workflow-id>`      | Show the inferred output schema for a workflow (what it returns).                                                                                                                                                                                                        |
 | `eigenpal workflow push [options]`                      | Create or update a workflow from a YAML file.                                                                                                                                                                                                                            |
 | `eigenpal workflow move [options] <workflow-id>`        | Move a workflow to a folder path, creating folders as needed                                                                                                                                                                                                             |
 | `eigenpal workflow validate [options] [path]`           | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`. |
@@ -198,6 +201,24 @@ Download the YAML definition of the workflow at its current version.
 | `--out <path>`     | no       |         | Write YAML to file instead of stdout |
 | `--base-url <url>` | no       |         | Server base URL                      |
 
+### `eigenpal workflow schema [options] <workflow-id>`
+
+Show the inferred output schema for a workflow (what it returns).
+
+### Arguments
+
+| Name          | Required | Variadic | Description |
+| ------------- | -------- | -------- | ----------- |
+| `workflow-id` | yes      | no       |             |
+
+### Options
+
+| Flag                | Required | Default  | Description                     |
+| ------------------- | -------- | -------- | ------------------------------- |
+| `--format <format>` | no       | `"json"` | json \| typescript \| python    |
+| `--out <path>`      | no       |          | Write to file instead of stdout |
+| `--base-url <url>`  | no       |          | Server base URL                 |
+
 ### `eigenpal workflow push [options]`
 
 Create or update a workflow from a YAML file.
@@ -243,9 +264,11 @@ Local-only validation. Without [path]: runs the templated three-way check (./wor
 
 ### Options
 
-| Flag           | Required | Default | Description                                                                |
-| -------------- | -------- | ------- | -------------------------------------------------------------------------- |
-| `--dir <path>` | no       |         | Project root (defaults to cwd; resolves the three default paths from here) |
+| Flag               | Required | Default | Description                                                                                                                                                                                                                                         |
+| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dir <path>`     | no       |         | Project root (defaults to cwd; resolves the three default paths from here)                                                                                                                                                                          |
+| `--online`         | no       |         | Also validate cross-workflow action.invoke-workflow references against the server (needs auth). Catches target-not-found, input type mismatches, missing/unknown input keys, undeclared output, and invoke cycles that local validation cannot see. |
+| `--base-url <url>` | no       |         | Server base URL                                                                                                                                                                                                                                     |
 
 ### `eigenpal workflow clear-local [options] [examples...]`
 

package/dist/skill/reference/step-types.md

@@ -574,7 +574,7 @@ Convert XLSX spreadsheet to JSON array of row objects for use in scripts or down
 
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| `input` | string | yes |  | File input - template expression e.g. {{input.document}} resolving to fileId or file path descriptor |
+| `input` | string | yes |  | File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime |
 | `sheet` | integer \| string | no |  | Sheet to read: 0-based index or sheet name. Omit for first sheet. |
 | `outputCsv` | boolean | no | `false` | If true, also write CSV to storage and include fileId in output |
 | `outputFilename` | string | no |  | Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv |
@@ -679,14 +679,14 @@ Execute another workflow and return its output
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
 | `workflowId` | string | yes |  | ID of workflow to invoke |
-| `input` | record<string, unknown> | no |  | Input to pass to workflow |
-| `wait` | boolean | no |  | If true, wait for the invoked workflow to complete (default: false) |
-| `timeout` | number | no |  | Max wait time in ms when wait=true (default: 300000) |
-| `pollInterval` | number | no |  | How often to poll status in ms when wait=true (default: 1000) |
+| `input` | record<string, unknown> | no |  | Input record keyed by the invoked workflow's declared inputs |
+| `wait` | boolean | no |  | Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget. |
+| `timeout` | number | no |  | Max wait time in ms when waiting (default: 300000) |
+| `pollInterval` | number | no |  | How often to poll status in ms when waiting (default: 1000) |
 
 **Output:** `record<string, unknown>`
 
-> Output from invoked workflow
+> When wait is true, the invoked workflow's declared output fields are flattened to the top level alongside a `files` array — reference them as {{ steps.<invoke>.output.<field> }} (there is no `.data` or `.result` wrapper). When wait is false, execution metadata. Call get_workflow_output_schema to see the exact resolved fields.
 
 #### `action.website-reader` — Website Reader
 

package/dist/skill/reference/workflow-yaml.md

@@ -79,10 +79,14 @@ The materialized shape on `triggerInput` is driven by the YAML, not by
 how many files the dataset uploaded. Get this wrong and the worker
 sees the opposite shape:
 
-| YAML                                       | `triggerInput.<name>` | Template                                |
-| ------------------------------------------ | --------------------- | --------------------------------------- |
-| `type: file`                               | `{ fileId }`          | `{{ input.<name> }}`                    |
-| `type: array`, `items: { type: file }`     | `[{ fileId }, ...]`   | `{{ input.<name>[0] }}` (or `forEach:`) |
+| YAML                                       | durable `triggerInput.<name>` | Template                                |
+| ------------------------------------------ | ------------------------------ | --------------------------------------- |
+| `type: file`                               | `{ "$file": "input/..." }`     | `{{ input.<name> }}`                    |
+| `type: array`, `items: { type: file }`     | `[{ "$file": "input/..." }]`   | `{{ input.<name>[0] }}` (or `forEach:`) |
+
+API/SDK ingress can use `{ "$fileId": "file_..." }`, inline bytes via
+`{ "$inline": { filename, mimeType, base64 } }`, or multipart file parts.
+Eigenpal snapshots those into run-scoped artifacts before execution.
 
 If you see `Invalid input ... expected object, received array` from a
 step that takes a single file, the workflow input is `type: file` but
@@ -474,7 +478,7 @@ _Generated from `WorkflowDefinitionSchema` in `@eigenpal/types/src/workflow/work
 | `triggerMethods` | array<object> | no | `[{"type":"manual"}]` |  |
 | `inputs` | array<object> | no |  |  |
 | `steps` | array<unknown> | yes |  |  |
-| `output` | record<string, string> | no |  |  |
+| `output` | record<string, string> \| string | no |  |  |
 | `settings` | object | no |  |  |
 | `defaultModel` | string | no |  |  |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   "keywords": [
     "eigenpal",