From 1a37928bb9721f4b8b4ffb4ae6666dfd8ce936d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= <xiaoju@shazhou.work>
Date: Fri, 5 Jun 2026 23:13:54 +0000
Subject: [PATCH] =?UTF-8?q?fix:=20workflow-authoring=20docs=20=E2=80=94=20?=
 =?UTF-8?q?type:object=20+=20const=20vs=20enum=20clarity=20(#123)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add type:object to all frontmatter examples (flat and oneOf)
- Restructure $status section: Multi-exit (oneOf/const) vs Single-exit (flat/enum)
- Add Important rules box clarifying validation requirements
- Restore Custom Fields subsection

Fixes #123
---
 .changeset/workflow-authoring-docs.md         | 10 ++++++++
 .../util/src/workflow-authoring-reference.ts  | 23 +++++++++++--------
 2 files changed, 24 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/workflow-authoring-docs.md

diff --git a/.changeset/workflow-authoring-docs.md b/.changeset/workflow-authoring-docs.md
new file mode 100644
index 0000000..08d0812
--- /dev/null
+++ b/.changeset/workflow-authoring-docs.md
@@ -0,0 +1,10 @@
+---
+"@united-workforce/util": patch
+---
+
+fix: workflow-authoring docs — add type:object to oneOf examples, clarify const vs enum rules (#123)
+
+- All frontmatter examples include `type: object` (both flat and oneOf)
+- Restructure $status section: "Multi-exit (oneOf)" vs "Single-exit (flat schema)"
+- Add "Important rules" box: type:object required, const only in oneOf, enum in flat
+- Restore "Custom Fields" subsection
diff --git a/packages/util/src/workflow-authoring-reference.ts b/packages/util/src/workflow-authoring-reference.ts
index 7d32e31..28c1f68 100644
--- a/packages/util/src/workflow-authoring-reference.ts
+++ b/packages/util/src/workflow-authoring-reference.ts
@@ -28,6 +28,7 @@ roles:                         # named actors
       2. Do that
     output: "..."              # what the agent should produce
     frontmatter:               # JSON Schema for structured output
+      type: object
       oneOf:
         - properties:
             $status: { const: "ready" }
@@ -71,10 +72,13 @@ The \`frontmatter\` field is a standard JSON Schema. It defines the structured f
 
 ### \`$status\` Field
 
-\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows.
+
+**Multi-exit (oneOf)** — use \`const\` to constrain each variant:
 
 \`\`\`yaml
 frontmatter:
+  type: object
   oneOf:
     - properties:
         $status: { const: "done" }
@@ -86,13 +90,7 @@ frontmatter:
       required: [$status, error]
 \`\`\`
 
-### Custom Fields
-
-Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
-
-### Flat Schema (Single Status)
-
-When a role has only one outcome, use \`enum\` with a single value:
+**Single-exit (flat schema)** — use \`enum\` (not \`const\`):
 
 \`\`\`yaml
 frontmatter:
@@ -105,7 +103,14 @@ frontmatter:
   required: [$status, summary]
 \`\`\`
 
-Note: \`$status: { const: "done" }\` is **not** valid in flat schemas — the validator requires \`enum\` or \`oneOf\` with \`const\`. Use \`const\` only inside \`oneOf\` variants.
+**Important rules:**
+- \`type: object\` is **required** at the top level of frontmatter (both flat and oneOf)
+- In flat schemas, \`$status\` must use \`enum: [value]\`, NOT \`const: "value"\` — the validator rejects \`const\` outside of \`oneOf\` variants
+- In \`oneOf\` schemas, each variant's \`$status\` must use \`const: "value"\`
+
+### Custom Fields
+
+Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
 
 ## Graph Routing