@meistrari/tela-cli 1.3.0 → 1.4.0

package/dist/docs/workflow-code/api-reference.md

@@ -15,6 +15,7 @@ import {
     canvas,
     code,
     crop,
+    docTemplate,
     input,
     llm,
     splitter,
@@ -35,7 +36,9 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
 | [`crop()`](#cropoptions) | Cropping selected PDF pages from compatible files or existing Vault files. |
 | [`vault.asset()`](#vaultassetpath-options) | Declaring a local file that `sync` uploads and locks in Vault. |
+| [`docTemplate()`](#doctemplateoptions) | Rendering a `.docx` Vault template with keyed placeholders. |
 | [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
+| [`vault.asset()`](#vaultassetpath-options) | Declaring a local file dependency uploaded and locked by `sync`. |
 | [`remote()`](#remote) | Generated catalog paths and explicit ID refs for inert remote authoring. |
 | [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
 | [`agent(remoteRef, options)`](#agentremoteref-options) | Published-Agent calls from the remote catalog. |
@@ -491,6 +494,29 @@ function crop(options: CropOptions): CropNodeHandle
 ```
 
 Declares Workflow V3's existing `document-cropper` action. Its exclusive `input.file` supports the same compatible workflow input, prior-node output, `vault.ref()`, `vault.asset()`, and Vault-array forms as `splitter.input.file`.
+### `docTemplate(options)`
+
+```ts
+type DocTemplateOptions = {
+    name: string
+    key?: string
+    input: {
+        template: WorkflowCodeVaultSource
+            | ((context: ExclusiveRefFactoryContext) => WorkflowCodeExclusiveRef<string>)
+        placeholders?: Record<string, string | WorkflowCodeVaultSource>
+            | ((context: PromptFactoryContext) => Record<string, string | WorkflowCodeVaultSource | PromptRefValue>)
+        outputFilename: string
+        mustache?: boolean
+        createPermalink?: boolean
+        templateFilename?: string
+        templateFileSize?: number
+    }
+}
+
+function docTemplate(options: DocTemplateOptions): DocTemplateNodeHandle
+```
+
+Declares the Workflow V3 `document-templater` action. `input.template` may be a `.docx` file declared with `vault.ref()` or `vault.asset()`, or a callback reference to a text workflow input/string-compatible field from an earlier node. Placeholders are authored as a keyed object; literal strings remain literal, and compatible workflow/Vault references lower to the reference strings consumed by the runtime action.
 
 | Option | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
@@ -549,6 +575,44 @@ const selectedPages = crop({
 ```
 
 `path`, `name`, and `mimeType` must be non-empty strings when present. Offline compile without a matching explicit asset snapshot reports `vault.asset.missing_lock`; it never falls back to reading the local file. If the file changes, the next `sync` uploads the new content and updates the lock.
+| `input.template` | `WorkflowCodeVaultSource` | Yes | — | Existing `vault.ref()` or local `vault.asset()` `.docx` template. |
+| `input.template` | `WorkflowCodeVaultSource` or callback | Yes | — | Existing `vault.ref()`, local `vault.asset()`, text input ref, or string-compatible earlier-node ref containing the template Vault URL. |
+| `input.placeholders` | Record or callback | No | `{}` | Literal strings, Vault sources, text inputs, or string-compatible earlier-node fields keyed by template placeholder. |
+| `input.outputFilename` | `string` | Yes | — | Filename for the generated document. |
+| `input.mustache` | `boolean` | No | `false` | Enables the runtime action's Mustache mode. |
+| `input.createPermalink` | `boolean` | No | `false` | Requests a permalink for the rendered document. |
+| `input.templateFilename` | `string` | No | Known Vault name | Explicit `.docx` template name, validated against known metadata. |
+| `input.templateFileSize` | `number` | No | Known Vault size | Explicit byte size, validated against known metadata. |
+
+```ts
+const template = vault.asset('./templates/invoice.docx', {
+    name: 'invoice.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+})
+
+const renderInvoice = docTemplate({
+    name: 'Render invoice',
+    input: {
+        template,
+        outputFilename: 'rendered-invoice.docx',
+        placeholders: ({ ref, paths }) => ({
+            customer: ref(customerName),
+            total: ref(extractInvoice, paths(extractInvoice).total),
+            footer: 'Generated by Tela',
+        }),
+    },
+})
+
+const renderSelectedTemplate = docTemplate({
+    name: 'Render selected template',
+    input: {
+        template: ({ ref, paths }) => ref(selectTemplate, paths(selectTemplate).vaultUrl),
+        outputFilename: 'selected-template.docx',
+    },
+})
+```
+
+The returned handle exposes typed `generatedDocument`, `generatedAt`, and optional permalink fields. Before workflow mutation, `sync` uploads changed local assets, reuses matching locks, validates access to every directly used Vault ref, checks known filename/size metadata, and rejects known non-`.docx` templates. Dynamic template refs are validated for scope and string compatibility, but their runtime Vault value cannot be inspected during sync. File inputs and non-string node fields are incompatible template or placeholder references.
 
 ### `vault.ref(reference)`
 
@@ -575,6 +639,26 @@ const existingPages = splitter({
 
 During compile, a direct Vault ref used by `splitter.input.file` or `crop.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
 
+### `vault.asset(path, options)`
+
+```ts
+const vault: {
+    asset: (
+        path: string,
+        options?: { name?: string, mimeType?: string },
+    ) => WorkflowCodeVaultAsset
+}
+```
+
+Creates an inert local file declaration. Source evaluation does not read, hash, or upload the path. `sync` resolves it inside the Workflow Code project, uploads new or changed content, and persists the returned `vault://...` ref with its content hash and known metadata in the target lockfile. An unchanged asset reuses that lock.
+
+```ts
+const template = vault.asset('./templates/invoice.docx', {
+    name: 'invoice.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+})
+```
+
 ### `agent(remoteRef, options)`
 
 ```ts

package/dist/docs/workflow-code/manifest.json

@@ -14,7 +14,7 @@
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "fc121fd8c0e83e4f39ecef45b50d4fc9b0bc64888bd10d0590b3ca168af0a42d"
+      "sha256": "380cf0c8543400f6fd311936f1b4fb984f12d27b0472213b8a2b431405f0755e"
     },
     {
       "slug": "cli",

package/dist/index.js

@@ -368782,7 +368782,7 @@ var require_output_schema = __commonJS({
   "../../packages/workflow-code/dist/compiler/output-schema.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.CROP_OUTPUT_JSON_SCHEMA = exports2.SPLITTER_OUTPUT_JSON_SCHEMA = exports2.FILE_INPUT_JSON_SCHEMA = exports2.FILE_OUTPUT_JSON_SCHEMA = void 0;
+    exports2.DOC_TEMPLATE_OUTPUT_JSON_SCHEMA = exports2.CROP_OUTPUT_JSON_SCHEMA = exports2.SPLITTER_OUTPUT_JSON_SCHEMA = exports2.FILE_INPUT_JSON_SCHEMA = exports2.FILE_OUTPUT_JSON_SCHEMA = void 0;
     exports2.createPromptOutputJsonSchema = createPromptOutputJsonSchema;
     exports2.selectOutputJsonSchema = selectOutputJsonSchema;
     exports2.isFileCompatibleOutputJsonSchema = isFileCompatibleOutputJsonSchema;
@@ -368834,6 +368834,17 @@ var require_output_schema = __commonJS({
         required: Object.freeze(["indexes", "originalFile", "file"])
       })
     });
+    exports2.DOC_TEMPLATE_OUTPUT_JSON_SCHEMA = Object.freeze({
+      type: "object",
+      properties: Object.freeze({
+        generatedDocument: exports2.FILE_OUTPUT_JSON_SCHEMA,
+        generatedAt: Object.freeze({ type: "string" }),
+        permalinkUrl: Object.freeze({ type: "string" }),
+        permalinkId: Object.freeze({ type: "string" }),
+        permalinkExpiresAt: Object.freeze({ anyOf: Object.freeze([{ type: "string" }, { type: "null" }]) })
+      }),
+      required: Object.freeze(["generatedDocument", "generatedAt"])
+    });
     function createPromptOutputJsonSchema(schema) {
       return schema === void 0 || schema === null ? void 0 : { type: "object", properties: schema };
     }
@@ -369376,7 +369387,8 @@ var require_extract3 = __commonJS({
         required: declaration.required
       }));
       const nodeBindings = input.builtNodes.slice(0, input.currentNodeIndex).flatMap((node) => {
-        const schema = input.nodeOutputSchemasById.get(input.nodeIdsByKey.get(node.key ?? node.name) ?? "");
+        const nodeId = input.nodeIdsByKey.get(node.key ?? node.name);
+        const schema = nodeId === void 0 ? void 0 : input.nodeOutputSchemasById.get(nodeId);
         return schema ? [{ name: node.name, schema, required: true }] : [];
       });
       return [...inputBindings, ...nodeBindings];
@@ -370531,6 +370543,7 @@ var require_refs = __commonJS({
     exports2.resolveReferenceRecordRefs = resolveReferenceRecordRefs;
     exports2.resolveWorkflowRef = resolveWorkflowRef;
     exports2.resolveExclusiveRef = resolveExclusiveRef;
+    exports2.resolveVisibleNodeIdentity = resolveVisibleNodeIdentity;
     var workflow_shared_1 = require_cjs2();
     function resolvePromptRefs(context) {
       const diagnostics = [];
@@ -370621,7 +370634,7 @@ var require_refs = __commonJS({
       const candidates = context.nodeIdentitiesByKey.get(ref.targetKey) ?? [];
       if (candidates.length === 0)
         return void 0;
-      const visible = findVisibleCandidate(ref.targetKey, context);
+      const visible = resolveVisibleNodeIdentity(ref.targetKey, context);
       if (visible) {
         const reference = workflow_shared_1.ActionOutputReferenceURI.fromStepId(visible.id);
         return { reference: formatPromptReference(reference, ref), nodeId: visible.id };
@@ -370631,7 +370644,7 @@ var require_refs = __commonJS({
       }
       return "scope";
     }
-    function findVisibleCandidate(key, context) {
+    function resolveVisibleNodeIdentity(key, context) {
       const currentScopeCandidate = resolvePriorCandidateInScope(key, context.currentNode.scopePath, context.currentNode.sequenceIndex, context);
       if (currentScopeCandidate)
         return currentScopeCandidate;
@@ -370962,9 +370975,9 @@ var require_modules = __commonJS({
           currentNodeIndex: context.nodeIndex,
           inputNamesByKey: context.inputNamesByKey,
           nodeNamesByKey: context.nodeNamesByKey,
+          nodeIdsByKey: context.nodeIdsByKey,
           nodeIndexesByKey: context.nodeIndexesByKey,
-          nodeOutputSchemasById: context.nodeOutputSchemasById,
-          nodeIdsByKey: context.nodeIdsByKey
+          nodeOutputSchemasById: context.nodeOutputSchemasById
         });
         context.diagnostics.push(...extracted.diagnostics);
         if (extracted.diagnostics.some((item) => item.severity === "error"))
@@ -371106,6 +371119,255 @@ var require_modules = __commonJS({
         diagnostics.push(invalidDocumentInputDiagnostic(node, "crop", "type must be pdf"));
       return diagnostics;
     }
+    var DOCX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    var docTemplateModule = {
+      kind: "doc-template",
+      actionId: workflow_shared_1.WORKFLOW_ACTION_IDS.documentTemplater,
+      createFailedInput() {
+        return {
+          vaultUrl: "vault://00000000-0000-4000-8000-000000000000",
+          placeholders: [],
+          outputFilename: "compilation-failed.docx",
+          mustache: false,
+          createPermalink: false
+        };
+      },
+      validate(node) {
+        return validateDocTemplateInput(node);
+      },
+      lower(node, context) {
+        if (validateDocTemplateInput(node).length > 0)
+          return void 0;
+        const template = lowerDocTemplateSource(node.input.template, context);
+        const placeholders = lowerDocTemplatePlaceholders(node, context);
+        context.diagnostics.push(...template.diagnostics, ...placeholders.diagnostics);
+        if (!template.reference)
+          return void 0;
+        const templateFilename = node.input.templateFilename ?? template.lock?.name;
+        const templateFileSize = node.input.templateFileSize ?? template.lock?.size;
+        context.diagnostics.push(...validateKnownTemplateMetadata(node, template.lock));
+        const linearPorts = defaultLinearPorts(context.nodeId);
+        return {
+          node: {
+            id: context.nodeId,
+            name: node.name,
+            actionId: workflow_shared_1.WORKFLOW_ACTION_IDS.documentTemplater,
+            ports: [
+              { id: linearPorts.input, dir: "in", type: "default" },
+              { id: linearPorts.output, dir: "out", type: "default" }
+            ],
+            input: {
+              vaultUrl: template.reference,
+              placeholders: Object.entries(placeholders.values).map(([key, reference]) => ({ key, reference })),
+              outputFilename: node.input.outputFilename,
+              mustache: node.input.mustache ?? false,
+              createPermalink: node.input.createPermalink ?? false,
+              ...templateFilename === void 0 ? {} : { templateFilename },
+              ...templateFileSize === void 0 ? {} : { templateFileSize }
+            }
+          },
+          linearPorts,
+          outputSchema: output_schema_1.DOC_TEMPLATE_OUTPUT_JSON_SCHEMA,
+          vaultRefs: [...template.vaultRefs, ...placeholders.vaultRefs],
+          ...(0, reference_1.isWorkflowCodeVaultReference)(template.reference) ? { vaultRequirements: [{
+            reference: template.reference,
+            ...templateFilename === void 0 ? {} : { expectedName: templateFilename },
+            ...templateFileSize === void 0 ? {} : { expectedSize: templateFileSize },
+            requiredExtension: ".docx",
+            requiredMimeType: DOCX_MIME_TYPE
+          }] } : {}
+        };
+      }
+    };
+    function validateDocTemplateInput(node) {
+      if (!node.input || typeof node.input !== "object")
+        return [invalidDocTemplateInputDiagnostic(node, "input must be an object")];
+      const diagnostics = [];
+      if (!isVaultSource(node.input.template) && !isExclusiveWorkflowRef(node.input.template))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "template must be vault.ref(), vault.asset(), or a workflow reference callback"));
+      if (typeof node.input.outputFilename !== "string" || node.input.outputFilename.trim().length === 0)
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "outputFilename must be a non-empty string"));
+      if (!isRecord3(node.input.placeholders))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "placeholders must be an object"));
+      else if (Object.entries(node.input.placeholders).some(([key, value]) => key.trim().length === 0 || !isReferencePlaceholder(value) && !isVaultSource(value)))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "placeholder keys must be non-empty and values must be string literals or compatible refs"));
+      if (node.input.mustache !== void 0 && typeof node.input.mustache !== "boolean")
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "mustache must be a boolean"));
+      if (node.input.createPermalink !== void 0 && typeof node.input.createPermalink !== "boolean")
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "createPermalink must be a boolean"));
+      if (node.input.templateFilename !== void 0 && (typeof node.input.templateFilename !== "string" || !hasDocxExtension(node.input.templateFilename)))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "templateFilename must name a .docx file"));
+      if (node.input.templateFileSize !== void 0 && (typeof node.input.templateFileSize !== "number" || !Number.isFinite(node.input.templateFileSize) || node.input.templateFileSize < 0))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, "templateFileSize must be a non-negative finite number"));
+      if (isVaultAsset(node.input.template)) {
+        const assetName = node.input.template.name ?? node.input.template.path;
+        if (!hasDocxExtension(assetName))
+          diagnostics.push(invalidDocTemplateInputDiagnostic(node, "vault.asset() template must name a .docx file"));
+        if (node.input.template.mimeType !== void 0 && node.input.template.mimeType !== DOCX_MIME_TYPE)
+          diagnostics.push(invalidDocTemplateInputDiagnostic(node, `vault.asset() template MIME type must be ${DOCX_MIME_TYPE}`));
+      }
+      return diagnostics;
+    }
+    function invalidDocTemplateInputDiagnostic(node, detail) {
+      return {
+        code: "compiler.module.invalid_input",
+        severity: "error",
+        message: `Node ${node.name || "<unnamed>"} has invalid docTemplate input: ${detail}`
+      };
+    }
+    function lowerDocTemplateSource(source, context) {
+      if (isExclusiveWorkflowRef(source)) {
+        const compatibility = validateDocTemplateSourceTarget(source, context);
+        if (compatibility.length > 0)
+          return { vaultRefs: [], diagnostics: compatibility };
+        const resolved = (0, refs_1.resolveExclusiveRef)(source, {
+          inputIdsByKey: context.inputIdsByKey,
+          nodeIdentitiesByKey: context.nodeIdentitiesByKey,
+          nodesByPath: context.nodesByPath,
+          currentNode: context.currentNode
+        });
+        return { reference: resolved.reference, vaultRefs: [], diagnostics: resolved.diagnostics };
+      }
+      if (isVaultRef(source)) {
+        if (!(0, reference_1.isWorkflowCodeVaultReference)(source.reference))
+          return { vaultRefs: [], diagnostics: [invalidVaultRefDiagnostic(source.reference)] };
+        return { reference: source.reference, vaultRefs: [source.reference], diagnostics: [] };
+      }
+      if (!isVaultAsset(source))
+        return { vaultRefs: [], diagnostics: [] };
+      const lock = context.vaultAssetsByKey.get((0, asset_1.workflowCodeVaultAssetKey)(context.workflowKey, source));
+      if (!lock || !(0, reference_1.isWorkflowCodeVaultReference)(lock.ref)) {
+        return {
+          vaultRefs: [],
+          diagnostics: [{
+            code: "vault.asset.missing_lock",
+            severity: "error",
+            message: `Vault asset ${source.path} has no uploaded lock for this workflow`,
+            hint: "Run tela workflow sync so the CLI can upload and lock the local asset before compilation."
+          }]
+        };
+      }
+      return {
+        reference: lock.ref,
+        lock,
+        vaultRefs: [lock.ref],
+        diagnostics: []
+      };
+    }
+    function validateDocTemplateSourceTarget(source, context) {
+      if (source.targetKind === "input") {
+        const target2 = context.builtInputs.find((input) => (input.key ?? input.name) === source.targetKey);
+        if (!target2 || target2.inputType === "text")
+          return [];
+        return [incompatibleDocTemplateSourceDiagnostic(source.targetKey)];
+      }
+      const target = resolveVisibleNodeOutput(source.targetKey, context);
+      if (!target)
+        return [];
+      const directStringLlm = target.declaration?.nodeKind === "llm" && target.declaration.schema == null && (source.path?.length ?? 0) === 0;
+      const selectedSchema = (0, output_schema_1.selectOutputJsonSchema)(target.schema, source.path ?? []);
+      return directStringLlm || (0, output_schema_1.isStringCompatibleOutputJsonSchema)(selectedSchema) ? [] : [incompatibleDocTemplateSourceDiagnostic(source.targetKey)];
+    }
+    function incompatibleDocTemplateSourceDiagnostic(targetKey) {
+      return {
+        code: "compiler.ref.incompatible",
+        severity: "error",
+        message: `Template reference ${targetKey} does not select a string-compatible value for docTemplate.input.template`
+      };
+    }
+    function lowerDocTemplatePlaceholders(node, context) {
+      const diagnostics = validateDocTemplatePlaceholderCompatibility(node, context);
+      const resolved = (0, refs_1.resolveReferenceRecordRefs)({
+        values: node.input.placeholders,
+        refs: node.placeholderRefs ?? [],
+        inputIdsByKey: context.inputIdsByKey,
+        inputTypesByKey: context.inputTypesByKey,
+        nodeIdentitiesByKey: context.nodeIdentitiesByKey,
+        nodesByPath: context.nodesByPath,
+        currentNode: context.currentNode
+      });
+      diagnostics.push(...resolved.diagnostics);
+      const values = {};
+      const vaultRefs = [];
+      for (const [key, value] of Object.entries(resolved.values)) {
+        if (typeof value === "string") {
+          values[key] = value;
+          continue;
+        }
+        if (isVaultRef(value)) {
+          if ((0, reference_1.isWorkflowCodeVaultReference)(value.reference)) {
+            values[key] = value.reference;
+            vaultRefs.push(value.reference);
+          } else {
+            diagnostics.push(invalidVaultRefDiagnostic(value.reference));
+          }
+          continue;
+        }
+        if (isVaultAsset(value)) {
+          const lock = context.vaultAssetsByKey.get((0, asset_1.workflowCodeVaultAssetKey)(context.workflowKey, value));
+          if (!lock || !(0, reference_1.isWorkflowCodeVaultReference)(lock.ref)) {
+            diagnostics.push({
+              code: "vault.asset.missing_lock",
+              severity: "error",
+              message: `Vault asset ${value.path} has no uploaded lock for this workflow`,
+              hint: "Run tela workflow sync so the CLI can upload and lock the local asset before compilation."
+            });
+          } else {
+            values[key] = lock.ref;
+            vaultRefs.push(lock.ref);
+          }
+        }
+      }
+      return { values: Object.freeze(values), vaultRefs, diagnostics };
+    }
+    function validateDocTemplatePlaceholderCompatibility(node, context) {
+      const diagnostics = [];
+      for (const ref of node.placeholderRefs ?? []) {
+        if (ref.targetKind === "input") {
+          if (context.inputTypesByKey.get(ref.targetKey) === "file")
+            diagnostics.push(incompatibleDocTemplatePlaceholderDiagnostic(ref.key, ref.targetKey));
+          continue;
+        }
+        const target = resolveVisibleNodeOutput(ref.targetKey, context);
+        if (!target)
+          continue;
+        const directStringLlm = target.declaration?.nodeKind === "llm" && target.declaration.schema == null && (ref.path?.length ?? 0) === 0;
+        const selected = (0, output_schema_1.selectOutputJsonSchema)(target.schema, ref.path ?? []);
+        if (!directStringLlm && !(0, output_schema_1.isStringCompatibleOutputJsonSchema)(selected))
+          diagnostics.push(incompatibleDocTemplatePlaceholderDiagnostic(ref.key, ref.targetKey));
+      }
+      return diagnostics;
+    }
+    function incompatibleDocTemplatePlaceholderDiagnostic(key, targetKey) {
+      return {
+        code: "compiler.ref.incompatible",
+        severity: "error",
+        message: `Placeholder ${key} reference ${targetKey} does not select a string-compatible value`
+      };
+    }
+    function validateKnownTemplateMetadata(node, lock) {
+      if (!lock)
+        return [];
+      const diagnostics = [];
+      if (node.input.templateFilename !== void 0 && lock.name !== void 0 && node.input.templateFilename !== lock.name)
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, `templateFilename ${node.input.templateFilename} does not match locked asset name ${lock.name}`));
+      if (node.input.templateFileSize !== void 0 && lock.size !== void 0 && node.input.templateFileSize !== lock.size)
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, `templateFileSize ${node.input.templateFileSize} does not match locked asset size ${lock.size}`));
+      if (lock.name !== void 0 && !hasDocxExtension(lock.name))
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, `locked asset name ${lock.name} is not a .docx file`));
+      if (lock.mimeType !== void 0 && lock.mimeType !== DOCX_MIME_TYPE)
+        diagnostics.push(invalidDocTemplateInputDiagnostic(node, `locked asset MIME type ${lock.mimeType} is not ${DOCX_MIME_TYPE}`));
+      return diagnostics;
+    }
+    function hasDocxExtension(value) {
+      return value.toLowerCase().endsWith(".docx");
+    }
+    function isReferencePlaceholder(value) {
+      return typeof value === "string";
+    }
+    function isVaultSource(value) {
+      return isVaultRef(value) || isVaultAsset(value);
+    }
     function validateSplitterInput(node) {
       if (!node.input || typeof node.input !== "object")
         return [invalidSplitterInputDiagnostic(node, "input must be an object")];
@@ -371220,19 +371482,34 @@ var require_modules = __commonJS({
     }
     function validateExclusiveFileTarget(file2, context, targetField) {
       if (file2.targetKind === "input") {
-        const target = context.builtInputs.find((input) => (input.key ?? input.name) === file2.targetKey);
-        if (!target || target.inputType === "file")
+        const target2 = context.builtInputs.find((input) => (input.key ?? input.name) === file2.targetKey);
+        if (!target2 || target2.inputType === "file")
           return [];
         return [incompatibleDocumentRefDiagnostic(file2.targetKey, targetField)];
       }
-      const resolved = (0, refs_1.resolveWorkflowRef)(file2, context);
-      if (resolved.nodeId === void 0)
+      const target = resolveVisibleNodeOutput(file2.targetKey, context);
+      if (!target)
         return [];
-      const selectedSchema = (0, output_schema_1.selectOutputJsonSchema)(context.nodeOutputSchemasById.get(resolved.nodeId), file2.path ?? []);
-      if (selectedSchema === void 0 && context.remoteMode.kind === "symbolic" && context.remoteTemplateNodeIds.has(resolved.nodeId))
+      const selectedSchema = (0, output_schema_1.selectOutputJsonSchema)(target.schema, file2.path ?? []);
+      if (selectedSchema === void 0 && context.remoteMode.kind === "symbolic" && context.remoteTemplateNodeIds.has(target.id))
         return [];
       return (0, output_schema_1.isFileCompatibleOutputJsonSchema)(selectedSchema) ? [] : [incompatibleDocumentRefDiagnostic(file2.targetKey, targetField)];
     }
+    function resolveVisibleNodeOutput(targetKey, context) {
+      const identity2 = (0, refs_1.resolveVisibleNodeIdentity)(targetKey, {
+        inputIdsByKey: context.inputIdsByKey,
+        nodeIdentitiesByKey: context.nodeIdentitiesByKey,
+        nodesByPath: context.nodesByPath,
+        currentNode: context.currentNode
+      });
+      if (!identity2)
+        return void 0;
+      return {
+        id: identity2.id,
+        declaration: context.nodeDeclarationsById.get(identity2.id),
+        schema: context.nodeOutputSchemasById.get(identity2.id)
+      };
+    }
     function incompatibleDocumentRefDiagnostic(targetKey, targetField) {
       return {
         code: "compiler.ref.incompatible",
@@ -371455,7 +371732,8 @@ var require_modules = __commonJS({
       [codeModule.kind, codeModule],
       [mapModule.kind, mapModule],
       [splitterModule.kind, splitterModule],
-      [cropModule.kind, cropModule]
+      [cropModule.kind, cropModule],
+      [docTemplateModule.kind, docTemplateModule]
     ]);
   }
 });
@@ -371649,10 +371927,31 @@ var require_transpile = __commonJS({
         return createFailedSplitterNode(workflowKey, declaration);
       if (declaration.node.nodeKind === "crop")
         return createFailedCropNode(workflowKey, declaration);
+      if (declaration.node.nodeKind === "doc-template")
+        return createFailedDocTemplateNode(workflowKey, declaration);
       if (declaration.node.nodeKind === "remote-executable" || declaration.node.nodeKind === "remote-agent" || declaration.node.nodeKind === "remote-template")
         return createFailedRemoteNode(workflowKey, declaration);
       return createFailedPromptNode(workflowKey, declaration);
     }
+    function createFailedDocTemplateNode(workflowKey, declaration) {
+      const nodeId = (0, ids_1.stableNodeId)(workflowKey, declaration.node, declaration.path);
+      const linearPorts = failedNodePorts(nodeId);
+      const module3 = modules_1.nodeModuleRegistry.get(declaration.node.nodeKind);
+      return {
+        declarationIndex: declaration.ordinal,
+        path: declaration.path,
+        scopePath: declaration.scopePath,
+        sequenceIndex: declaration.sequenceIndex,
+        linearPorts,
+        node: {
+          id: nodeId,
+          name: declaration.node.name,
+          actionId: module3?.actionId ?? workflow_shared_1.WORKFLOW_ACTION_IDS.documentTemplater,
+          ports: workflowNodePorts(linearPorts),
+          input: module3?.createFailedInput(declaration.node) ?? {}
+        }
+      };
+    }
     function createFailedRemoteNode(workflowKey, declaration) {
       const nodeId = (0, ids_1.stableNodeId)(workflowKey, declaration.node, declaration.path);
       const linearPorts = failedNodePorts(nodeId);
@@ -371916,9 +372215,9 @@ var require_transpile = __commonJS({
         nodeIndexesByKey.set(key, ordinal);
       });
       const { nodesByPath, nodeIdentitiesByKey } = createScopedIdentities(workflowKey, flattenedNodes);
+      const nodeDeclarationsById = new Map(flattenedNodes.map(({ node, path: path3 }) => [(0, ids_1.stableNodeId)(workflowKey, node, path3), node]));
       const inputNamesByKey = new Map(declarationInputs.map((declaration) => [declaration.key ?? declaration.name, declaration.name]));
       const nodeNamesByKey = new Map(topLevelNodes.map(({ node }) => [node.key ?? node.name, node.name]));
-      const nodeOutputSchemasByKey = /* @__PURE__ */ new Map();
       const nodeOutputSchemasById = /* @__PURE__ */ new Map();
       const remoteTemplateNodeIds = new Set(flattenedNodes.filter(({ node }) => node.nodeKind === "remote-template").map(({ node, path: path3 }) => (0, ids_1.stableNodeId)(workflowKey, node, path3)));
       const buildBinding = input.declaration[contracts_1.BUILD_BINDING];
@@ -371955,9 +372254,9 @@ var require_transpile = __commonJS({
           },
           nodeIdsByKey,
           nodeIndexesByKey,
+          nodeDeclarationsById,
           inputNamesByKey,
           nodeNamesByKey,
-          nodeOutputSchemasByKey,
           nodeOutputSchemasById,
           remoteTemplateNodeIds,
           builtInputs: declarationInputs,
@@ -371970,10 +372269,8 @@ var require_transpile = __commonJS({
           remoteRefs,
           diagnostics
         });
-        if (lowered?.outputSchema !== void 0) {
-          nodeOutputSchemasByKey.set(node.key ?? node.name, lowered.outputSchema);
+        if (lowered?.outputSchema !== void 0)
           nodeOutputSchemasById.set((0, ids_1.stableNodeId)(workflowKey, node, flattened.path), lowered.outputSchema);
-        }
         return lowered ? {
           ...lowered,
           declarationIndex: index,
@@ -371985,6 +372282,7 @@ var require_transpile = __commonJS({
       const loweredModuleNodes = loweredModuleNodesByDeclaration.filter(isLoweredModuleNodeWithIndex);
       const vaultRefs = [...new Set(loweredModuleNodes.flatMap((item) => item.vaultRefs ?? []))].sort((left, right) => left.localeCompare(right));
       const vaultAssets = collectVaultAssetUses(flattenedNodes, workflowKey);
+      const vaultRequirements = [...new Map(loweredModuleNodes.flatMap((item) => item.vaultRequirements ?? []).map((item) => [JSON.stringify(item), item])).values()].sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
       const loweredByPath = createLoweredByPath(loweredModuleNodes);
       const nodes = loweredModuleNodes.map((item) => item.node);
       const edges = createTopologyEdges(rootRecords, loweredByPath);
@@ -372027,7 +372325,8 @@ var require_transpile = __commonJS({
         },
         resources: Object.freeze({
           vaultRefs: Object.freeze(vaultRefs),
-          ...vaultAssets.length === 0 ? {} : { vaultAssets: Object.freeze(vaultAssets) }
+          ...vaultAssets.length === 0 ? {} : { vaultAssets: Object.freeze(vaultAssets) },
+          ...vaultRequirements.length === 0 ? {} : { vaultRequirements: Object.freeze(vaultRequirements) }
         }),
         diagnostics
       });
@@ -372035,9 +372334,7 @@ var require_transpile = __commonJS({
     function collectVaultAssetUses(records, workflowKey) {
       const byKey = /* @__PURE__ */ new Map();
       for (const { node } of records) {
-        if (node.nodeKind !== "splitter" && node.nodeKind !== "crop")
-          continue;
-        const values = Array.isArray(node.input.file) ? node.input.file : [node.input.file];
+        const values = node.nodeKind === "doc-template" ? [node.input.template, ...Object.values(node.input.placeholders)] : node.nodeKind === "splitter" || node.nodeKind === "crop" ? Array.isArray(node.input.file) ? node.input.file : [node.input.file] : [];
         for (const value of values) {
           if (!isVaultAsset(value))
             continue;
@@ -372812,6 +373109,7 @@ var require_evaluate_source = __commonJS({
               collectWorkflowCodeAliasBindings(node, node.statements, "agent", scopedBindings.promptNodeBindings, scopedBindings.promptNodeNamespaceBindings, scopedBindings.promptNodeNamespaceMemberBindings);
               collectWorkflowCodeAliasBindings(node, node.statements, "llm", scopedBindings.promptNodeBindings, scopedBindings.promptNodeNamespaceBindings, scopedBindings.promptNodeNamespaceMemberBindings);
               collectWorkflowCodeAliasBindings(node, node.statements, "map", scopedBindings.promptNodeBindings, scopedBindings.promptNodeNamespaceBindings, scopedBindings.promptNodeNamespaceMemberBindings);
+              collectWorkflowCodeAliasBindings(node, node.statements, "docTemplate", scopedBindings.promptNodeBindings, scopedBindings.promptNodeNamespaceBindings, scopedBindings.promptNodeNamespaceMemberBindings);
               return typescript_1.default.visitEachChild(node, createVisit(scopedBindings), context);
             }
             if (isForLikeStatement(node)) {
@@ -372980,7 +373278,7 @@ var require_evaluate_source = __commonJS({
       return Boolean(namespaceMemberBindings.get(root)?.has(members.join(".")));
     }
     function isPromptNodeMemberName(name) {
-      return name === "agent" || name === "llm" || name === "map";
+      return name === "agent" || name === "docTemplate" || name === "llm" || name === "map";
     }
     function isWorkflowCodeMemberExpression(expression, memberName, memberBindings, namespaceBindings, namespaceMemberBindings) {
       const unwrapped = unwrapExpression(expression);
@@ -373616,6 +373914,7 @@ var require_evaluate_source = __commonJS({
         exportedNames.build.add("build");
         exportedNames.code.add("code");
         exportedNames.promptNodes.add("agent");
+        exportedNames.promptNodes.add("docTemplate");
         exportedNames.promptNodes.add("llm");
         exportedNames.promptNodes.add("map");
         return;
@@ -374113,12 +374412,41 @@ const __workflowCodeApi = (() => {
             }),
         })
     }
+    const docTemplateNode = (options) => {
+        if (!options || typeof options !== 'object' || !options.input || typeof options.input !== 'object')
+            throwAuthoringDiagnostic('docTemplate.input must be an object', options && typeof options === 'object' ? options.__workflowCodeSource : undefined)
+        assertNonEmptyString(options.name, 'docTemplate.name', options.__workflowCodeSource)
+        assertNonEmptyString(options.input.outputFilename, 'docTemplate.input.outputFilename', options.__workflowCodeSource)
+        const template = typeof options.input.template === 'function'
+            ? options.input.template(exclusiveRefContext(options.__workflowCodeSource))
+            : options.input.template
+        if (!isVaultRef(template) && !isVaultAsset(template) && !isWorkflowRef(template))
+            throwAuthoringDiagnostic('docTemplate.input.template must be vault.ref(), vault.asset(), or a workflow reference callback', options.__workflowCodeSource)
+        const placeholders = renderReferenceRecord(options.input.placeholders ?? {}, options.__workflowCodeSource)
+        return freeze({
+            kind: 'node',
+            nodeKind: 'doc-template',
+            name: options.name,
+            ...(options.key !== undefined ? { key: options.key } : {}),
+            input: freeze({
+                template,
+                placeholders: placeholders.values,
+                outputFilename: options.input.outputFilename,
+                ...(options.input.mustache === undefined ? {} : { mustache: options.input.mustache }),
+                ...(options.input.createPermalink === undefined ? {} : { createPermalink: options.input.createPermalink }),
+                ...(options.input.templateFilename === undefined ? {} : { templateFilename: options.input.templateFilename }),
+                ...(options.input.templateFileSize === undefined ? {} : { templateFileSize: options.input.templateFileSize }),
+            }),
+            ...(placeholders.refs.length === 0 ? {} : { placeholderRefs: placeholders.refs }),
+        })
+    }
     return freeze({
         agent: (ref, options) => publishedAgent(ref, options),
         build: buildWorkflow,
         canvas: canvasNode,
         code: codeNode,
         crop: cropNode,
+        docTemplate: docTemplateNode,
         input: freeze({ text: (options) => baseInput('text', options), file: (options) => baseInput('file', options) }),
         llm: (options) => promptNode('llm', options, llmInput),
         map: mapNode,
@@ -376253,8 +376581,8 @@ var require_vault_preflight = __commonJS({
       }
       const results = await Promise.all(references.map(async (reference) => {
         try {
-          await input.vaultApi?.validateVaultRef({ reference });
-          return [];
+          const metadata = await input.vaultApi?.validateVaultRef({ reference });
+          return validateRequirements(reference, metadata, input.compiled);
         } catch (error48) {
           if (hasDiagnostics(error48))
             return error48.diagnostics;
@@ -376264,6 +376592,27 @@ var require_vault_preflight = __commonJS({
       const diagnostics = results.flat();
       return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true, value: createValidation(references) };
     }
+    function validateRequirements(reference, metadata, compiled) {
+      if (!metadata)
+        return [];
+      const requirements = compiled.flatMap((item) => item.resources.vaultRequirements ?? []).filter((requirement) => requirement.reference === reference);
+      const diagnostics = [];
+      for (const requirement of requirements) {
+        if (requirement.expectedName !== void 0 && metadata.name !== void 0 && requirement.expectedName !== metadata.name) {
+          diagnostics.push((0, diagnostics_1.diagnostic)("vault.template.metadata_mismatch", "error", `Vault template ${reference} is named ${metadata.name}, not the declared ${requirement.expectedName}.`, "Update templateFilename or select the matching Vault file before syncing."));
+        }
+        if (requirement.expectedSize !== void 0 && metadata.size !== void 0 && requirement.expectedSize !== metadata.size) {
+          diagnostics.push((0, diagnostics_1.diagnostic)("vault.template.metadata_mismatch", "error", `Vault template ${reference} has size ${metadata.size}, not the declared ${requirement.expectedSize}.`, "Update templateFileSize or select the matching Vault file before syncing."));
+        }
+        if (requirement.requiredExtension !== void 0 && metadata.name !== void 0 && !metadata.name.toLowerCase().endsWith(requirement.requiredExtension)) {
+          diagnostics.push((0, diagnostics_1.diagnostic)("vault.template.invalid_file", "error", `Vault template ${reference} is named ${metadata.name}; docTemplate() requires a ${requirement.requiredExtension} file.`, "Upload a .docx template or correct the Vault reference before syncing."));
+        }
+        if (requirement.requiredMimeType !== void 0 && metadata.mimeType !== void 0 && metadata.mimeType !== requirement.requiredMimeType) {
+          diagnostics.push((0, diagnostics_1.diagnostic)("vault.template.invalid_file", "error", `Vault template ${reference} has MIME type ${metadata.mimeType}; docTemplate() requires ${requirement.requiredMimeType}.`, "Upload a .docx template or correct the Vault reference before syncing."));
+        }
+      }
+      return diagnostics;
+    }
     function collectVaultRefs(compiled) {
       return [...new Set(compiled.flatMap((item) => item.resources?.vaultRefs ?? []))].sort((left, right) => left.localeCompare(right));
     }
@@ -376574,12 +376923,21 @@ var require_remote_api2 = __commonJS({
             throw workflowApiError("vault.ref.inaccessible", "The active Tela environment does not configure a Vault service URL.", "Add services.vault to the active Tela environment and retry.");
           }
           try {
-            await vaultRequest(`/files/${encodeURIComponent((0, reference_1.vaultReferenceId)(input.reference))}`, {
+            const result = await vaultRequest(`/files/${encodeURIComponent((0, reference_1.vaultReferenceId)(input.reference))}`, {
               failureCode: "vault.ref.inaccessible",
               invalidResponseCode: "vault.ref.inaccessible",
               failureMessage: (status2) => `Vault reference ${input.reference} is not accessible in the active Tela context (HTTP ${status2}).`,
               failureHint: "Check the selected workspace, context credentials, and file permissions."
             });
+            const metadata = isRecord3(result.metadata) ? result.metadata : {};
+            const name = typeof metadata.originalFileName === "string" ? metadata.originalFileName : typeof metadata.name === "string" ? metadata.name : void 0;
+            const size = typeof metadata.size === "number" ? metadata.size : typeof result.size === "number" ? result.size : void 0;
+            const mimeType = typeof metadata.mimeType === "string" ? metadata.mimeType : void 0;
+            return {
+              ...name === void 0 ? {} : { name },
+              ...size === void 0 ? {} : { size },
+              ...mimeType === void 0 ? {} : { mimeType }
+            };
           } catch (error48) {
             if (hasDiagnostics(error48))
               throw error48;
@@ -376947,18 +377305,30 @@ var require_vault_assets = __commonJS({
   "../../packages/workflow-code/dist/cli/sync/vault-assets.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.snapshotPreparedWorkflowVaultAssets = snapshotPreparedWorkflowVaultAssets;
+    exports2.prepareWorkflowVaultAssetUploads = prepareWorkflowVaultAssetUploads;
+    exports2.uploadPreparedWorkflowVaultAssets = uploadPreparedWorkflowVaultAssets;
     exports2.prepareWorkflowVaultAssets = prepareWorkflowVaultAssets;
     var node_crypto_1 = require("node:crypto");
     var node_fs_1 = require("node:fs");
     var promises_1 = require("node:fs/promises");
     var node_path_1 = require("node:path");
     var diagnostics_1 = require_diagnostics();
-    async function prepareWorkflowVaultAssets(input) {
+    function snapshotPreparedWorkflowVaultAssets(assets) {
+      return assets.map((asset) => asset.previous ?? Object.freeze({
+        ...asset.asset,
+        name: asset.name,
+        resolvedPath: asset.resolvedPath,
+        contentHash: asset.contentHash,
+        size: asset.content.byteLength,
+        // The compiler only needs lock-derived local metadata at this stage.
+        ref: `vault://${asset.contentHash}`,
+        uploadedAt: ""
+      }));
+    }
+    async function prepareWorkflowVaultAssetUploads(input) {
       if (input.assets.length === 0)
         return { ok: true, value: [] };
-      if (!input.vaultApi) {
-        return { ok: false, diagnostics: [(0, diagnostics_1.diagnostic)("vault.asset.upload_failed", "error", "Vault assets cannot be uploaded because the active remote client has no Vault service.", "Configure services.vault for the active Tela environment and retry before syncing.")] };
-      }
       const existingByKey = new Map((input.existing ?? []).map((asset) => [asset.key, asset]));
       const prepared = [];
       let projectRoot;
@@ -376998,33 +377368,70 @@ var require_vault_assets = __commonJS({
         }
         const contentHash = (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
         const previous = existingByKey.get(asset.key);
-        if (previous?.contentHash === contentHash) {
-          prepared.push(previous);
+        const name = asset.name ?? (0, node_path_1.basename)(resolvedPath);
+        prepared.push(Object.freeze({
+          asset,
+          name,
+          resolvedPath,
+          content,
+          contentHash,
+          ...previous?.contentHash === contentHash ? { previous } : {}
+        }));
+      }
+      return { ok: true, value: prepared };
+    }
+    async function uploadPreparedWorkflowVaultAssets(input) {
+      if (input.assets.length === 0)
+        return { ok: true, value: [] };
+      if (!input.vaultApi) {
+        return { ok: false, diagnostics: [(0, diagnostics_1.diagnostic)("vault.asset.upload_failed", "error", "Vault assets cannot be uploaded because the active remote client has no Vault service.", "Configure services.vault for the active Tela environment and retry before syncing.")] };
+      }
+      const uploaded = [];
+      for (const asset of input.assets) {
+        if (asset.previous) {
+          uploaded.push(asset.previous);
           continue;
         }
-        const name = asset.name ?? (0, node_path_1.basename)(resolvedPath);
         try {
           const ref = await input.vaultApi.uploadVaultAsset({
-            name,
-            ...asset.mimeType === void 0 ? {} : { mimeType: asset.mimeType },
-            content
+            name: asset.name,
+            ...asset.asset.mimeType === void 0 ? {} : { mimeType: asset.asset.mimeType },
+            content: asset.content
           });
-          prepared.push(Object.freeze({
-            ...asset,
-            name,
-            resolvedPath,
-            contentHash,
-            size: content.byteLength,
+          uploaded.push(Object.freeze({
+            ...asset.asset,
+            name: asset.name,
+            resolvedPath: asset.resolvedPath,
+            contentHash: asset.contentHash,
+            size: asset.content.byteLength,
             ref,
             uploadedAt: input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString()
           }));
+          const persisted = await input.onUploaded?.(snapshotKnownWorkflowVaultAssets(input.assets, uploaded));
+          if (persisted !== void 0 && !persisted.ok)
+            return persisted;
         } catch (error48) {
           if (hasDiagnostics(error48))
             return { ok: false, diagnostics: error48.diagnostics };
-          return { ok: false, diagnostics: [(0, diagnostics_1.diagnostic)("vault.asset.upload_failed", "error", `Vault asset ${asset.path} could not be uploaded.`, "Check the active Vault service and retry sync.")] };
+          return { ok: false, diagnostics: [(0, diagnostics_1.diagnostic)("vault.asset.upload_failed", "error", `Vault asset ${asset.asset.path} could not be uploaded.`, "Check the active Vault service and retry sync.")] };
         }
       }
-      return { ok: true, value: prepared };
+      return { ok: true, value: uploaded };
+    }
+    function snapshotKnownWorkflowVaultAssets(plans, uploaded) {
+      return plans.flatMap((plan, index) => {
+        const snapshot = uploaded[index] ?? plan.previous;
+        return snapshot === void 0 ? [] : [snapshot];
+      });
+    }
+    async function prepareWorkflowVaultAssets(input) {
+      if (input.assets.length > 0 && !input.vaultApi) {
+        return { ok: false, diagnostics: [(0, diagnostics_1.diagnostic)("vault.asset.upload_failed", "error", "Vault assets cannot be uploaded because the active remote client has no Vault service.", "Configure services.vault for the active Tela environment and retry before syncing.")] };
+      }
+      const prepared = await prepareWorkflowVaultAssetUploads(input);
+      if (!prepared.ok)
+        return prepared;
+      return await uploadPreparedWorkflowVaultAssets({ assets: prepared.value, vaultApi: input.vaultApi, now: input.now });
     }
     function isWithinRoot(path3, rootDir) {
       const relativePath = (0, node_path_1.relative)((0, node_path_1.resolve)(rootDir), path3);
@@ -377036,6 +377443,79 @@ var require_vault_assets = __commonJS({
   }
 });
 
+// ../../packages/workflow-code/dist/cli/sync/vault-locks.js
+var require_vault_locks = __commonJS({
+  "../../packages/workflow-code/dist/cli/sync/vault-locks.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.createWorkflowVaultAssetLockPersister = createWorkflowVaultAssetLockPersister;
+    var diagnostics_1 = require_diagnostics();
+    var state_1 = require_state2();
+    async function createWorkflowVaultAssetLockPersister(input) {
+      const lockfilePath = (0, state_1.deriveLockfilePath)(input.cwd, input.facts);
+      if (!lockfilePath.ok)
+        return { ok: false, diagnostics: lockfilePath.diagnostics };
+      const remote = await fetchPromptSnapshot(input.remoteApi, input.facts);
+      if (!remote.ok)
+        return { ok: false, diagnostics: remote.diagnostics };
+      let current = input.existing;
+      return {
+        ok: true,
+        value: {
+          persist: async (vaultAssets) => {
+            const plan = (0, state_1.planRemoteSnapshotWrite)(lockfilePath.value, input.facts, remote.value, current, void 0, vaultAssets);
+            if (!plan.ok)
+              return { ok: false, diagnostics: plan.diagnostics };
+            const written = await (0, state_1.writePlannedLockfile)(plan.value);
+            if (!written.ok)
+              return { ok: false, diagnostics: written.diagnostics };
+            current = {
+              path: lockfilePath.value,
+              hash: written.value.hash,
+              content: plan.value.content,
+              lockfile: plan.value.lockfile
+            };
+            return { ok: true, value: current };
+          }
+        }
+      };
+    }
+    async function fetchPromptSnapshot(remoteApi, facts) {
+      const promptId = facts.context.promptId;
+      if (promptId === void 0) {
+        return {
+          ok: false,
+          diagnostics: [(0, diagnostics_1.diagnostic)("state.prompt_id.missing", "error", `Workflow target ${facts.targetName} has no prompt id for context ${facts.context.key}`, "Add promptId to the active workflow context binding before retrying the upload.")]
+        };
+      }
+      try {
+        const snapshot = await remoteApi.fetchPromptSnapshot({
+          promptId,
+          projectId: facts.context.projectId
+        });
+        if (snapshot.prompt.id !== promptId) {
+          return {
+            ok: false,
+            diagnostics: [(0, diagnostics_1.diagnostic)("sync.remote.prompt_mismatch", "error", `Remote prompt ${snapshot.prompt.id} does not match configured prompt ${promptId}`, "Check the workflow target promptId binding.")]
+          };
+        }
+        return { ok: true, value: snapshot };
+      } catch (error48) {
+        return {
+          ok: false,
+          diagnostics: diagnosticsFromError(error48)
+        };
+      }
+    }
+    function diagnosticsFromError(error48) {
+      if (error48 && typeof error48 === "object" && "diagnostics" in error48 && Array.isArray(error48.diagnostics))
+        return error48.diagnostics;
+      const detail = error48 instanceof Error ? ` ${error48.message}` : "";
+      return [(0, diagnostics_1.diagnostic)("sync.remote.request_failed", "error", `Unable to fetch the workflow state before persisting uploaded Vault assets.${detail}`, "Check the active Tela context and retry sync.")];
+    }
+  }
+});
+
 // ../../packages/workflow-code/dist/cli/sync/index.js
 var require_sync2 = __commonJS({
   "../../packages/workflow-code/dist/cli/sync/index.js"(exports2) {
@@ -377062,6 +377542,7 @@ var require_sync2 = __commonJS({
     __exportStar(require_remote_api2(), exports2);
     __exportStar(require_types5(), exports2);
     __exportStar(require_vault_assets(), exports2);
+    __exportStar(require_vault_locks(), exports2);
     __exportStar(require_vault_preflight(), exports2);
   }
 });
@@ -377503,7 +377984,7 @@ var require_publish2 = __commonJS({
         tsconfig: configResult.value.config.tsconfig,
         targets: resolved.targets,
         rootDir: context.cwd,
-        vaultApi: remoteApi
+        remoteApi
       });
       if (!prepared.ok)
         return { exitCode: 1, diagnostics: [...environmentCreationDiagnostics, ...prepared.diagnostics], compiled: prepared.compiled };
@@ -377596,7 +378077,7 @@ var require_publish2 = __commonJS({
       return { ok: true, targets: Object.entries(workflows).map(([name, target]) => ({ name, target })) };
     }
     async function preparePublishTargets(options2) {
-      const prepared = [];
+      const staged = [];
       for (const selected of options2.targets) {
         const source = await (0, load_source_1.loadWorkflowSource)((0, node_path_1.dirname)(options2.configPath), selected.target, options2.configEnv, options2.tsconfig);
         if (!source.ok)
@@ -377640,26 +378121,75 @@ var require_publish2 = __commonJS({
           if (!lockfileIdentity.ok)
             return { ok: false, diagnostics: lockfileIdentity.diagnostics, compiled: initial };
         }
-        const vaultAssets = await (0, sync_1.prepareWorkflowVaultAssets)({
+        const vaultPlans = await (0, sync_1.prepareWorkflowVaultAssetUploads)({
           rootDir: (0, node_path_1.dirname)(options2.configPath),
           assets: initial.resources.vaultAssets ?? [],
-          existing: existing.ok ? existing.value.lockfile.vaultAssets : void 0,
-          vaultApi: options2.vaultApi
+          existing: existing.ok ? existing.value.lockfile.vaultAssets : void 0
         });
-        if (!vaultAssets.ok)
-          return { ok: false, diagnostics: vaultAssets.diagnostics, compiled: initial };
-        const compiled = (0, compiler_1.transpileWorkflow)({
+        if (!vaultPlans.ok)
+          return { ok: false, diagnostics: vaultPlans.diagnostics, compiled: initial };
+        const preflight = (0, compiler_1.transpileWorkflow)({
           targetName: selected.name,
           workflowKey: selected.target.workflowKey,
           title: selected.target.title,
           declaration: source.value.declaration,
           source: source.value.source,
+          vaultAssets: (0, sync_1.snapshotPreparedWorkflowVaultAssets)(vaultPlans.value)
+        });
+        if (preflight.diagnostics.some((item) => item.severity === "error"))
+          return { ok: false, diagnostics: [...preflight.diagnostics], compiled: preflight };
+        staged.push({
+          ...selected,
+          source: source.value,
+          preflight,
+          vaultPlans: vaultPlans.value,
+          ...existing.ok ? { lockfileState: existing.value } : {}
+        });
+      }
+      const prepared = [];
+      for (const stagedTarget of staged) {
+        let onUploaded;
+        if (stagedTarget.vaultPlans.some((asset) => asset.previous === void 0)) {
+          const persister = await (0, sync_1.createWorkflowVaultAssetLockPersister)({
+            cwd: options2.rootDir,
+            facts: {
+              targetName: stagedTarget.name,
+              workflowKey: stagedTarget.preflight.workflowKey,
+              context: {
+                key: stagedTarget.identity.contextKey ?? "default",
+                ...stagedTarget.identity.contextId === void 0 ? {} : { id: stagedTarget.identity.contextId },
+                projectId: stagedTarget.identity.projectId,
+                promptId: stagedTarget.identity.promptId
+              }
+            },
+            existing: stagedTarget.lockfileState,
+            remoteApi: options2.remoteApi
+          });
+          if (!persister.ok)
+            return { ok: false, diagnostics: persister.diagnostics, compiled: stagedTarget.preflight };
+          onUploaded = persister.value.persist;
+        }
+        const vaultAssets = await (0, sync_1.uploadPreparedWorkflowVaultAssets)({
+          assets: stagedTarget.vaultPlans,
+          vaultApi: options2.remoteApi,
+          ...onUploaded === void 0 ? {} : { onUploaded }
+        });
+        if (!vaultAssets.ok)
+          return { ok: false, diagnostics: vaultAssets.diagnostics, compiled: stagedTarget.preflight };
+        const compiled = (0, compiler_1.transpileWorkflow)({
+          targetName: stagedTarget.name,
+          workflowKey: stagedTarget.target.workflowKey,
+          title: stagedTarget.target.title,
+          declaration: stagedTarget.source.declaration,
+          source: stagedTarget.source.source,
           vaultAssets: vaultAssets.value
         });
         if (compiled.diagnostics.some((item) => item.severity === "error"))
           return { ok: false, diagnostics: [...compiled.diagnostics], compiled };
         prepared.push({
-          ...selected,
+          name: stagedTarget.name,
+          target: stagedTarget.target,
+          identity: stagedTarget.identity,
           compiled,
           vaultAssets: vaultAssets.value
         });
@@ -377871,30 +378401,14 @@ var require_sync3 = __commonJS({
         const existing = await (0, state_1.readLockfile)(lockPath.value);
         if (!existing.ok && existing.diagnostics[0]?.code !== "state.lockfile.missing")
           return { ok: false, diagnostics: existing.diagnostics, compiled: initialSymbolic };
-        const vaultAssets = await (0, sync_1.prepareWorkflowVaultAssets)({
-          rootDir: options2.projectDir,
-          assets: initialSymbolic.resources.vaultAssets ?? [],
-          existing: existing.ok ? existing.value.lockfile.vaultAssets : void 0,
-          vaultApi: options2.vaultApi
-        });
-        if (!vaultAssets.ok)
-          return { ok: false, diagnostics: vaultAssets.diagnostics, compiled: initialSymbolic };
-        const symbolic = (0, compiler_1.transpileWorkflow)({
-          targetName: selected.name,
-          workflowKey: selected.target.workflowKey,
-          title: selected.target.title,
-          declaration: sourceResult.value.declaration,
-          source: sourceResult.value.source,
-          vaultAssets: vaultAssets.value
-        });
-        if (symbolic.diagnostics.some((item) => item.severity === "error"))
-          return { ok: false, diagnostics: [...symbolic.diagnostics], compiled: symbolic };
         symbolicPrepared.push({
           ...selected,
           source: sourceResult.value,
-          symbolic,
-          compiled: symbolic,
-          vaultAssets: vaultAssets.value,
+          symbolic: initialSymbolic,
+          compiled: initialSymbolic,
+          vaultAssets: [],
+          ...existing.ok ? { lockfile: existing.value.lockfile } : {},
+          ...existing.ok ? { lockfileState: existing.value } : {},
           identity: {
             contextKey: identity2.value.contextKey,
             contextId: identity2.value.contextId,
@@ -377905,7 +378419,7 @@ var require_sync3 = __commonJS({
       }
       const needsCatalog = options2.catalogApi !== void 0 || symbolicPrepared.some((item) => item.symbolic.remoteRefs.length > 0);
       if (!needsCatalog)
-        return { ok: true, targets: symbolicPrepared };
+        return await prepareVaultAssetsForTargets({ ...options2, remoteApi: options2.vaultApi }, symbolicPrepared);
       let api;
       try {
         api = options2.catalogApi ?? await (0, catalog_1.createWorkflowCatalogApi)();
@@ -377928,19 +378442,12 @@ var require_sync3 = __commonJS({
       }
       const prepared = [];
       for (const item of symbolicPrepared) {
-        const facts = factsForPrepared(item);
-        const lockPath = (0, state_1.deriveLockfilePath)(options2.rootDir, facts);
-        if (!lockPath.ok)
-          return { ok: false, diagnostics: lockPath.diagnostics, compiled: item.symbolic };
-        const existing = await (0, state_1.readLockfile)(lockPath.value);
-        if (!existing.ok && existing.diagnostics[0]?.code !== "state.lockfile.missing")
-          return { ok: false, diagnostics: existing.diagnostics, compiled: item.symbolic };
         const initialGenerated = (0, catalog_1.validateAndLockRemoteRefs)({
           contextId: snapshot.context.id,
           workspaceId: snapshot.context.workspaceId,
           snapshot,
           refs: item.symbolic.remoteRefs,
-          existing: existing.ok ? existing.value.lockfile.generatedMetadata : void 0
+          existing: item.lockfile?.generatedMetadata
         });
         if (initialGenerated.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
           return { ok: false, diagnostics: [...initialGenerated.diagnostics], compiled: item.symbolic };
@@ -377958,26 +378465,87 @@ var require_sync3 = __commonJS({
           workspaceId: snapshot.context.workspaceId,
           snapshot,
           refs: compiled.remoteRefs,
-          existing: existing.ok ? existing.value.lockfile.generatedMetadata : void 0
+          existing: item.lockfile?.generatedMetadata
         });
         const diagnostics = [...generated.diagnostics, ...compiled.diagnostics];
-        if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
+        if (diagnostics.some((diagnostic) => diagnostic.severity === "error" && diagnostic.code !== "vault.asset.missing_lock"))
           return { ok: false, diagnostics, compiled };
-        prepared.push({ ...item, generatedMetadata: generated.locks, compiled });
+        prepared.push({
+          ...item,
+          generatedMetadata: generated.locks,
+          remote: { kind: "resolved", snapshot, locks: generated.locks.refs },
+          compiled
+        });
       }
-      return { ok: true, targets: prepared };
+      return await prepareVaultAssetsForTargets({ ...options2, remoteApi: options2.vaultApi }, prepared);
     }
-    function factsForPrepared(prepared) {
-      return {
-        targetName: prepared.name,
-        workflowKey: prepared.symbolic.workflowKey,
-        context: {
-          key: prepared.identity.contextKey ?? "default",
-          ...prepared.identity.contextId === void 0 ? {} : { id: prepared.identity.contextId },
-          projectId: prepared.identity.projectId,
-          promptId: prepared.identity.promptId
+    async function prepareVaultAssetsForTargets(options2, targets) {
+      const staged = [];
+      for (const target of targets) {
+        const vaultAssets = await (0, sync_1.prepareWorkflowVaultAssetUploads)({
+          rootDir: options2.projectDir,
+          assets: target.symbolic.resources.vaultAssets ?? [],
+          existing: target.lockfile?.vaultAssets
+        });
+        if (!vaultAssets.ok)
+          return { ok: false, diagnostics: vaultAssets.diagnostics, compiled: target.compiled };
+        const preflight = (0, compiler_1.transpileWorkflow)({
+          targetName: target.name,
+          workflowKey: target.target.workflowKey,
+          title: target.target.title,
+          declaration: target.source.declaration,
+          source: target.source.source,
+          ...target.remote === void 0 ? {} : { remote: target.remote },
+          vaultAssets: (0, sync_1.snapshotPreparedWorkflowVaultAssets)(vaultAssets.value)
+        });
+        if (preflight.diagnostics.some((item) => item.severity === "error"))
+          return { ok: false, diagnostics: [...preflight.diagnostics], compiled: preflight };
+        staged.push({ target, vaultAssets: vaultAssets.value });
+      }
+      const prepared = [];
+      for (const item of staged) {
+        let onUploaded;
+        if (item.vaultAssets.some((asset) => asset.previous === void 0)) {
+          const persister = await (0, sync_1.createWorkflowVaultAssetLockPersister)({
+            cwd: options2.rootDir,
+            facts: {
+              targetName: item.target.name,
+              workflowKey: item.target.symbolic.workflowKey,
+              context: {
+                key: item.target.identity.contextKey ?? "default",
+                ...item.target.identity.contextId === void 0 ? {} : { id: item.target.identity.contextId },
+                projectId: item.target.identity.projectId,
+                promptId: item.target.identity.promptId
+              }
+            },
+            existing: item.target.lockfileState,
+            remoteApi: options2.remoteApi
+          });
+          if (!persister.ok)
+            return { ok: false, diagnostics: persister.diagnostics, compiled: item.target.compiled };
+          onUploaded = persister.value.persist;
         }
-      };
+        const vaultAssets = await (0, sync_1.uploadPreparedWorkflowVaultAssets)({
+          assets: item.vaultAssets,
+          vaultApi: options2.vaultApi,
+          ...onUploaded === void 0 ? {} : { onUploaded }
+        });
+        if (!vaultAssets.ok)
+          return { ok: false, diagnostics: vaultAssets.diagnostics, compiled: item.target.compiled };
+        const compiled = (0, compiler_1.transpileWorkflow)({
+          targetName: item.target.name,
+          workflowKey: item.target.target.workflowKey,
+          title: item.target.target.title,
+          declaration: item.target.source.declaration,
+          source: item.target.source.source,
+          ...item.target.remote === void 0 ? {} : { remote: item.target.remote },
+          vaultAssets: vaultAssets.value
+        });
+        if (compiled.diagnostics.some((item2) => item2.severity === "error"))
+          return { ok: false, diagnostics: [...compiled.diagnostics], compiled };
+        prepared.push({ ...item.target, compiled, vaultAssets: vaultAssets.value });
+      }
+      return { ok: true, targets: prepared };
     }
     function renderSingleSyncResult(item) {
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Tela command line tools for local state and agent workflows.",
   "engines": {
     "node": ">=22"