From 5450bc12301aa9334a08677ae34efc67392f67e2 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 11:44:20 +0000
Subject: [PATCH] fix: workflow-authoring flat schema, bootstrap PATH guidance

- #110.3: flat schema example uses enum: [done] instead of bare const
  (bare const fails validate-semantic hasStatusEnum check)
- #110.4: bootstrap adds 'which hermes' PATH check and venv guidance
- #110.1: already fixed in rc.1 (inline hello.yaml)
- #110.2: already fixed in rc.1 (capabilities: [] present)

Fixes #110
---
 .changeset/bootstrap-schema-path.md               | 9 +++++++++
 packages/cli/src/commands/prompt.ts               | 5 +++++
 packages/util/src/workflow-authoring-reference.ts | 9 +++++++--
 3 files changed, 21 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/bootstrap-schema-path.md

diff --git a/.changeset/bootstrap-schema-path.md b/.changeset/bootstrap-schema-path.md
new file mode 100644
index 0000000..9592043
--- /dev/null
+++ b/.changeset/bootstrap-schema-path.md
@@ -0,0 +1,9 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/util": patch
+---
+
+fix: workflow-authoring flat schema example uses enum, bootstrap adds PATH guidance
+
+- workflow-authoring: flat schema example uses `enum: [done]` instead of bare `const` (#110.3)
+- bootstrap: adds `which hermes` check and PATH guidance for venv installs (#110.4)
diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts
index 3f33fef..7daee8b 100644
--- a/packages/cli/src/commands/prompt.ts
+++ b/packages/cli/src/commands/prompt.ts
@@ -48,6 +48,11 @@ Install an agent adapter (at least one is required):
 pip install hermes-agent[acp]   # or: pip install -e .[acp] if installed from source
 \`\`\`
 
+Verify \`hermes\` is in your PATH: \`which hermes\`. If Hermes is installed in a virtualenv (e.g. \`~/.hermes/hermes-agent/.venv/\`), activate it or add the bin directory to PATH:
+\`\`\`bash
+export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"
+\`\`\`
+
 Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).
 
 ### Step 2 — Configure provider and model
diff --git a/packages/util/src/workflow-authoring-reference.ts b/packages/util/src/workflow-authoring-reference.ts
index 0220bc4..7d32e31 100644
--- a/packages/util/src/workflow-authoring-reference.ts
+++ b/packages/util/src/workflow-authoring-reference.ts
@@ -92,16 +92,21 @@ Add any fields you need for data passing between roles. These are available in e
 
 ### Flat Schema (Single Status)
 
-When a role has only one outcome:
+When a role has only one outcome, use \`enum\` with a single value:
 
 \`\`\`yaml
 frontmatter:
+  type: object
   properties:
-    $status: { const: "done" }
+    $status:
+      type: string
+      enum: [done]
     summary: { type: string }
   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.
+
 ## Graph Routing
 
 The graph maps each role's \`$status\` values to the next role:
-- 
2.43.0