docs: add draft patch and plan artifact workflow guidance

skills/wf-cli/SKILL.md

@@ -36,6 +36,7 @@ wf draft patch <workspace_id> --revision <n> --input-file patch.json
 wf draft validate <workspace_id>
 wf draft save <workspace_id> --artifact <artifact_id> --version <n> --title <title>
 
+wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version <n> --title <title>
 wf deploy save <deployment_id> --artifact <artifact_id> --version <n> --binding <logical>=<concrete>
 wf deploy validate <deployment_id>
 wf run start <deployment_id> --input-file input.json
@@ -47,6 +48,8 @@ wf run trace <run_id> --from 0 --limit 25
 - Prefer `--input-file` for large JSON.
 - Prefer `--format ids` or `--format compact` for discovery.
 - Use `wf cap call` as a cheap smoke test before creating a draft.
+- Prefer draft workspaces for iterative authoring; use `artifact create-from-plan`
+  only when you already have a complete raw JSON/YAML workflow plan.
 - Do not request unbounded traces.
 - Do not treat wrapper hints as semantic guarantees.
 - If validation fails, run `wf explain <code>` or `wf explain --input-file <validation-output.json>`.

skills/wf-workflow/SKILL.md

@@ -13,7 +13,7 @@ Use this skill for the workflow lifecycle, regardless of front door:
 
 Prefer small discovery calls, draft workspaces, validation, and bounded trace
 reads. Do not write raw workflow plans unless the user explicitly asks for the
-low-level escape hatch.
+low-level escape hatch or you already have a complete compiler/generated plan.
 
 ## Workflow Lifecycle
 
@@ -41,6 +41,9 @@ low-level escape hatch.
   lifecycle behavior.
 - Treat wrapper hints as scaffolding, not semantic truth.
 - Use draft workspaces for iterative authoring; avoid rewriting full drafts.
+- If a complete raw JSON/YAML plan already exists, the CLI escape hatch is
+  `wf artifact create-from-plan`; do not write helper scripts that call
+  `WorkflowApi.create_artifact_from_plan` directly.
 - Use explicit source bindings at deployment time.
 - Keep traces bounded with `trace_range`.
 - Do not expect a newly saved workflow to become a new MCP tool mid-session.

skills/wf-workflow/references/draft-workspaces.md

@@ -70,3 +70,12 @@ Prefer focused helpers over JSON Patch for common edits:
 - `set_step_output_map`
 
 Use JSON Patch for structural edits the helpers do not cover.
+
+For larger patches, write a JSON Patch array to a file and pass it with
+`--input-file`:
+
+```bash
+wf draft patch <workspace_id> --revision <n> --input-file draft-patch.json
+```
+
+The patch file must be an RFC 6902 JSON Patch array, not a full draft object.

skills/wf-workflow/references/workflow-lifecycle.md

@@ -27,6 +27,30 @@ validated, runnable deployment.
 8. Run the deployment.
 9. Inspect the run summary first; read bounded traces only when needed.
 
+## Raw Plan Escape Hatch
+
+Draft workspaces are the normal interactive authoring path. If a compiler,
+fixture, or advanced client already has a complete raw JSON/YAML workflow plan,
+use the CLI escape hatch instead of writing a helper script around the Python
+API:
+
+```bash
+wf artifact create-from-plan workflow.plan.json \
+  --artifact <artifact_id> \
+  --version 1 \
+  --title "Workflow Title" \
+  --outcome ok \
+  --binding <logical_source>=<concrete_source>
+```
+
+Then continue with the normal deployment and run steps:
+
+```bash
+wf deploy save <deployment_id> --artifact <artifact_id> --version 1
+wf deploy validate <deployment_id>
+wf run start <deployment_id> --input-file input.json
+```
+
 ## Object Model
 
 - **Source**: owner of capabilities, such as `wf.std` or `everything.default`.