@meistrari/tela-cli 0.7.58 → 1.0.0

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

@@ -0,0 +1,210 @@
+## CLI
+
+The workflow command group documents implemented `init`, `compile`, `docs`, `codegen`, `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. |
+| `codegen [--json]` | Implemented | No | Refresh or reuse the active-context remote catalog and generate remote() TypeScript metadata. |
+| `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 codegen --json
+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
+```
+
+### codegen
+
+`codegen [--json]`
+
+**Description.** `tela workflow codegen` resolves the active Tela Local context and workspace, refreshes the authenticated remote catalog, and writes TypeScript metadata for inert `remote()` authoring. It writes the generated augmentation at `.tela/workflow-code/generated/workflow-code.generated.d.ts` and the complete context/workspace snapshot at `.tela/workflow-code/catalogs/<workspaceId>/remote-catalog.snapshot.json`. The catalog includes canvases, workflows, templates, published agents, and models; only canvases, workflows, published agents, and models are projected by `remote()`.
+
+Codegen fetches a fresh snapshot when possible. If refresh fails, it may reuse only a complete cached snapshot for the same active context and workspace, reports warning diagnostics, and repairs or skips artifacts deterministically. If neither refresh nor a matching snapshot is available, it fails without inventing catalog bindings. Generated files are non-secret typechecking and orchestration metadata; include the generated declaration path in TypeScript's `include` configuration when needed.
+
+`compile` remains offline and preserves symbolic remote refs. `sync` refreshes and validates catalog references and locks before resolved lowering and remote mutation.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `--json` | Flag | No | Emit command, active context/workspace, metadata source/hash/timestamps, written paths, skipped paths, and diagnostics as JSON. |
+
+**Examples.**
+
+```bash
+tela workflow codegen
+tela workflow codegen --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
+}>
+```

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

@@ -0,0 +1,69 @@
+## Config
+
+`workflow-code.config.ts` selects workflow targets, TypeScript entrypoints used by `compile`, and remote prompt bindings used by `sync`. The config is evaluated after dotenv loading, so `process.env` is available.
+
+### Basic shape
+
+```ts
+import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
+
+export default {
+    version: 1,
+    workflows: {
+        demo: {
+            entry: './src/workflows/demo.workflow.ts',
+            projectId: process.env.TELA_PROJECT_ID,
+            promptId: process.env.TELA_WORKFLOW_PROMPT_ID,
+            workflowKey: 'first-workflow',
+            contexts: {
+                development: {
+                    projectId: process.env.TELA_DEV_PROJECT_ID ?? process.env.TELA_PROJECT_ID!,
+                    promptId: process.env.TELA_DEV_PROMPT_ID,
+                },
+            },
+        },
+    },
+} satisfies WorkflowCodeConfig
+```
+
+### Config properties
+
+| Property | Required | Purpose |
+| --- | --- | --- |
+| `version` | Yes | Must be `1`. |
+| `workflows` | Yes | Map from CLI target name to workflow target. |
+| `tsconfig` | No | Optional TypeScript config path for source evaluation. |
+| `outDir` | No | Output directory for generated workflow artifacts. |
+
+### Workflow target properties
+
+| Property | Required | Purpose |
+| --- | --- | --- |
+| `entry` | Yes | Path to the workflow TypeScript entrypoint. |
+| `projectId` | No | Default Tela project id for remote lifecycle commands; not required by compile. |
+| `promptId` | No | Existing Tela prompt or workflow id for remote lifecycle commands; not required by compile. |
+| `workflowKey` | No | Expected source workflow key; compile reports an error if it disagrees with `workflow(...)`. |
+| `title` | No | Human title used by compiler metadata. |
+| `contexts` | No | Map of context name to `projectId` and `promptId` overrides for remote lifecycle commands. |
+
+### Environment variables
+
+Use `.env` files for ids that differ by workspace or deployment.
+
+```bash
+TELA_PROJECT_ID=proj_default
+TELA_WORKFLOW_PROMPT_ID=prompt_default
+TELA_DEV_PROJECT_ID=proj_development
+TELA_DEV_PROMPT_ID=prompt_development
+```
+
+Use `tela workflow compile --env .env.staging --json` to validate local workflow source. `compile` does not require or validate `projectId`/`promptId`; use `tela workflow sync demo --env .env.staging --json` when remote bindings are available. Do not print secrets or store credentials in workflow source.
+
+### Contexts
+
+Contexts can mirror Tela Dock contexts for environment-specific ids. `compile` remains local validation. `sync` resolves the active Tela Local context, chooses the matching `contexts[...]` binding, requires both `projectId` and `promptId`, and writes state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`.
+
+```bash
+tela context current --json
+tela context list --json
+```

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

@@ -0,0 +1,56 @@
+## Guides
+
+These guides collect practical conventions for source layout, CI validation, and diagnostic workflows.
+
+### Suggested scaffold
+
+Start with a small source tree that separates workflow declarations, prompt text, and shared utilities.
+
+
+
+```bash
+workflow-code.config.ts
+.env.example
+src/workflows/demo.workflow.ts
+src/workflows/prompts.ts
+src/workflows/shared.ts
+```
+
+
+
+| Path | Purpose |
+| --- | --- |
+| `workflow-code.config.ts` | Typed workflow targets and context bindings. |
+| `.env.example` | Document required project and prompt ids. |
+| `src/workflows/demo.workflow.ts` | Default-exported `build(workflow(...))` declaration. |
+| `src/workflows/prompts.ts` | Prompt strings and small prompt helpers. |
+| `src/workflows/shared.ts` | Pure utilities reused by declarations or code handlers. |
+
+### CI compile check
+
+Use `compile --json` in CI to validate source and fail on error diagnostics before any remote lifecycle command runs.
+
+```bash
+set -euo pipefail
+pnpm install --frozen-lockfile
+pnpm exec tela workflow compile demo --env .env.ci --json > .tela/compile-result.json
+node -e "const r=require('./.tela/compile-result.json'); if (r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
+```
+
+For trusted release jobs with Tela credentials, run sync after compile:
+
+```bash
+pnpm exec tela workflow sync --env .env.ci --yes --json > .tela/sync-result.json
+node -e "const r=require('./.tela/sync-result.json'); if (r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
+```
+
+Commit stable context lockfiles such as `.tela/workflows/*/contexts/*/lock.json` when they represent reviewed remote sync state.
+
+### Troubleshooting diagnostics
+
+When `compile` or `sync` fails, read diagnostic `code` and `hint` first. Most failures point to config shape, missing env files, unresolved entry paths, invalid references, `workflowKey` mismatches, unsupported `code()` extraction patterns, missing `promptId`, active-context binding mismatches, or remote divergence.
+
+- Use `tela workflow compile --json` for declaration and graph diagnostics.
+- Use `tela context current --json` when `sync` selects an unexpected context binding.
+- Pass `--yes` only in trusted non-interactive jobs where consolidating a newer remote version is expected.
+- Keep code handlers source-visible and avoid dynamic imports, runtime-created closure values, and reserved generated names.

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

@@ -0,0 +1,33 @@
+## Installation
+
+Workflow Code uses the `tela workflow` command group from `@meistrari/tela-cli` and the authoring/compiler package `@meistrari/workflow-code` in the repository that owns workflow source.
+
+### CLI through Tela Dock
+
+Tela Dock is the recommended source for CLI setup. It manages account login, workspace or environment context, updates, and shared local configuration used by workflow commands.
+
+```bash
+tela whoami --pretty
+tela workflow help
+```
+
+Use Dock for login and context switching instead of workflow-specific token files. Dock and CLI share local context metadata through `@meistrari/tela-local-config`; credential material remains in the OS keychain (macOS Keychain, or the Linux freedesktop Secret Service via `secret-tool`) or environment credential adapters.
+
+### Repository package
+
+Install the authoring and compiler package where workflow source lives.
+
+```bash
+pnpm add -D @meistrari/workflow-code @meistrari/tela-cli
+```
+
+Use package scripts or `pnpm exec` to invoke `tela workflow` from CI. The public workflow source imports only `@meistrari/workflow-code`.
+
+### Verification
+
+Run these checks before writing workflow source:
+
+- `tela whoami --pretty` confirms the authenticated account.
+- `tela context current --json` confirms the active local context.
+- `tela workflow help` confirms the workflow command group is routed.
+- `pnpm list @meistrari/workflow-code` confirms the authoring package is installed in the repository.

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

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@meistrari/workflow-code",
+  "packageVersion": "0.0.0",
+  "sourcePackage": "@meistrari/workflow-code-page",
+  "pages": [
+    {
+      "slug": "overview",
+      "title": "Documentation overview",
+      "file": "overview.md",
+      "sha256": "88c838262048260cee280cdd8d16e9987847bcf06b857ca6d2cf0b707c4b15fe"
+    },
+    {
+      "slug": "api-reference",
+      "title": "API Reference",
+      "file": "api-reference.md",
+      "sha256": "2306f6a21d23b4e3457262c3105e65e0292af5a59154aa15cf24188409db07f8"
+    },
+    {
+      "slug": "cli",
+      "title": "CLI",
+      "file": "cli.md",
+      "sha256": "759db330fd7b06859e55404f01feb0625a43bb579324fe011bc34cd92d517239"
+    },
+    {
+      "slug": "config",
+      "title": "Config",
+      "file": "config.md",
+      "sha256": "b07b91f46b4ab9a3850df58a0dec388c670771be6de0a5cf3bafd989135fe306"
+    },
+    {
+      "slug": "guides",
+      "title": "Guides",
+      "file": "guides.md",
+      "sha256": "b3f2ff1ac03f3829b6c5614ecc61229e181179dd2506684fae073075748359cb"
+    },
+    {
+      "slug": "installation",
+      "title": "Installation",
+      "file": "installation.md",
+      "sha256": "e20f15e52c519580a8260748195a3ec8f149ac15d8beb79d06bb401a5f639500"
+    },
+    {
+      "slug": "quick-start",
+      "title": "Quick start",
+      "file": "quick-start.md",
+      "sha256": "15f4b45bd6292c4dd3f3ff5fc58f46e5e83e55f3a5e4ed9fee0df37fd12b2305"
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+## Documentation overview
+
+Workflow Code documentation is organized as a set of focused pages. Read the pages in order when adopting the package for the first time, or use the sidebar when you need a specific reference.
+
+### Recommended path
+
+| Page | Use it when |
+| --- | --- |
+| [Quick start](/docs/quick-start) | You want the shortest path from `tela workflow init` to local compile and explicit sync. |
+| [Installation](/docs/installation) | You need to verify Tela Dock, the `tela` CLI, or the `@meistrari/workflow-code` package. |
+| [Config](/docs/config) | You are defining `workflow-code.config.ts`, dotenv files, target ids, or context-specific bindings. |
+| [CLI](/docs/cli) | You need implemented init/compile/docs/codegen/sync/publish behavior, target selection rules, generated catalog refresh, or JSON diagnostics. |
+| [API Reference](/docs/api-reference) | You are authoring `workflow()`, `build()`, `input`, `llm`, `agent`, `code`, references, remote catalogs, and executable remote refs. |
+| [Guides](/docs/guides) | You want repository layout, CI compile checks, and troubleshooting patterns. |

package/dist/docs/workflow-code/quick-start.md

@@ -0,0 +1,124 @@
+## Quick start
+
+This page assumes Tela Dock already installed and authenticated the `tela` CLI. Use [Installation](/docs/installation) only when the command is unavailable or the account context is not configured.
+
+### Verify the CLI
+
+```bash
+tela whoami --pretty
+tela workflow help
+```
+
+`compile` is a local validation step. It does not create, sync, publish, or run remote workflows. `sync` writes compiled versions to configured Tela prompts, while `publish` releases a local-matching version to a workflow publication environment.
+
+### Initialize local scaffold
+
+```bash
+tela workflow init
+```
+
+`init` creates safe starter files and package scripts, reports skipped existing files, and does not call Tela APIs.
+
+### Add a minimal config
+
+```ts
+import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
+
+export default {
+    version: 1,
+    workflows: {
+        demo: {
+            entry: './src/workflows/demo.workflow.ts',
+            projectId: process.env.TELA_PROJECT_ID,
+            promptId: process.env.TELA_WORKFLOW_PROMPT_ID,
+            contexts: {
+                development: {
+                    projectId: process.env.TELA_DEV_PROJECT_ID ?? process.env.TELA_PROJECT_ID!,
+                    promptId: process.env.TELA_DEV_PROMPT_ID,
+                },
+            },
+        },
+    },
+} satisfies WorkflowCodeConfig
+```
+
+Keep the first config small: one target, one entrypoint, and environment-backed ids. Context-specific ids can override defaults when Tela Dock switches contexts.
+
+### Author a workflow
+
+```ts
+import { agent, build, code, input, llm, remote, workflow } from '@meistrari/workflow-code'
+
+const topic = input.text({
+    name: 'topic',
+    required: true,
+    description: 'Topic the workflow should explain.',
+})
+
+const outline = llm({
+    name: 'Draft outline',
+    input: {
+        temperature: 0.2,
+        prompt: ({ ref }) => `Create a concise outline about ${ref(topic).formats().raw}.`,
+    },
+    schema: {
+        bullets: { type: 'array', items: { type: 'string' } },
+    },
+})
+
+const countBullets = code({
+    name: 'Count bullets',
+    handler: ({ ref, paths }) => {
+        const bullets = ref(outline, paths(outline).bullets) as string[]
+        return {
+            count: bullets.length,
+            firstBullet: bullets[0] ?? null,
+        }
+    },
+})
+
+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().json}`,
+            `Bullet count: ${ref(countBullets, paths(countBullets).count).formats().json}`,
+        ].join('\n'),
+        inputs: {},
+    },
+})
+
+export default build(workflow('first-workflow'), {
+    inputs: [topic],
+    nodes: [outline, countBullets, review],
+})
+```
+
+Workflow source is an inert TypeScript declaration. `build(workflow(...), { inputs, nodes })` is the default export read by `compile`. The `code()` handler is not run during compile; compile extracts supported source and lowers it into sandbox code for Workflow runtime execution.
+
+### Compile
+
+```bash
+tela workflow compile demo --json
+```
+
+Use `compile` to validate source and inspect deterministic graph, compiler payload, hashes, and diagnostics.
+
+### Sync
+
+```bash
+tela workflow sync demo --json
+```
+
+Use `sync` after review to write the compiled workflow to the configured Tela prompt for the active Tela context. Omit `demo` to sync every configured workflow. If remote content changed since the last successful sync, the CLI asks before consolidating a new version; pass `--yes` for non-interactive CI.
+
+### Publish
+
+```bash
+tela workflow publish demo --environment production --json
+```
+
+Use `publish` to release the exact version proven to match local compiled source. `production` is the default. When a selected custom environment does not exist, interactive publish asks whether to create it and defaults to no; non-interactive commands must add `--create-environment-if-missing`. The `--environment` flag selects the workflow publication environment; Tela authentication, workspace, and context still come from shared Tela Local state. Publish can perform its own sync when required, but keeping sync explicit in this quick-start flow preserves a clear review boundary before release.