@meistrari/tela-cli 1.4.0 → 1.6.0

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

@@ -16,11 +16,13 @@ import {
     code,
     crop,
     docTemplate,
+    condition,
     input,
     llm,
     splitter,
     vault,
     remote,
+    stop,
     workflow,
 } from '@meistrari/workflow-code'
 import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
@@ -43,6 +45,8 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`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. |
+| [`condition()`](#conditionoptions) | Synchronous predicate branches with compiler-owned V3 branch ports. |
+| [`stop()`](#stop) | Terminal leaf allowed only as the final direct node of a condition branch. |
 | [`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 })`.
@@ -177,6 +181,7 @@ const normalizeInvoice = code({
 Reference rules:
 
 - References in node inputs may target workflow inputs or earlier nodes.
+- `condition()` and `stop()` are compiler-owned topology nodes and do not produce output references.
 - `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`.
@@ -743,6 +748,38 @@ Avoid these patterns:
 - Forward references to later nodes.
 - Declaring generated-reserved names such as `execute` or `TelaInput` in extracted handler/helper/type code.
 
+### `condition(options)`
+
+```ts
+const route = condition({
+    cases: {
+        approved: {
+            when: ({ ref, paths }) =>
+                ref(classify, paths(classify).status) === 'approved',
+            nodes: [approveInvoice],
+        },
+    },
+    default: { nodes: [manualReview] },
+})
+```
+
+Declares a Workflow V3 condition. `cases` are evaluated in authored object insertion order; array-index names like `"0"` are rejected. Each named case has a synchronous boolean `when` predicate and ordered branch `nodes`. The optional `default` has only `nodes`.
+
+The compiler extracts predicate source without executing it, copies supported source-visible helpers and local imports, rewrites `ref()` reads to runtime inputs, and emits guarded JavaScript for the V3 condition action. V3 `steps`, branch `portId`s, node IDs, and graph edges are always compiler-owned.
+
+### `stop()`
+
+```ts
+const route = condition({
+    cases: {
+        duplicate: { when: () => true, nodes: [stop()] },
+    },
+    default: { nodes: [continueProcessing] },
+})
+```
+
+Declares a terminal Workflow V3 stop node. It is valid only as the final direct node in a `condition()` case or default branch. A stopped branch does not converge to the next node; normal and empty sibling branches still converge. `stop()` at the workflow root, inside a map body, or before another direct branch node reports `compiler.stop.invalid_placement`.
+
 ### Config and shared types
 
 These types are exported for config files and integrations. See [Config](/docs/config) for full examples.

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

@@ -1,6 +1,6 @@
 ## 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`.
+The workflow command group documents implemented `init`, `create`, `compile`, `docs`, `codegen`, `sync`, and `publish` workflows. Current MVP behavior is local-first until you run an explicit remote lifecycle command such as `create`, `sync`, or `publish`.
 
 ### Command surface
 
@@ -10,12 +10,13 @@ The workflow command group documents implemented `init`, `compile`, `docs`, `cod
 | `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. |
+| `create <target> [--project <project-id>] [--config <path>] [--env <path>] [--json]` | Implemented | Yes | Provision a remote workflow, bind it to the active context, scaffold source, and sync when possible. |
 | `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.
+The positional target is the key inside `workflow-code.config.ts` `workflows`. `create` always requires exactly one target. If `compile` sees exactly one configured workflow, the target may be omitted; with multiple workflows it is required. `sync` and `publish` use the same target key and run every configured workflow when it is omitted. For publish, `--environment <name>` selects the workflow publication environment and is independent from the active Tela Local context. `--env <path>` remains scoped to dotenv-backed config/source evaluation and does not select the remote Tela context.
 
 ```bash
 tela workflow compile
@@ -23,6 +24,7 @@ tela workflow compile invoice-processing
 tela workflow compile invoice-processing --env .env.staging --json
 tela workflow docs cli
 tela workflow codegen --json
+tela workflow create invoice-processing --project proj_123 --json
 tela workflow sync
 tela workflow sync invoice-processing --env .env.staging --json
 tela workflow publish
@@ -72,6 +74,8 @@ tela workflow init --workflow invoice-processing --yes --json
 
 **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.
 
+`compile` stays offline. For a workflow that declares `vault.asset()`, it can lower the asset only when the active-context lockfile already contains the matching uploaded `vault://...` ref. Otherwise it reports `vault.asset.missing_lock`. Compile never reads the asset file, uploads it, refreshes the lock, or contacts Vault; run `sync` first to create or refresh that lock.
+
 | Prop | Type | Required | Description |
 |---|---|---:|---|
 | `target` | Positional | No | Config `workflows` key to compile. Required when more than one workflow is configured. |
@@ -132,6 +136,8 @@ tela workflow codegen --json
 
 **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`.
 
+For `vault.asset()` declarations, sync validates that each local path is a regular file within the project directory, hashes its content, and reuses a matching active-context asset lock when possible. New or changed assets are uploaded and recorded as `vault://...` refs before sync performs its final resolved compilation or any workflow lifecycle mutation. This makes later offline `compile` runs deterministic; a changed asset is uploaded again on the next sync.
+
 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.
@@ -158,7 +164,37 @@ tela workflow sync invoice-processing --env .env.staging --yes --json
 
 **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.
 
+### create
+
+**Description.** `tela workflow create <target>` explicitly creates a remote Tela workflow, binds the returned prompt identity under `workflows[target]` for the active Tela Local context, scaffolds source, and runs the normal sync lifecycle when its prerequisites are available. It is never called by `init` and never publishes.
+
+Create resolves credentials, API endpoint, workspace, and active context through shared Tela Local config/auth. The project is taken from the target's active context binding (or a legacy top-level target binding when no `contexts` map exists). For a new target or missing active binding, pass `--project <project-id>`; create deliberately does not infer a project from the workspace or another workflow.
+
+The command preflights config/source safety and compilation, then performs changes in this order: remote creation, config binding, source scaffold, config-loader verification, and best-effort sync. Before `/prompt`, create reuses sync's context-bound remote-reference preparation: it refreshes and validates used `remote()` references, recompiles them to concrete resource IDs, and authenticates direct Vault references. Immediately before the POST, it reloads the source and transitive local imports, reapplies the prepared remote snapshot, and requires the same source and compiled hashes. Preparation failures, `create.source.snapshot_changed`, or unresolved `$workflowCodeRemote` markers stop without creating a workflow. A target already bound to a `promptId` also fails before remote creation; use `sync` for that workflow.
+
+Create canonicalizes the config identity through symlinked parent directories without following a final config symlink. The stable remote idempotency key is derived from that canonical config, target, active context, workspace, and project, so path aliases and retries replay the same logical creation. Target selection, project, source entry, and config edits come from one immutable loader snapshot; a changed snapshot reports `create.config.snapshot_changed` before `/prompt`. Config object spreads, computed properties, or duplicate mutation-path properties that could make the edited syntax differ from the evaluated binding are rejected before remote creation.
+
+The successful API response is untrusted: it must contain a non-empty prompt `id`, bootstrap `version.id`, `projectId`, and `workspaceId`, with project/workspace matching the request. Create validates those returned identities without additional prompt/version reads; complete representation validation is deferred until the create endpoint returns those fields. If Tela returns a valid prompt id but an absent or malformed bootstrap version identity, create exits non-zero before local writes/sync while preserving `promptId` and the create idempotency key; JSON reports `bootstrapVersionId: null`. If the POST outcome is unknown and no prompt identity was returned, JSON still reports the attempted idempotency key with `promptId: null`, no local writes, and non-zero exit status so the same logical create can be replayed safely.
+
+Config binding uses an exclusive per-config lock, re-reads the preflight hash while holding that lock, and atomically replaces only the unchanged config. After the scaffold step, create reloads the config and verifies the effective target entry/workflow key plus the exact context/project/prompt binding; `create.config.postcondition_failed` stops before sync if evaluation diverges from what was written. Source paths must remain inside the config root without symlinked components both before remote creation and before writing. Source writes are exclusive: a file that appears after preflight or an existing source that disappears produces `create.source.write_conflict`; create neither overwrites/recreates that content nor syncs it automatically. Existing config entries and validated source files remain preserved by default.
+
+If remote creation succeeds but local work fails, human and JSON output retain the recoverable remote identity plus written/skipped paths. Next actions follow the completed phase: request a manual binding only when the config write failed, describe source repair after a source-write failure, and describe loader or effective-binding repair after config/source were written or preserved. Follow-up sync is pinned to the provisioning context, workspace, project, prompt, and returned bootstrap version. It reads the remote snapshot before editing; if the remote advances past that bootstrap first, `create.sync.bootstrap_version_changed` skips the automatic edit and asks for an explicit sync after review. Only a failure before sync mutation (`preflight`) becomes `sync.status: "skipped"` with warnings; a failure after `mutation_attempted` remains an error, exits non-zero, and exposes pending-sync recovery with lockfile path, idempotency key, and target version id. `published` is always `false`.
 
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `target` | Positional | Yes | Config `workflows` key and local workflow target name to provision. Must not already have a prompt binding in the active context. |
+| `--project <project-id>` | Flag | Conditional | Tela project for a new target or missing active binding. Must match a configured active-binding project when both are present. |
+| `--config <path>` | Flag | No | Load and update a custom config instead of `workflow-code.config.ts`. |
+| `--env <path>` | Flag | No | Load a custom dotenv file before evaluating config. |
+| `--json` | Flag | No | Emit diagnostics, remote identity, active binding, written/skipped paths, sync status, and `published: false`. |
+
+**Examples.**
+
+```bash
+tela workflow create invoice-processing
+tela workflow create invoice-processing --project proj_123
+tela workflow create invoice-processing --project proj_123 --env .env.staging --json
+```
 
 ### publish
 

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

@@ -1,6 +1,6 @@
 ## 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.
+`workflow-code.config.ts` selects workflow targets, TypeScript entrypoints used by `compile`, and active-context project/prompt bindings used by `create`, `sync`, and `publish`. The config is evaluated after dotenv loading, so `process.env` is available.
 
 ### Basic shape
 
@@ -57,11 +57,11 @@ 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.
+Use `tela workflow compile --env .env.staging --json` to validate local workflow source. `compile` does not require or validate `projectId`/`promptId`. Use `tela workflow create demo --project <project-id>` to provision and bind a new remote workflow, or `tela workflow sync demo --env .env.staging --json` when the prompt binding already exists. 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`.
+Contexts can mirror Tela Dock contexts for environment-specific ids. `compile` remains local validation. `create` resolves the active Tela Local context through shared local state, uses that binding's `projectId` (or explicit `--project`), and writes the returned `promptId` into the same binding. `sync` requires both ids there and writes state under `.tela/workflows/<workflowKey>/contexts/<context>/lock.json`. A `TELA_CONTEXT` value loaded through `.env` or `--env` is scoped to config/source evaluation and cannot redirect these remote operations.
 
 ```bash
 tela context current --json

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

@@ -26,6 +26,17 @@ src/workflows/shared.ts
 | `src/workflows/prompts.ts` | Prompt strings and small prompt helpers. |
 | `src/workflows/shared.ts` | Pure utilities reused by declarations or code handlers. |
 
+### Generate remote authoring metadata
+
+Run `codegen` before typechecking workflow source that uses named `remote()` catalog paths. It refreshes the active Tela Local context's catalog and writes the TypeScript augmentation used for remote authoring. `codegen` is workspace-scoped: it does not take a workflow target, load `workflow-code.config.ts`, compile a workflow, or mutate Tela resources.
+
+```bash
+pnpm exec tela workflow codegen --json > .tela/codegen-result.json
+node -e "const r=require('./.tela/codegen-result.json'); if (!r.success || r.diagnostics?.some(d => d.severity === 'error')) process.exit(1)"
+```
+
+With credentials, codegen refreshes the catalog. When that refresh is unavailable, it can use only a complete cached snapshot for the same active context and workspace; inspect its warning diagnostics and `fetchedAt` before relying on the generated names.
+
 ### CI compile check
 
 Use `compile --json` in CI to validate source and fail on error diagnostics before any remote lifecycle command runs.
@@ -37,7 +48,9 @@ pnpm exec tela workflow compile demo --env .env.ci --json > .tela/compile-result
 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:
+`compile` does not upload local `vault.asset()` files. An asset workflow needs an uploaded ref in the active-context lockfile or compile reports `vault.asset.missing_lock`. Do not use a compile-only job to bootstrap those locks.
+
+For trusted release jobs with Tela credentials, run sync. It reuses unchanged asset hashes, uploads new or changed assets, records their Vault refs in the context lockfile, then performs final resolved compilation before the workflow lifecycle mutation:
 
 ```bash
 pnpm exec tela workflow sync --env .env.ci --yes --json > .tela/sync-result.json
@@ -48,9 +61,11 @@ Commit stable context lockfiles such as `.tela/workflows/*/contexts/*/lock.json`
 
 ### 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.
+When `codegen`, `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, Vault asset locks/uploads, or remote divergence.
 
+- Use `tela workflow codegen --json` to refresh remote authoring metadata or inspect matching-context cached-fallback diagnostics.
 - Use `tela workflow compile --json` for declaration and graph diagnostics.
 - Use `tela context current --json` when `sync` selects an unexpected context binding.
+- Run `tela workflow sync` when `compile` reports `vault.asset.missing_lock`; sync uploads and locks the local asset before its final resolved compile.
 - 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/manifest.json

@@ -8,31 +8,31 @@
       "slug": "overview",
       "title": "Documentation overview",
       "file": "overview.md",
-      "sha256": "88c838262048260cee280cdd8d16e9987847bcf06b857ca6d2cf0b707c4b15fe"
+      "sha256": "6209c5b2d8b2d85ca8a084df932e0af9786ff88312f80c59625b47a1d246f307"
     },
     {
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "380cf0c8543400f6fd311936f1b4fb984f12d27b0472213b8a2b431405f0755e"
+      "sha256": "f601e98f0c63812dc0979473c5476b35709f6c8ff70e6de131674503d9cfbe59"
     },
     {
       "slug": "cli",
       "title": "CLI",
       "file": "cli.md",
-      "sha256": "759db330fd7b06859e55404f01feb0625a43bb579324fe011bc34cd92d517239"
+      "sha256": "aaa6b661a7adf7bebcb22a0881e604034886515440468fad7e20c7e5ce3a2e6d"
     },
     {
       "slug": "config",
       "title": "Config",
       "file": "config.md",
-      "sha256": "b07b91f46b4ab9a3850df58a0dec388c670771be6de0a5cf3bafd989135fe306"
+      "sha256": "7a9a70422f2dc8aad5238d6aa0d09a4d635a18e08d264556a35eff5e9efe31f3"
     },
     {
       "slug": "guides",
       "title": "Guides",
       "file": "guides.md",
-      "sha256": "b3f2ff1ac03f3829b6c5614ecc61229e181179dd2506684fae073075748359cb"
+      "sha256": "4109cef4376315b99cbee2d763c927c3148ed889b8602f958fb785faebaf8e03"
     },
     {
       "slug": "installation",
@@ -44,7 +44,7 @@
       "slug": "quick-start",
       "title": "Quick start",
       "file": "quick-start.md",
-      "sha256": "15f4b45bd6292c4dd3f3ff5fc58f46e5e83e55f3a5e4ed9fee0df37fd12b2305"
+      "sha256": "fbb93a9d7ac137a565da232eb145ddab9178d988d6b7d6b218ddd4b735ccb2e2"
     }
   ]
 }

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

@@ -9,6 +9,6 @@ Workflow Code documentation is organized as a set of focused pages. Read the pag
 | [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. |
+| [CLI](/docs/cli) | You need implemented init/create/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

@@ -9,7 +9,7 @@ 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.
+`compile` is a local validation step. It does not create, sync, publish, or run remote workflows. Use the optional `create` command only when this project needs a new remote Tela workflow; an existing remote workflow can be configured and sent directly through `sync`. `publish` releases a local-matching version to a workflow publication environment.
 
 ### Initialize local scaffold
 
@@ -29,6 +29,7 @@ export default {
     workflows: {
         demo: {
             entry: './src/workflows/demo.workflow.ts',
+            workflowKey: 'first-workflow',
             projectId: process.env.TELA_PROJECT_ID,
             promptId: process.env.TELA_WORKFLOW_PROMPT_ID,
             contexts: {
@@ -107,6 +108,16 @@ tela workflow compile demo --json
 
 Use `compile` to validate source and inspect deterministic graph, compiler payload, hashes, and diagnostics.
 
+### Create a new remote workflow (optional)
+
+If `demo` already points to an existing Tela workflow, keep its active-context `projectId`/`promptId` binding and continue to `sync`. To provision a new remote workflow instead, leave `promptId` unset and make the active binding's project available or pass it explicitly:
+
+```bash
+tela workflow create demo --project proj_123 --json
+```
+
+`create` contacts Tela intentionally, validates the prompt/bootstrap/project/workspace identities returned by the create response, records that identity in the active-context config binding, preserves the authored source, and attempts the normal sync lifecycle without publishing. It rejects an already prompt-bound target. If the POST outcome is unknown, `--json` retains the stable idempotency key even when `promptId` is `null`; replay the same command instead of choosing a new identity. If sync prerequisites are unavailable or the remote advanced beyond the bootstrap version, inspect the reported `sync.status`, phase, diagnostics, and recovery data before running `sync` yourself.
+
 ### Sync
 
 ```bash