fix(cli): align workflow list with thread start via parent traversal

discoverProjectWorkflows() now searches .workflow/ in ancestor directories,
matching findWorkflowInParents() behavior used by `uwf thread start`. Also
documents project-local .workflow/ auto-discovery in usage, cli, and
workflow-authoring references.

Fixes #162

packages/util/src/cli-reference.ts

@@ -17,9 +17,24 @@ uwf setup --provider <name> --base-url <url> \\
 \`\`\`
 uwf workflow add <file>           # register a workflow from YAML file
 uwf workflow show <id>            # show workflow by name or CAS hash
-uwf workflow list                 # list all registered workflows
+uwf workflow list                 # list workflows (auto-discovers .workflow/ from cwd upward + global registry)
 \`\`\`
 
+### Workflow Resolution
+
+\`uwf thread start <workflow>\` and \`uwf workflow list\` both resolve the workflow
+argument by searching from cwd upward. Strategies are tried in priority order:
+
+1. **CAS hash** — a 13-char Crockford Base32 string is loaded directly from CAS.
+2. **File path** — a relative or absolute \`.yaml\`/\`.yml\` path is materialized on the fly.
+3. **Local \`.workflow/\` (cwd upward)** — \`uwf\` searches from cwd upward for the nearest
+   directory containing \`.workflow/<name>.yaml\`, \`.workflow/<name>.yml\`,
+   \`.workflow/<name>/index.yaml\`, or the legacy \`.workflows/\` variants. \`workflow list\`
+   uses the same cwd upward parent traversal so its output matches what \`thread start\`
+   can resolve.
+4. **Global registry** — \`uwf workflow add\` stores the workflow under
+   \`@uwf/registry/<name>\` for system-wide resolution independent of cwd.
+
 ## Thread Commands
 
 \`\`\`

packages/util/src/usage-reference.ts

@@ -18,11 +18,14 @@ Guide for using the uwf CLI to manage workflows and threads.
 # 1. Configure provider and model
 uwf setup
 
-# 2. Register a workflow
-uwf workflow add my-workflow.yaml
+# 2. Place a workflow under .workflow/ in your project (recommended)
+#    uwf thread start auto-discovers from .workflow/ by walking from cwd upward.
+#    No workflow add registration needed.
+mkdir -p .workflow
+cp my-workflow.yaml .workflow/solve-issue.yaml
 
-# 3. Start a thread (creates but does not execute)
-uwf thread start my-workflow -p "Build a login page"
+# 3. Start a thread by bare name (no file path)
+uwf thread start solve-issue -p "Build a login page"
 
 # 4. Execute the thread (runs moderator → agent → extract cycles)
 uwf thread exec <thread-id>          # one step
@@ -51,12 +54,16 @@ Config is stored at \`~/.uwf/config.yaml\`. Override storage root with \`UWF_HOM
 ## Workflow Commands
 
 \`\`\`
-uwf workflow add <file>            # register from YAML file
+uwf workflow add <file>            # register from YAML file (optional)
 uwf workflow show <id>             # show by name or CAS hash
-uwf workflow list                  # list all registered workflows
+uwf workflow list                  # list workflows (auto-discovers .workflow/ from cwd upward + global registry)
 \`\`\`
 
-You can also pass a file path directly to \`uwf thread start\` without registering first.
+Three placement strategies, in priority order:
+
+1. **Project-local \`.workflow/\` (recommended)** — drop \`<name>.yaml\` (or \`<name>/index.yaml\`) under \`<repo>/.workflow/\`. \`uwf thread start <name>\` and \`uwf workflow list\` both auto-discover by walking from cwd upward. No registration step is needed.
+2. **Explicit file path** — pass a relative or absolute \`.yaml\` path to \`uwf thread start ./path/to/workflow.yaml\`. Useful for one-off runs and testing.
+3. **Global registry** — \`uwf workflow add <file>\` stores the workflow hash under \`@uwf/registry/<name>\` so it is available system-wide, independent of cwd.
 
 ## Thread Lifecycle
 

packages/util/src/workflow-authoring-reference.ts

@@ -159,6 +159,28 @@ graph:
     failed: { role: cleanup, prompt: "Clean up: {{{error}}}" }
 \`\`\`
 
+## Placement
+
+Drop your workflow YAML under a project-local \`.workflow/\` directory at (or above)
+your repo root:
+
+\`\`\`
+my-project/
+  .workflow/
+    solve-issue.yaml
+    review-code.yaml
+\`\`\`
+
+\`uwf thread start solve-issue\` will auto-discover \`.workflow/solve-issue.yaml\` by
+searching from cwd upward — you can run the command from any subdirectory of the
+project. \`uwf workflow list\` uses the same parent traversal, so its output
+matches what \`thread start\` can resolve. No workflow add registration needed —
+\`uwf workflow add\` is only required for global, cwd-independent registration.
+
+Folder-based layouts also work — \`.workflow/<name>/index.yaml\` (or \`index.yml\`) is
+discovered as workflow \`<name>\`. The legacy \`.workflows/\` directory remains
+supported as a fallback when \`.workflow/\` is absent.
+
 ## Self-Testing
 
 ### Step-by-Step Verification