@meistrari/tela-cli 0.7.58 → 0.8.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,434 @@
+## 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,
+    code,
+    input,
+    llm,
+    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. |
+| [`agent()`](#agentoptions) | Multi-round reasoning, tool use, Tela tools, or external skills. |
+| [`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, 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 review = agent({
+    name: 'Review outline',
+    input: {
+        maxRounds: 8,
+        prompt: ({ ref, paths }) => [
+            'Review this outline for a new Tela user.',
+            `Bullets: ${ref(outline, paths(outline).bullets).formats().format}`,
+        ].join('\n'),
+    },
+})
+
+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.
+
+
+### 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 = agent({
+    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' },
+                },
+            },
+        },
+    },
+})
+```
+
+### `agent(options)`
+
+```ts
+type AgentOptions = {
+    name: string
+    key?: string
+    input: {
+        prompt: string | ((context: PromptFactoryContext) => string)
+        model?: string
+        maxRounds?: number
+        tools?: AgentToolOptions
+    }
+    schema?: WorkflowCodeOutputSchema | null
+}
+
+function agent(options: AgentOptions): AgentNodeDeclaration
+```
+
+Declares an agent node. Use `agent()` when the step may need iteration, tool calls, Tela tools, or broader reasoning than a single completion.
+
+| 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 | Agent instruction. Callback form enables `ref()` and `paths()`. Must render to non-empty string. |
+| `input.model` | `string` | No | Agent model id passed through to Workflow V3. |
+| `input.maxRounds` | `number` | No | Maximum reasoning/tool-use rounds. |
+| `input.tools` | `AgentToolOptions` | No | Built-in or platform tool options accepted by Workflow V3. |
+| `schema` | `WorkflowCodeOutputSchema \| null` | No | Structured output fields for the agent result. 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` gives the agent an explicit result contract after reasoning/tool use and creates fields that downstream nodes can reference with `paths()`. Keep fields small and explicit: use `type`, `description`, `enum`, `properties`, `items`, and `required` when useful.
+
+```ts
+const reviewInvoice = agent({
+    name: 'Review invoice extraction',
+    key: 'review_invoice',
+    input: {
+        maxRounds: 6,
+        prompt: ({ ref, paths }) => [
+            'Review extracted invoice data for missing or suspicious fields.',
+            `Vendor: ${ref(extractInvoice, paths(extractInvoice).vendor).formats().format}`,
+            `Total: ${ref(extractInvoice, paths(extractInvoice).total).formats().format}`,
+        ].join('\n'),
+    },
+    schema: {
+        approved: { type: 'boolean' },
+        notes: { type: 'array', items: { type: 'string' } },
+    },
+})
+```
+
+Choose `agent()` over `llm()` when the workflow step needs investigation, retries, tools, or judgment across multiple pieces of context.
+
+### `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.

package/dist/docs/workflow-code/cli.md

@@ -0,0 +1,187 @@
+## CLI
+
+The workflow command group documents implemented `init`, `compile`, `docs`, `sync`, and `publish` workflows. Current MVP behavior is local-first until you run explicit remote lifecycle commands such as `sync` or `publish`.
+
+### Command surface
+
+| Command | Status | Remote mutation | Purpose |
+| --- | --- | --- | --- |
+| `init [--directory <path>] [--config <path>] [--workflow <key>...] [--yes] [--init-git\|--no-init-git] [--install-deps\|--no-install-deps] [--package-manager bun\|pnpm\|npm\|yarn] [--json]` | Implemented | No | Create local Workflow Code scaffold. |
+| `compile [target] [--config <path>] [--env <path>] [--json]` | Implemented | No | Compile selected source into Workflow V3 output. |
+| `docs [page] [--json]` | Implemented | No | Read the version-matched Workflow Code documentation bundled with the installed CLI. |
+| `sync [target] [--config <path>] [--env <path>] [--yes] [--json]` | Implemented | Yes | Synchronize local compiled workflow(s) with configured Tela prompt(s). |
+| `publish [target] [--environment <name>] [--create-environment-if-missing] [--config <path>] [--env <path>] [--yes] [--json]` | Implemented | Yes | Publish local-matching workflow version(s) to the selected workflow environment. |
+
+### Target selection
+
+The positional target is the key inside `workflow-code.config.ts` `workflows`. If `compile` sees exactly one configured workflow, the target may be omitted. If multiple workflows exist, `compile` requires a target. `sync` and `publish` use the same target key; when the target is omitted, they run every configured workflow. For publish, `--environment <name>` selects the workflow publication environment and is independent from the active Tela Local context. `--env <path>` remains a dotenv loader.
+
+```bash
+tela workflow compile
+tela workflow compile invoice-processing
+tela workflow compile invoice-processing --env .env.staging --json
+tela workflow docs cli
+tela workflow sync
+tela workflow sync invoice-processing --env .env.staging --json
+tela workflow publish
+tela workflow publish invoice-processing --environment staging --json
+```
+
+### init
+
+**Description.** `tela workflow init` scaffolds a local Workflow Code project. It is local-only: it does not contact Tela APIs, create remote resources, write lockfiles, emit generated artifacts, or print environment values.
+
+Init creates the target directory when needed, then writes a safe starter project:
+
+- `workflow-code.config.ts` with `tsconfig: './tsconfig.json'`, `outDir: '.tela/workflows'`, and a `workflows` map.
+- `src/workflows/<key>.workflow.ts` for each workflow key passed with `--workflow <key>` or entered interactively.
+- `.env.example` with placeholder project and prompt variables for generated workflow targets.
+- `tsconfig.json` when missing.
+- `package.json` updates for `@meistrari/workflow-code` and missing `workflow:*` scripts.
+- `.gitignore` entry for `.tela/workflows/*/contexts/dev/lock.json`.
+
+Existing files and package scripts are preserved by default. Conflicts become diagnostics and `--json` reports written paths, skipped paths, skipped scripts, and setup actions.
+
+Interactive init prompts in this order: target directory, workflow keys, git initialization, dependency installation, then package manager when installation is enabled. Defaults are safe: current directory, no workflow keys, no git init, no dependency install, and Bun when a package manager is needed. `--yes` answers non-interactive prompts with those safe defaults while still honoring explicit flags such as `--workflow`, `--directory`, or `--install-deps`.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `--directory <path>` | Flag | No | Target directory to initialize. Defaults to `.` and is created when missing. |
+| `--config <path>` | Flag | No | Config file path to create inside the target directory. Defaults to `workflow-code.config.ts`. |
+| `--workflow <key>` | Flag | No | Add a workflow target and source file. Repeat for multiple workflows. Keys must be safe file names. |
+| `--yes` | Flag | No | Disable prompts and use safe defaults for unspecified choices. |
+| `--init-git` / `--no-init-git` | Flag | No | Create or skip a git repository when the target directory is not already inside one. |
+| `--install-deps` / `--no-install-deps` | Flag | No | Install Workflow Code dependencies. If `package.json` is missing, init runs the selected package manager's non-interactive init first. |
+| `--package-manager bun|pnpm|npm|yarn` | Flag | No | Package manager for dependency installation. Defaults to Bun. |
+| `--json` | Flag | No | Emit the result envelope, diagnostics, scaffold paths, skipped scripts, and setup actions as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow init
+tela workflow init --directory ./workflow-app --workflow invoice-processing --workflow review
+tela workflow init --install-deps --package-manager pnpm --yes
+tela workflow init --workflow invoice-processing --yes --json
+```
+
+
+
+### compile
+
+**Description.** `tela workflow compile` loads config, loads dotenv files, evaluates the TypeScript entrypoint, validates declarations, and returns deterministic Workflow V3 graph, payload, hashes, and diagnostics. It does not require or validate remote `projectId`/`promptId`, write lockfiles, sync remote content, or publish.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `target` | Positional | No | Config `workflows` key to compile. Required when more than one workflow is configured. |
+| `--config <path>` | Flag | No | Load a custom config file instead of `workflow-code.config.ts`. |
+| `--env <path>` | Flag | No | Load a custom dotenv file before evaluating config. |
+| `--json` | Flag | No | Emit compiled graph, payload, hashes, and diagnostics as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow compile
+tela workflow compile invoice-processing
+tela workflow compile invoice-processing --env .env.staging --json
+tela workflow compile --config ./workflow-code.config.ts
+```
+
+### docs
+
+**Description.** `tela workflow docs` reads the official Workflow Code documentation bundled with the installed CLI. It is local-only, performs no network requests, and reports the Workflow Code package version represented by the bundle.
+
+Omit the page to list the available documentation. Pass a page slug to print its Markdown content. JSON output includes the package version, source package, and either the page catalog or selected page content.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `page` | Positional | No | Bundled documentation page such as `cli`, `config`, or `api-reference`. |
+| `--json` | Flag | No | Emit bundle provenance, package version, and page metadata or content as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow docs
+tela workflow docs cli
+tela workflow docs api-reference --json
+```
+
+### sync
+
+**Description.** `tela workflow sync` compiles local source, resolves the active Tela Local context, selects the matching `projectId` and `promptId`, verifies remote content, and writes per-context lockfile state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`.
+
+Sync uses a consolidated version strategy. The compiled workflow becomes the complete source of truth for the next remote version: source files, hashes, lifecycle payload, package metadata, and binding metadata are consolidated into one prompt version snapshot. When compiled content changed, sync creates a new non-draft version. The only exception is a verified no-op: if local hashes already match the active-context lockfile and fresh remote content confirms the same version, sync returns without creating a version.
+
+Consolidated versions make sync safe to repeat. A sync never edits an existing version in place, never mutates a draft, and never changes the previous consolidated version. If the workflow is currently pointing at a draft version, sync leaves that draft untouched and creates a new consolidated non-draft version for the compiled workflow instead.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `target` | Positional | No | Config `workflows` key to sync. Omit to sync every configured workflow. |
+| `--config <path>` | Flag | No | Load a custom config file instead of `workflow-code.config.ts`. |
+| `--env <path>` | Flag | No | Load a custom dotenv file before evaluating config. |
+| `--yes` | Flag | No | Continue non-interactively when remote content changed since the last successful sync. |
+| `--json` | Flag | No | Emit selected workflows, sync status, remote version ids, lockfile paths, compiled payloads, and diagnostics as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow sync
+tela workflow sync invoice-processing
+tela workflow sync invoice-processing --env .env.staging --yes --json
+```
+
+**Example: local source changes after review.** You update `src/invoice.workflow.ts`, run `compile`, review the payload, then run `tela workflow sync invoice-processing`. Sync creates a new non-draft consolidated version that contains the compiled workflow and updates the active-context lockfile to that version.
+
+**Example: active remote workflow is a draft.** A teammate is experimenting in Tela and the current workflow points at a draft version. Running `tela workflow sync invoice-processing` does not overwrite or publish that draft. Sync creates a new consolidated non-draft version from local source and records that new version in the lockfile; the former draft version remains available as it was.
+
+**Example: no local changes.** CI runs `tela workflow sync --yes --json` after a previous successful sync. If local hashes match the lockfile and the remote snapshot still matches, sync returns a no-op and does not create another version.
+
+
+
+### publish
+
+**Description.** `tela workflow publish` releases only remote versions proven to match local compiled source. It uses shared Tela CLI authentication and the active Tela Local context to resolve each workflow's configured `projectId` and `promptId`. If the current remote version cannot be proven to match the local hashes and synced lineage, publish runs sync internally for that workflow before continuing. A matching draft is consolidated before publication; publish does not create an unrelated workflow version.
+
+`--environment <name>` selects the workflow publication environment for every selected workflow and defaults to `production`. Before changing any workflow version, publish resolves that environment and its current remote version for every selected workflow. If a custom environment is missing in an interactive terminal, publish shows its exact name and affected workflows, then asks once whether to create it; the default answer is no. In `--json` or another non-interactive execution, pass `--create-environment-if-missing` to authorize creation explicitly. `--yes` remains limited to remote-divergence handling during the sync lifecycle. These flags do not change the Tela Local context, API endpoint, workspace, or credentials. `--env <path>` only loads dotenv values used by config and workflow source.
+
+Publish does not store publication state in the Workflow Code lockfile; Tela's environment state remains authoritative. The lockfile changes only when publish needs to run sync internally first.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `target` | Positional | No | Config `workflows` key to publish. Omit to publish every configured workflow. |
+| `--environment <name>` | Flag | No | Workflow publication environment. Defaults to `production`. |
+| `--create-environment-if-missing` | Flag | No | Create the selected custom environment when absent. Required for non-interactive creation. |
+| `--config <path>` | Flag | No | Load a custom config file instead of `workflow-code.config.ts`. |
+| `--env <path>` | Flag | No | Load a custom dotenv file before evaluating config. |
+| `--yes` | Flag | No | Continue non-interactively if the sync performed by publish detects remote divergence. |
+| `--json` | Flag | No | Emit selected workflow, context, and environment identities, version ids, hashes, diagnostics, and written paths as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow publish
+tela workflow publish invoice-processing
+tela workflow publish invoice-processing --environment staging
+tela workflow publish invoice-processing --environment dev --create-environment-if-missing --json
+tela workflow publish --environment production --yes --json
+```
+
+
+
+### JSON diagnostics
+
+```ts
+type Diagnostic = Readonly<{
+    code: string
+    severity: 'error' | 'warning' | 'info'
+    message: string
+    hint?: string
+    location?: {
+        file: string
+        line?: number
+        column?: number
+        offset?: number
+        endOffset?: number
+    }
+    stack?: string
+}>
+```