@openclaw/lobster 2026.5.24-beta.1 → 2026.5.25-beta.1

package/node_modules/@clawdbot/lobster/README.md

@@ -1,4 +1,4 @@
-# Lobster
+# 🦞 Lobster
 
 An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
 
@@ -208,6 +208,38 @@ Notes:
 - `pipeline:` shares the same args/env/results model as shell steps, so later steps can still reference `$step.stdout` or `$step.json`.
 - If you need a human checkpoint before an LLM call, use a dedicated `approval:` step in the workflow file rather than `approve` inside the nested pipeline.
 - `cwd`, `env`, `stdin`, `when`, and `condition` work for both shell and pipeline steps.
+- Use `retry`, `timeout_ms`, and `on_error` per step to control transient-failure behavior and recovery.
+- Approval steps can optionally enforce identity constraints:
+  - `approval.required_approver` (or `requiredApprover`) requires an exact approver id.
+  - `approval.require_different_approver` (or `requireDifferentApprover`) requires approver id to differ from initiator.
+  - `approval.initiated_by` (or `initiatedBy`) sets the initiator id for comparison.
+  - `LOBSTER_APPROVAL_INITIATED_BY` can provide a default initiator id at run time.
+  - `LOBSTER_APPROVAL_APPROVED_BY` is used at resume/approval time for identity checks.
+
+## Visualizing workflows
+
+Use `lobster graph` to inspect workflow structure before execution.
+
+```bash
+lobster graph --file path/to/workflow.lobster
+lobster graph --file path/to/workflow.lobster --format mermaid
+lobster graph --file path/to/workflow.lobster --format dot
+lobster graph --file path/to/workflow.lobster --format ascii
+lobster graph --file path/to/workflow.lobster --args-json '{"location":"Seattle"}'
+```
+
+What gets visualized:
+
+- each workflow step as a node (`run`, `pipeline`, `approval`, etc.)
+- data-flow edges from `stdin: $step.stdout` / `$step.json` references
+- conditional dependencies from `when:` / `condition:` expressions
+- approval gates as diamond-shaped nodes in `mermaid` and `dot` output
+
+Format notes:
+
+- `mermaid` (default): emits `flowchart TD` text for GitHub/Markdown rendering
+- `dot`: emits Graphviz DOT syntax
+- `ascii`: emits a terminal-friendly node/edge list
 
 ## Calling LLMs from workflows
 
@@ -233,6 +265,23 @@ Built-in providers today:
 
 `llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.
 
+### `pipeline:` vs `run:` for LLM calls
+
+- Use `pipeline:` for `llm.invoke` and `llm_task.invoke` (they are Lobster pipeline stages, not shell executables).
+- Use `run:` only for real binaries in your shell (for example `openclaw.invoke`).
+
+Example (`stdin` from a prior step is passed to the LLM as artifacts):
+
+```yaml
+steps:
+  - id: make_words
+    run: echo "One two three four five six"
+
+  - id: count_words
+    pipeline: llm_task.invoke --prompt "How many words have been pasted below?"
+    stdin: $make_words.stdout
+```
+
 ## Calling OpenClaw tools from workflows
 
 Shell `run:` steps execute in your system shell, so OpenClaw tool calls there must be real executables.