@meistrari/tela-cli 1.5.0 → 1.7.0

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`, `publish`, and `watch` workflows. Current MVP behavior is local-first until you run an explicit remote lifecycle command such as `create`, `sync`, `publish`, or `watch`.
 
 ### Command surface
 
@@ -10,12 +10,14 @@ 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. |
+| `watch [target] [--config <path>] [--env <path>] [--json]` | Implemented | Yes | Run an initial compile, codegen, and sync cycle, then serialize debounced source, config, and Tela context changes until stopped. |
 
 ### 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`, `publish`, and `watch` 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,10 +25,13 @@ 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
 tela workflow publish invoice-processing --environment staging --json
+tela workflow watch
+tela workflow watch invoice-processing --env .env.staging
 ```
 
 ### init
@@ -162,7 +167,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
 
@@ -192,6 +227,29 @@ tela workflow publish invoice-processing --environment dev --create-environment-
 tela workflow publish --environment production --yes --json
 ```
 
+### watch
+
+**Description.** `tela workflow watch` runs an initial compile, codegen, and sync cycle for the selected workflow(s), then watches local source files, the workflow-code config, and the active Tela Local config file (`~/.tela/config.json` or `$TELA_HOME/config.json`) for changes. Rapid edits debounce into one re-run, and file events that arrive while a cycle is already running coalesce into one serialized follow-up cycle, so codegen and sync do not overlap.
+
+Each cycle reloads config before syncing, so newly added targets, changed entries, and newly imported source files are picked up without restarting watch. Each cycle also refreshes the shared workspace catalog (the same mechanism as `codegen`) and, when the active Tela Local context changes, automatically switches to that context's lockfile before the next sync while reporting the prior and new context in human output. If the active context is unchanged, watch prints no context-change notice.
+
+A compile failure in one workflow blocks only that workflow's sync and does not stop the watch loop. Watch never publishes and ignores project `.tela/` writes, including lockfiles, catalog snapshots, and generated augmentation files, so it cannot trigger itself. Watcher backend errors are reported with diagnostics and close the watcher. Stop watch with Ctrl+C; the routed Tela CLI removes its SIGINT handler after shutdown.
+
+| Prop | Type | Required | Description |
+|---|---|---:|---|
+| `target` | Positional | No | Config `workflows` key to watch. Omit to watch 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. |
+| `--json` | Flag | No | Emit one JSON line per watch cycle (codegen and per-target sync results, plus a context-changed flag) instead of formatted terminal output. |
+
+**Examples.**
+
+```bash
+tela workflow watch
+tela workflow watch invoice-processing
+tela workflow watch invoice-processing --env .env.staging
+```
+
 
 
 ### JSON diagnostics

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/manifest.json

@@ -8,7 +8,7 @@
       "slug": "overview",
       "title": "Documentation overview",
       "file": "overview.md",
-      "sha256": "88c838262048260cee280cdd8d16e9987847bcf06b857ca6d2cf0b707c4b15fe"
+      "sha256": "6209c5b2d8b2d85ca8a084df932e0af9786ff88312f80c59625b47a1d246f307"
     },
     {
       "slug": "api-reference",
@@ -20,13 +20,13 @@
       "slug": "cli",
       "title": "CLI",
       "file": "cli.md",
-      "sha256": "ef7975ab0a915f6a57aa869713e0134478751e9814ac0b2f40d137c85f8ad581"
+      "sha256": "e1ad966acd236d4b80ccedc101f808f295b1917b05cf16831131265c22a6e8a2"
     },
     {
       "slug": "config",
       "title": "Config",
       "file": "config.md",
-      "sha256": "b07b91f46b4ab9a3850df58a0dec388c670771be6de0a5cf3bafd989135fe306"
+      "sha256": "7a9a70422f2dc8aad5238d6aa0d09a4d635a18e08d264556a35eff5e9efe31f3"
     },
     {
       "slug": "guides",
@@ -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