@meistrari/tela-cli 0.7.58 → 1.0.0

package/dist/credentials.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCliCredentialAdapter = createCliCredentialAdapter;
+const tela_local_config_1 = require("@meistrari/tela-local-config");
+function createCliCredentialAdapter(env = process.env) {
+    return (0, tela_local_config_1.createLocalCredentialAdapter)(env);
+}

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

@@ -0,0 +1,604 @@
+## API Reference
+
+Workflow Code lets you describe a Tela Workflow V3 workflow as typed, inert TypeScript. Authoring APIs create declarations only. The compiler later validates references, evaluates supported `code()` handlers from source, and produces deterministic Workflow V3 payloads.
+
+Use this page as the complete authoring guide while writing workflow source.
+
+### Authoring model
+
+Import the authoring helpers from `@meistrari/workflow-code`.
+
+```ts
+import {
+    agent,
+    build,
+    canvas,
+    code,
+    input,
+    llm,
+    splitter,
+    vault,
+    remote,
+    workflow,
+} from '@meistrari/workflow-code'
+import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
+```
+
+| API | Use it for |
+| --- | --- |
+| [`workflow()`](#workflowworkflowkey) | Naming the workflow with a stable source key. |
+| [`build()`](#buildworkflowhandle-options) | Creating the default-exported declaration consumed by `compile`. |
+| [`input.text()`](#inputtextoptions) | Text input supplied by a user, API caller, or run payload. |
+| [`input.file()`](#inputfileoptions) | File input supplied by upload or Vault reference. |
+| [`llm()`](#llmoptions) | Single model-call transformation with optional structured output. |
+| [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
+| [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
+| [`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. |
+| [`code()`](#codeoptions) | Sandboxed runtime JavaScript/TypeScript execution. |
+| [`ref()` / `paths()` / `formats()`](#references-ref-paths-and-formats) | References to workflow inputs or prior node output in prompt callbacks and code handlers. |
+
+A workflow file normally creates inputs, creates nodes, then default-exports `build(workflow(...), { inputs, nodes })`.
+
+```ts
+import { agent, build, input, llm, remote, workflow } from '@meistrari/workflow-code'
+
+const topic = input.text({ name: 'topic', required: true })
+
+const outline = llm({
+    name: 'Draft outline',
+    input: {
+        temperature: 0.2,
+        prompt: ({ ref }) => `Create an outline about ${ref(topic).formats().format}.`,
+    },
+    schema: {
+        bullets: { type: 'array', items: { type: 'string' } },
+    },
+})
+
+const reviewer = remote().agent().byId('published-agent-id')
+
+const review = agent(reviewer, {
+    name: 'Review outline',
+    input: {
+        message: ({ ref, paths }) => [
+            'Review this outline for a new Tela user.',
+            `Bullets: ${ref(outline, paths(outline).bullets).formats().format}`,
+        ].join('\n'),
+        inputs: {},
+    },
+})
+
+export default build(workflow('first-workflow'), {
+    inputs: [topic],
+    nodes: [outline, review],
+})
+```
+
+Rules to keep in mind:
+
+- Declarations are inert. They do not create remote workflows, publish versions, or run handlers.
+- `nodes` order is execution order. Adjacent nodes compile to default Workflow V3 edges.
+- `key` is optional on inputs and nodes. Use it when display `name` may change but identity should stay stable.
+- References in node inputs may target workflow inputs or earlier nodes. Forward references are compile diagnostics.
+
+
+### `remote()`
+
+```ts
+import { agent, build, canvas, input, remote, workflow } from '@meistrari/workflow-code'
+
+const document = input.file({ name: 'document', required: true })
+const extractInvoice = remote().canvas().Finance['Extract Invoice']
+const triage = remote().agent().byId('published-agent-id')
+
+const extract = canvas(extractInvoice, {
+    name: 'Extract invoice',
+    input: {
+        variables: ({ ref }) => ({ file: ref(document) }),
+    },
+})
+
+const classify = agent(triage, {
+    name: 'Triage extraction',
+    input: {
+        message: ({ ref }) => `Classify ${ref(extract).formats().parser}`,
+        inputs: ({ ref }) => ({ document: ref(document) }),
+    },
+})
+
+export default build(workflow('remote-catalog-example'), {
+    inputs: [document],
+    nodes: [extract, classify],
+})
+```
+
+Run `tela workflow codegen` before typechecking to generate named paths. User workflow source still imports only from `@meistrari/workflow-code`; generated catalog declarations augment those public types and should not be imported from workflow files.
+
+`remote()` values are inert path refs, not API calls or runtime resource objects. `remote().canvas()`, `.workflow()`, `.agent()`, and `.models()` expose generated namespaces. Use bracket access for names with spaces, punctuation, reserved words, or any other segment that is not a safe JavaScript identifier. `byId()` and model `raw()` are explicit escape hatches when a generated name is unavailable or an ID is clearer.
+
+`compile` preserves remote refs symbolically and remains offline. `sync` refreshes the active catalog, validates and locks referenced resources, resolves the refs, then lowers them for remote mutation.
+
+### References: `ref()`, `paths()`, and `formats()`
+
+Workflow references connect node inputs to workflow inputs or earlier node outputs. Under the hood, Tela represents those links as URI references such as `input://customer_question` or `step://extract_invoice?path=total&format=...`. Workflow Code hides the URI string and exposes typed helpers instead.
+
+The important rule is that reference compatibility is decided by the destination node input. A node input declares which value shapes it accepts and which reference formats make sense for those shapes. For example, a prompt input can accept text-oriented references, file-oriented references, object fields, numbers, or booleans, but each source may expose different formats. The helper types should guide you toward the formats that are valid for the specific input you are authoring.
+
+| Helper | What it does |
+| --- | --- |
+| `ref(input)` | References a workflow input. In prompt-like inputs it renders a reference token; in `code()` handlers it reads the runtime value. |
+| `ref(node)` | References an earlier node output. Forward references to later nodes are compile diagnostics. |
+| `paths(node).field` | Selects a typed field from a node output schema. Pass the selected path as the second argument to `ref()`. |
+| `formats().format` | Chooses the destination-compatible representation for a prompt/reference token. Available formats depend on the destination input and referenced value shape. |
+
+```ts
+const extractInvoice = llm({
+    name: 'Extract invoice data',
+    input: {
+        prompt: ({ ref }) => [
+            'Extract invoice data from this document.',
+            ref(invoicePdf).formats().format,
+        ].join('\n'),
+    },
+    schema: {
+        vendor: { type: 'string' },
+        total: { type: 'number' },
+    },
+})
+
+const reviewInvoice = llm({
+    name: 'Review invoice extraction',
+    input: {
+        prompt: ({ ref, paths }) => [
+            `Vendor: ${ref(extractInvoice, paths(extractInvoice).vendor).formats().format}`,
+            `Total: ${ref(extractInvoice, paths(extractInvoice).total).formats().format}`,
+        ].join('\n'),
+    },
+})
+
+const normalizeInvoice = code({
+    name: 'Normalize invoice',
+    handler: ({ ref, paths }) => {
+        const vendor = ref(extractInvoice, paths(extractInvoice).vendor)
+        const total = Number(ref(extractInvoice, paths(extractInvoice).total))
+        return { vendor: String(vendor).trim(), totalCents: Math.round(total * 100) }
+    },
+})
+```
+
+Reference rules:
+
+- References in node inputs may target workflow inputs or earlier nodes.
+- `paths()` only accepts node declarations, not inputs.
+- Path tokens are branded; do not replace them with strings or arrays.
+- A path token must come from the same node used in `ref()`, or authoring throws `ref path source must match ref target`.
+- In prompt/reference inputs, call `formats()` on `ref(...)` when the input needs a specific representation.
+- In code handlers, `ref(...)` returns runtime data directly, so `formats()` is not available.
+
+### `workflow(workflowKey)`
+
+```ts
+function workflow(workflowKey: string): WorkflowHandle
+```
+
+Creates the workflow handle passed to `build()`. The key is the stable source identity for review, config matching, and deterministic compiler output.
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `workflowKey` | `string` | Yes | Non-empty author-facing key such as `invoice-processing`. If `workflow-code.config.ts` sets `workflowKey`, compile reports a mismatch when values differ. |
+
+| Returns | Description |
+| --- | --- |
+| `WorkflowHandle` | Frozen object with `kind: 'workflow'` and `workflowKey`. |
+
+```ts
+const invoiceWorkflow = workflow('invoice-processing')
+```
+
+Use lowercase, stable, reviewable keys. Do not put project ids, prompt ids, secrets, or environment names in `workflowKey`.
+
+### `build(workflowHandle, options)`
+
+```ts
+type BuildOptions = {
+    input?: readonly InputDeclaration[]
+    inputs?: readonly InputDeclaration[]
+    nodes: readonly NodeDeclaration[]
+}
+
+function build(workflow: WorkflowHandle, options: BuildOptions): WorkflowDeclaration
+```
+
+Finalizes the workflow declaration. The compiled graph is derived from `inputs` and ordered `nodes`; authors should not hand-author raw Workflow V3 edge objects.
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `workflow` | `WorkflowHandle` | Yes | Handle returned by `workflow()`. |
+| `options.input` | `readonly InputDeclaration[]` | No | Scaffold-friendly alias for `options.inputs`. |
+| `options.inputs` | `readonly InputDeclaration[]` | No | Inputs available to prompts, code handlers, and runtime callers. Defaults to an empty array. |
+| `options.nodes` | `readonly NodeDeclaration[]` | Yes | Ordered node sequence. MVP compile lowers adjacent nodes into default edges. |
+
+| Returns | Description |
+| --- | --- |
+| `WorkflowDeclaration` | Frozen declaration expected as the workflow module default export. |
+
+```ts
+export default build(workflow('support-triage'), {
+    inputs: [message, attachment],
+    nodes: [classify, draftReply, normalizeResult],
+})
+```
+
+Author one `build()` default export per workflow entrypoint.
+
+### `input.text(options)`
+
+```ts
+declare function text(options: BaseInputOptions): TextInputDeclaration
+```
+
+Declares a text input. Text inputs are best for prompts, questions, small JSON snippets, URLs, or freeform user instructions.
+
+
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Human-readable input name. Also used as fallback identity when `key` is omitted. |
+| `required` | `boolean` | No | `false` | Whether callers must supply the value. |
+| `description` | `string` | No | — | Help text for UI and metadata. |
+| `key` | `string` | No | `name` | Stable identity independent from display `name`. |
+
+```ts
+const customerQuestion = input.text({
+    name: 'customer question',
+    key: 'customer_question',
+    required: true,
+    description: 'Question or support request to answer.',
+})
+```
+
+### `input.file(options)`
+
+```ts
+declare function file(options: BaseInputOptions): FileInputDeclaration
+```
+
+Declares a file input. Use it for uploaded documents, images, or PDFs passed to the workflow.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Human-readable file input name. |
+| `required` | `boolean` | No | `false` | Whether callers must supply the file. |
+| `description` | `string` | No | — | UI/help text explaining supported file expectations. |
+| `key` | `string` | No | `name` | Stable identity independent from display `name`. |
+
+```ts
+const invoicePdf = input.file({
+    name: 'invoice PDF',
+    key: 'invoice_pdf',
+    required: true,
+    description: 'PDF invoice to extract and review.',
+})
+```
+
+### `llm(options)`
+
+```ts
+type LlmOptions = {
+    name: string
+    key?: string
+    input: {
+        prompt: string | ((context: PromptFactoryContext) => string)
+        model?: string
+        temperature?: number
+    }
+    schema?: WorkflowCodeOutputSchema | null
+}
+
+function llm(options: LlmOptions): LlmNodeDeclaration
+```
+
+Declares a single LLM completion node. Use `llm()` for bounded transformations where one model call should produce the desired output.
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | Yes | Display name and fallback node identity. Must be non-empty. |
+| `key` | `string` | No | Stable identity when `name` may change. |
+| `input.prompt` | `string \| (context) => string` | Yes | Prompt text. Callback form enables `ref()` and `paths()`. Must render to non-empty string. |
+| `input.model` | `string` | No | Model id passed through to Workflow V3 completion input. |
+| `input.temperature` | `number` | No | Model temperature passed through to Workflow V3 completion input. |
+| `schema` | `WorkflowCodeOutputSchema \| null` | No | Structured output fields for the model response. Use field names mapped to JSON-schema-like field definitions; omit for default behavior or set `null` when intentionally no schema should be emitted. |
+
+`schema` helps constrain the completion output and creates named fields that later nodes can reference with `paths()`. Keep fields small and explicit: use `type`, `description`, `enum`, `properties`, `items`, and `required` when useful.
+
+```ts
+const extractInvoice = llm({
+    name: 'Extract invoice data',
+    key: 'extract_invoice',
+    input: {
+        model: 'gpt-4.1-mini',
+        temperature: 0,
+        prompt: ({ ref }) => [
+            'Extract invoice data from this document.',
+            ref(invoicePdf).formats().format,
+        ].join('\n'),
+    },
+    schema: {
+        vendor: { type: 'string', description: 'Supplier name.' },
+        total: { type: 'number', description: 'Invoice total.' },
+        lineItems: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    description: { type: 'string' },
+                    amount: { type: 'number' },
+                },
+            },
+        },
+    },
+})
+```
+
+### `canvas(remoteRef, options)`
+
+```ts
+type RemoteCanvasOptions<Ref extends WorkflowCodeRemoteExecutableRef, Environment extends RemoteEnvironment<Ref> | undefined = undefined> = {
+    name: string
+    key?: string
+} & (Environment extends string
+    ? { environment: Environment, input: { variables: RemoteReferenceRecordInput<RemoteInputObject<Ref, Environment>> } }
+    : RemoteDefaultOptions<Ref>)
+
+function canvas<Ref extends WorkflowCodeRemoteExecutableRef, Environment extends RemoteEnvironment<Ref> | undefined = undefined>(
+    ref: Ref,
+    options: RemoteCanvasOptions<Ref, Environment>,
+): CanvasNodeHandle<RemoteSelectedOutput<Ref, Environment>>
+```
+
+Declares an executable remote Canvas or Workflow node. The `remoteRef` must come from `remote().canvas()` or `remote().workflow()`. Generated metadata supplies known input variables, output fields, and environment choices when the catalog exposes them.
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | Yes | Display name and fallback node identity. Must be non-empty. |
+| `key` | `string` | No | Stable identity when `name` may change. |
+| `environment` | Generated literal union | Catalog-dependent | Environment name narrowed by the generated ref, such as `'production' \| 'staging'`. A generated ref with multiple non-production targets requires `environment`; generated refs with production metadata, no target metadata, or one selectable target may omit it. |
+| `input.variables` | `Record<string, unknown> \| (context) => Record<string, unknown>` | Yes | Variables passed to the remote executable. Callback form enables `ref()` and typed variable refs. |
+
+Generated declarations narrow `environment` to catalog literal names and conditionally make it required; it is not an arbitrary `string` escape hatch. The signature above uses the named `RemoteCanvasOptions` shape because the exact requiredness depends on the generated ref's target metadata rather than on a universal optional or required overload. Use `byId()` only for explicit ID binding, then rely on `sync` for authenticated environment validation when generated metadata is unavailable or stale.
+
+After sync resolution, this becomes the existing Workflow V3 Canvas action with `canvasId`, optional `environmentName`, and resolved `variables`. Compile keeps the ref symbolic until orchestration supplies the active catalog and locks.
+
+### `splitter(options)`
+
+```ts
+type SplitterOptions = {
+    name: string
+    key?: string
+    input: {
+        file: WorkflowCodeExclusiveFileSource
+        chunkSize?: number
+        type?: 'pdf' | 'csv'
+        mode?: 'single-pages' | 'smart-files'
+        customPrompt?: string
+        customPromptMode?: 'always' | 'fallback'
+    }
+}
+
+function splitter(options: SplitterOptions): SplitterNodeHandle
+```
+
+Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()`, or an array of Vault refs. It does not accept arbitrary strings or text references.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Display name and fallback node identity. |
+| `key` | `string` | No | `name` | Stable identity when the display name may change. |
+| `input.file` | `WorkflowCodeExclusiveFileSource` | Yes | — | File/File-array workflow reference, `vault.ref()`, or array of Vault refs. |
+| `input.chunkSize` | `number` | No | `1` | Pages per PDF chunk or rows per CSV chunk. |
+| `input.type` | `'pdf' \| 'csv'` | No | `'pdf'` | Splitter document type. |
+| `input.mode` | `'single-pages' \| 'smart-files'` | No | `'single-pages'` | Fixed chunking or smart document-boundary detection. |
+| `input.customPrompt` | `string` | No | — | Optional smart-files instruction, up to 2,000 characters. |
+| `input.customPromptMode` | `'always' \| 'fallback'` | No | `'always'` | Whether the custom smart-files prompt is always used or only as fallback. |
+
+```ts
+const invoice = input.file({
+    name: 'invoice',
+    required: true,
+})
+
+const pages = splitter({
+    name: 'Split invoice',
+    input: {
+        file: ({ ref }) => ref(invoice),
+        chunkSize: 1,
+        type: 'pdf',
+    },
+})
+
+const splitFirstPageAgain = splitter({
+    name: 'Split first page again',
+    input: {
+        file: ({ ref, paths }) => ref(pages, paths(pages)[0].file),
+    },
+})
+```
+
+Structured `llm()` outputs and published Agent outputs from `agent(remoteRef, options)` are valid sources only when the selected output or path has a file-compatible schema. A file schema declares string-valued schemas for `name` and at least one locator property (`fileUrl`, `vaultReference`, or `base64`). Any other declared transport string field (`mimeType` or another locator) must also be string-valued. Arrays are compatible when their item schema is file-compatible. The `x-tela-kind: 'file'` marker is metadata only and does not bypass structural validation. Schema presence or matching property names alone is not sufficient: scalar, generic-object, missing, malformed, or otherwise incompatible paths produce `compiler.ref.incompatible`.
+
+```ts
+const generated = llm({
+    name: 'Generate document reference',
+    input: { prompt: 'Return the generated document reference.' },
+    schema: {
+        document: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                fileUrl: { type: 'string' },
+            },
+        },
+    },
+})
+
+const generatedPages = splitter({
+    name: 'Split generated document',
+    input: {
+        file: ({ ref, paths }) => ref(generated, paths(generated).document),
+    },
+})
+```
+
+`code()` outputs can also feed `splitter.input.file`. Compile statically infers the original handler return without calling it. Transport-file objects, nested paths, file arrays, pass-through file refs, and `File`/`Blob` values are supported. Scalar, malformed, `any`, `unknown`, and mixed file/non-file returns produce `compiler.ref.incompatible`.
+
+```ts
+const generatedByCode = code({
+    name: 'Generate document in code',
+    handler: () => new File(['document contents'], 'generated.pdf', {
+        type: 'application/pdf',
+    }),
+})
+
+const generatedCodePages = splitter({
+    name: 'Split code document',
+    input: {
+        file: ({ ref }) => ref(generatedByCode),
+    },
+})
+```
+
+The referenced runtime value still needs to describe a real file. Declaring `fileUrl` or `vaultReference` in an LLM schema does not upload or create a Vault file.
+
+### `vault.ref(reference)`
+
+```ts
+const vault: {
+    ref: <Reference extends `vault://${string}`>(
+        reference: Reference,
+    ) => WorkflowCodeVaultRef<Reference>
+}
+```
+
+Creates an inert declaration for a file that already exists in Vault. The reference must contain a UUID v4 or SHA-256 file id. Calling `vault.ref()` does not read credentials, contact Vault, download the file, or mutate local state during source evaluation.
+
+```ts
+const existingInvoice = vault.ref(
+    'vault://550e8400-e29b-41d4-a716-446655440000',
+)
+
+const existingPages = splitter({
+    name: 'Split existing invoice',
+    input: { file: existingInvoice },
+})
+```
+
+During compile, a direct Vault ref used by `splitter.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.
+
+### `agent(remoteRef, options)`
+
+```ts
+function agent<Ref extends WorkflowCodeRemoteAgentRef>(
+    ref: Ref,
+    options: {
+        name: string
+        key?: string
+        input: {
+            message: string | ((context: PromptFactoryContext) => string)
+            inputs: Record<string, unknown> | ((context: PromptFactoryContext) => Record<string, unknown>)
+            environmentVariables?: Record<string, string>
+        }
+    },
+): AgentNodeHandle<RemoteAgentOutput<Ref>>
+```
+
+Declares a published Agent invocation. The `remoteRef` must come from `remote().agent()`. Generated metadata supplies known required inputs and output types when the catalog contains an authoritative published-Agent contract.
+
+`input.message` is prompt-like, may use `ref()` callbacks, and must render to a non-empty string. `input.inputs` supplies the published Agent's named inputs and may contain workflow input or prior-node refs. Optional `environmentVariables` remain authored strings; they are not resolved through catalog metadata.
+
+Lowering targets the existing Workflow V3 `agent-fcc` action fields `agentId`, `message`, `inputs`, and optional `environmentVariables` only. It does not emit output schema, revision, or catalog-hash fields in the node input.
+
+### `code(options)`
+
+```ts
+type CodeOptions<Handler extends CodeHandler = CodeHandler> = {
+    name: string
+    key?: string
+    handler: Handler
+    libraries?: readonly string[]
+}
+
+type CodeHandler<Output = unknown> = (
+    context: CodeHandlerContext,
+) => Output | Promise<Output>
+
+function code<Handler extends CodeHandler>(
+    options: CodeOptions<Handler>,
+): CodeNodeHandle<Awaited<ReturnType<Handler>>>
+```
+
+Declares a typed code-execution node. `compile` evaluates trusted declaration modules but does not call the handler. Instead, the compiler extracts supported handler source, rewrites Workflow Code `ref()` reads to runtime input access, computes library metadata, and emits sandbox code for Workflow V3 execution. The handler return type becomes the `CodeNodeHandle` output type, so downstream `paths(codeNode).field` references can autocomplete against that shape.
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | Yes | Display name and fallback node identity. Must be non-empty. |
+| `key` | `string` | No | Stable identity when `name` may change. |
+| `handler` | `CodeHandler` | Yes | Runtime function. Receives `ref()` and `paths()` helpers for workflow inputs and prior nodes. |
+| `libraries` | `readonly string[]` | No | Explicit sandbox package specs such as `zod@4.3.6`. User specs win over inferred package versions. |
+
+```ts
+const normalizeInvoice = code({
+    name: 'Normalize invoice',
+    key: 'normalize_invoice',
+    libraries: ['zod@4.3.6'],
+    handler: ({ ref, paths }) => {
+        const vendor = ref(extractInvoice, paths(extractInvoice).vendor)
+        const total = Number(ref(extractInvoice, paths(extractInvoice).total))
+
+        return {
+            vendor: String(vendor).trim(),
+            totalCents: Math.round(total * 100),
+            needsHumanReview: total > 10_000,
+        }
+    },
+})
+```
+
+Supported extraction patterns:
+
+- Inline handlers or named top-level handler functions.
+- Source-visible same-file helpers, constants, types, and classes.
+- Supported local TypeScript imports that can be copied into the source bundle.
+- Package imports preserved in generated source with versions resolved from lockfile/package metadata or `libraries`.
+
+Avoid these patterns:
+
+- Dynamic import specifiers.
+- Runtime-created closure values that cannot be statically traced.
+- Unsupported local imports or unresolved exports.
+- Forward references to later nodes.
+- Declaring generated-reserved names such as `execute` or `TelaInput` in extracted handler/helper/type code.
+
+### Config and shared types
+
+These types are exported for config files and integrations. See [Config](/docs/config) for full examples.
+
+| Type | Shape | Purpose |
+| --- | --- | --- |
+| `WorkflowCodeConfig` | `{ version: 1; tsconfig?: string; outDir?: string; workflows: Record<string, WorkflowTarget> }` | Top-level `workflow-code.config.ts` default export shape. |
+| `WorkflowTarget` | `{ entry: string; contexts?: Record<string, WorkflowContextBinding>; projectId?: string; export?: 'default'; promptId?: string; workflowKey?: string; title?: string }` | Per-target entrypoint and remote binding metadata. |
+| `WorkflowContextBinding` | `{ projectId?: string; promptId?: string }` | Context-specific project/prompt ids selected by Tela Dock/CLI context. Required only by remote lifecycle commands such as `sync`. |
+| `Diagnostic` | `{ code: string; severity: 'error' \| 'warning' \| 'info'; message: string; hint?: string; location?: { file: string; line?: number; column?: number; offset?: number; endOffset?: number }; stack?: string }` | Compiler and loader diagnostic payload. |
+
+### Diagnostics checklist
+
+When authoring fails, check these first:
+
+- Empty `workflowKey`, input `name`, node `name`, or prompt output.
+- Missing default export from the workflow entrypoint.
+- `workflowKey` mismatch between source and config.
+- `ref()` to a node that appears later in `nodes`.
+- `paths()` token from one node passed to `ref()` for another node.
+- `code()` handler uses unsupported closures, dynamic imports, unresolved local imports, or generated-reserved names.
+- Package import version cannot be resolved from lockfile, installed package, package.json, or `libraries` override.