chore: uptick

2026-05-02 03:19:39 -05:00
parent 420f68e4e2
commit db884f4646
240 changed files with 25206 additions and 3155 deletions
@@ -28,7 +28,7 @@ When you run `hermes update`, the following steps occur:
 2. **Git pull** — pulls the latest code from the `main` branch and updates submodules
 3. **Dependency install** — runs `uv pip install -e ".[all]"` to pick up new or changed dependencies
 4. **Config migration** — detects new config options added since your version and prompts you to set them
-5. **Gateway auto-restart** — if the gateway service is running (systemd on Linux, launchd on macOS), it is **automatically restarted** after the update completes so the new code takes effect immediately
+5. **Gateway auto-restart** — running gateways are refreshed after the update completes so the new code takes effect immediately. Service-managed gateways (systemd on Linux, launchd on macOS) are restarted through the service manager. Manual gateways are relaunched automatically when Hermes can map the running PID back to a profile.

 ### Preview-only: `hermes update --check`

@@ -63,7 +63,7 @@ Already up to date.  (or: Updating abc1234..def5678)
 ✅ Dependencies updated
 🔍 Checking for new config options...
 ✅ Config is up to date  (or: Found 2 new options — running migration...)
-🔄 Restarting gateway service...
+🔄 Restarting gateways...
 ✅ Gateway restarted
 ✅ Hermes Agent updated successfully!
 ```
@@ -113,7 +113,7 @@ You can also update directly from Telegram, Discord, Slack, or WhatsApp by sendi
 /update
 ```

-This pulls the latest code, updates dependencies, and restarts the gateway. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.
+This pulls the latest code, updates dependencies, and restarts running gateways. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.

 ### Manual Update

@@ -55,3 +55,12 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 - **Full web control** — Search, extract, browse, vision, image generation, TTS
 - **MCP support** — Connect to any MCP server for extended tool capabilities
 - **Research-ready** — Batch processing, trajectory export, RL training with Atropos. Built by [Nous Research](https://nousresearch.com) — the lab behind Hermes, Nomos, and Psyche models
+
+## For LLMs and coding agents
+
+Machine-readable entry points to this documentation:
+
+- **[`/llms.txt`](/llms.txt)** — curated index of every doc page with short descriptions. ~17 KB, safe to load into an LLM context.
+- **[`/llms-full.txt`](/llms-full.txt)** — every doc page concatenated into a single markdown file for one-shot ingestion. ~1.8 MB.
+
+Both files also resolve at `/docs/llms.txt` and `/docs/llms-full.txt`. Generated fresh on every deploy.
@@ -718,12 +718,21 @@ The curator is an auxiliary-model background task that periodically reviews agen
 |------------|-------------|
 | `status` | Show curator status and skill stats |
 | `run` | Trigger a curator review now |
+| `run --sync` | Block until the LLM pass finishes |
+| `run --dry-run` | Preview only — produce the review report with no mutations |
+| `backup` | Take a manual tar.gz snapshot of `~/.hermes/skills/` (curator also snapshots automatically before every real run) |
+| `rollback` | Restore `~/.hermes/skills/` from a snapshot (defaults to newest) |
+| `rollback --list` | List available snapshots |
+| `rollback --id <ts>` | Restore a specific snapshot by id |
+| `rollback -y` | Skip the confirmation prompt |
 | `pause` | Pause the curator until resumed |
 | `resume` | Resume a paused curator |
 | `pin <skill>` | Pin a skill so the curator never auto-transitions it |
 | `unpin <skill>` | Unpin a skill |
 | `restore <skill>` | Restore an archived skill |

+On a fresh install the first scheduled pass is deferred by one full `interval_hours` (7 days by default) — the gateway will not curate immediately on the first tick after `hermes update`. Use `hermes curator run --dry-run` to preview before that happens.
+
 See [Curator](../user-guide/features/curator.md) for behavior and config.

 ## `hermes fallback`
@@ -300,6 +300,8 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
 | `FEISHU_ENCRYPT_KEY` | Optional encryption key for webhook mode |
 | `FEISHU_VERIFICATION_TOKEN` | Optional verification token for webhook mode |
 | `FEISHU_ALLOWED_USERS` | Comma-separated Feishu user IDs allowed to message the bot |
+| `FEISHU_ALLOW_BOTS` | `none` (default) / `mentions` / `all` — accept inbound messages from other bots. See [bot-to-bot messaging](../user-guide/messaging/feishu.md#bot-to-bot-messaging) |
+| `FEISHU_REQUIRE_MENTION` | `true` (default) / `false` — whether group messages must @mention the bot. Override per-chat via `group_rules.<chat_id>.require_mention`. |
 | `FEISHU_HOME_CHANNEL` | Feishu chat ID for cron delivery and notifications |
 | `WECOM_BOT_ID` | WeCom AI Bot ID from admin console |
 | `WECOM_SECRET` | WeCom AI Bot secret |
@@ -406,6 +408,7 @@ Advanced per-platform knobs for throttling the outbound message batcher. Most us
 | `HERMES_RESTART_DRAIN_TIMEOUT` | Gateway: seconds to wait for active runs to drain on `/restart` before forcing the restart (default: `900`). |
 | `HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT` | Per-platform connect timeout during gateway startup (seconds). |
 | `HERMES_GATEWAY_BUSY_INPUT_MODE` | Default gateway busy-input behavior: `queue`, `steer`, or `interrupt`. Can be overridden per chat with `/busy`. |
+| `HERMES_GATEWAY_BUSY_ACK_ENABLED` | Whether the gateway sends an acknowledgment message (⚡/⏳/⏩) when a user sends input while the agent is busy (default: `true`). Set to `false` to suppress these messages entirely — the input is still queued/steered/interrupts as normal, only the chat reply is silenced. Bridged from `display.busy_ack_enabled` in `config.yaml`. |
 | `HERMES_CRON_TIMEOUT` | Inactivity timeout for cron job agent runs in seconds (default: `600`). The agent can run indefinitely while actively calling tools or receiving stream tokens — this only triggers when idle. Set to `0` for unlimited. |
 | `HERMES_CRON_SCRIPT_TIMEOUT` | Timeout for pre-run scripts attached to cron jobs in seconds (default: `120`). Override for scripts that need longer execution (e.g., randomized delays for anti-bot timing). Also configurable via `cron.script_timeout_seconds` in `config.yaml`. |
 | `HERMES_CRON_MAX_PARALLEL` | Max cron jobs run in parallel per tick (default: `4`). |
@@ -129,7 +129,9 @@ hermes skills uninstall <skill-name>
 | Skill | Description |
 |-------|-------------|
 | [**canvas**](/docs/user-guide/skills/optional/productivity/productivity-canvas) | Canvas LMS integration — fetch enrolled courses and assignments using API token authentication. |
+| [**here.now**](/docs/user-guide/skills/optional/productivity/productivity-here-now) | Publish static sites to &#123;slug&#125;.here.now and store private files in cloud Drives for agent-to-agent handoff. |
 | [**memento-flashcards**](/docs/user-guide/skills/optional/productivity/productivity-memento-flashcards) | Spaced-repetition flashcard system. Create cards from facts or text, chat with flashcards using free-text answers graded by the agent, generate quizzes from YouTube transcripts, review due cards with adaptive scheduling, and export/impor... |
+| [**shopify**](/docs/user-guide/skills/optional/productivity/productivity-shopify) | Shopify Admin & Storefront GraphQL APIs via curl. Products, orders, customers, inventory, metafields. |
 | [**siyuan**](/docs/user-guide/skills/optional/productivity/productivity-siyuan) | SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl. |
 | [**telephony**](/docs/user-guide/skills/optional/productivity/productivity-telephony) | Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi. |

@@ -38,7 +38,7 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 | [`baoyu-comic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. | `creative/baoyu-comic` |
 | [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` |
 | [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative/claude-design` |
-| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST API for execution. | `creative/comfyui` |
+| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution. | `creative/comfyui` |
 | [`ideation`](/docs/user-guide/skills/bundled/creative/creative-creative-ideation) | Generate project ideas via creative constraints. | `creative/creative-ideation` |
 | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` |
 | [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | `creative/excalidraw` |
@@ -62,6 +62,8 @@ If a skill is missing from this list but present in the repo, the catalog is reg

 | Skill | Description | Path |
 |-------|-------------|------|
+| [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator) | Decomposition playbook + specialist-roster conventions + anti-temptation rules for an orchestrator profile routing work through Kanban. The "don't do the work yourself" rule and the basic lifecycle are auto-injected into every kanban wor... | `devops/kanban-orchestrator` |
+| [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker) | Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper det... | `devops/kanban-worker` |
 | [`webhook-subscriptions`](/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions) | Webhook subscriptions: event-driven agent runs. | `devops/webhook-subscriptions` |

 ## dogfood
@@ -34,6 +34,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/stop` | Kill all running background processes |
 | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response). |
 | `/steer <prompt>` | Inject a mid-run note that arrives at the agent **after the next tool call** — no interrupt, no new user turn. The text is appended to the last tool result's content once the current tool completes, giving the agent new context without breaking the current tool-calling loop. Use this to nudge direction mid-task (e.g. "focus on the auth module" while the agent is running tests). |
+| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. After each turn an auxiliary judge model decides whether the goal is done; if not, Hermes auto-continues. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Budget defaults to 20 turns (`goals.max_turns`); any real user message preempts the continuation loop, and state survives `/resume`. See [Persistent Goals](/docs/user-guide/features/goals) for the full walkthrough. |
 | `/resume [name]` | Resume a previously-named session |
 | `/redraw` | Force a full UI repaint (recovers from terminal drift after tmux resize, mouse selection artifacts, etc.) |
 | `/status` | Show session info |
@@ -153,6 +154,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/background <prompt>` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See [Messaging Background Sessions](/docs/user-guide/messaging/#background-sessions). |
 | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn without interrupting the current one. |
 | `/steer <prompt>` | Inject a message after the next tool call without interrupting — the model picks it up on its next iteration rather than as a new turn. |
+| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](/docs/user-guide/features/goals). |
 | `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, tool counts, timing). |
 | `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. |
 | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. |
@@ -23,6 +23,12 @@ The curator is triggered by an inactivity check, not a cron daemon. On CLI sessi

 If both are true, it spawns a background fork of `AIAgent` — the same pattern used by the memory/skill self-improvement nudges. The fork runs in its own prompt cache and never touches the active conversation.

+:::info First-run behavior
+On a brand-new install (or the first time a pre-curator install ticks after `hermes update`), the curator **does not run immediately**. The first observation seeds `last_run_at` to "now" and defers the first real pass by one full `interval_hours`. This gives you a full interval to review your skill library, pin anything important, or opt out entirely before the curator ever touches it.
+
+If you want to see what the curator *would* do before it runs for real, run `hermes curator run --dry-run` — it produces the same review report without mutating the library.
+:::
+
 A run has two phases:

 1. **Automatic transitions** (deterministic, no LLM). Skills unused for `stale_after_days` (30) become `stale`; skills unused for `archive_after_days` (90) are moved to `~/.hermes/skills/.archive/`.
@@ -80,6 +86,12 @@ Earlier releases used a one-off `curator.auxiliary.{provider,model}` block. That
 hermes curator status         # last run, counts, pinned list, LRU top 5
 hermes curator run            # trigger a review now (background by default)
 hermes curator run --sync     # same, but block until the LLM pass finishes
+hermes curator run --dry-run  # preview only — report without any mutations
+hermes curator backup         # take a manual snapshot of ~/.hermes/skills/
+hermes curator rollback       # restore from the newest snapshot
+hermes curator rollback --list     # list available snapshots
+hermes curator rollback --id <ts>  # restore a specific snapshot
+hermes curator rollback -y         # skip the confirmation prompt
 hermes curator pause          # stop runs until resumed
 hermes curator resume
 hermes curator pin <skill>    # never auto-transition this skill
@@ -87,6 +99,31 @@ hermes curator unpin <skill>
 hermes curator restore <skill>  # move an archived skill back to active
 ```

+## Backups and rollback
+
+Before every real curator pass, Hermes takes a tar.gz snapshot of `~/.hermes/skills/` at `~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz`. If a pass archives or consolidates something you didn't want touched, you can undo the whole run with one command:
+
+```bash
+hermes curator rollback        # restore newest snapshot (with confirmation)
+hermes curator rollback -y     # skip the prompt
+hermes curator rollback --list # see all snapshots with reason + size
+```
+
+The rollback itself is reversible: before replacing the skills tree, Hermes takes another snapshot tagged `pre-rollback to <target-id>`, so a mistaken rollback can be undone by rolling forward to that one with `--id`.
+
+You can also take manual snapshots at any time with `hermes curator backup --reason "before-refactor"`. The `--reason` string lands in the snapshot's `manifest.json` and is shown in `--list`.
+
+Snapshots are pruned to `curator.backup.keep` (default 5) to keep disk usage bounded:
+
+```yaml
+curator:
+  backup:
+    enabled: true
+    keep: 5
+```
+
+Set `curator.backup.enabled: false` to disable automatic snapshotting. The manual `hermes curator backup` command still works when backups are disabled only if you set `enabled: true` first — the flag gates both paths symmetrically so there's no way to accidentally skip the pre-run snapshot on mutating runs.
+
 `hermes curator status` also lists the five least-recently-used skills — a quick way to see what's likely to become stale next.

 The same subcommands are available as the `/curator` slash command inside a running session (CLI or gateway platforms).
@@ -104,6 +141,18 @@ Everything else in `~/.hermes/skills/` is fair game for the curator. This includ
 - Skills you created manually with a hand-written `SKILL.md`.
 - Skills added via external skill directories you've pointed Hermes at.

+:::warning Your hand-written skills look the same as agent-saved ones
+Provenance here is **binary** (bundled/hub vs. everything else). The curator cannot tell a hand-authored skill you rely on for private workflows apart from a skill the self-improvement loop saved mid-session. Both land in the "agent-created" bucket.
+
+Before the first real pass (7 days after installation by default), take a moment to:
+
+1. Run `hermes curator run --dry-run` to see exactly what the curator would propose.
+2. Use `hermes curator pin <name>` to fence off anything you don't want touched.
+3. Or set `curator.enabled: false` in `config.yaml` if you'd rather manage the library yourself.
+
+Archives are always recoverable via `hermes curator restore <name>`, but it's easier to pin up-front than to chase down a consolidation after the fact.
+:::
+
 If you want to protect a specific skill from ever being touched — for example a hand-authored skill you rely on — use `hermes curator pin <name>`. See the next section.

 ## Pinning a skill
@@ -0,0 +1,165 @@
+---
+sidebar_position: 16
+title: "Persistent Goals"
+description: "Set a standing goal and let Hermes keep working across turns until it's done. Our take on the Ralph loop."
+---
+
+# Persistent Goals (`/goal`)
+
+`/goal` gives Hermes a standing objective that survives across turns. After every turn a lightweight judge model checks whether the goal is satisfied by the assistant's last response. If not, Hermes automatically feeds a continuation prompt back into the same session and keeps working — until the goal is achieved, you pause or clear it, or the turn budget runs out.
+
+It's our take on the **Ralph loop**, directly inspired by [Codex CLI 0.128.0's `/goal`](https://github.com/openai/codex) by Eric Traut (OpenAI). The core idea — keep a goal alive across turns and don't stop until it's achieved — is theirs. The implementation here is independent and adapted to Hermes' architecture.
+
+## When to use it
+
+Use `/goal` for tasks where you want Hermes to iterate on its own without you re-prompting every turn:
+
+- "Fix every lint error in `src/` and verify `ruff check` passes"
+- "Port feature X from repo Y, including tests, and get CI green"
+- "Investigate why session IDs sometimes drift on mid-run compression and write up a report"
+- "Build a small CLI to rename files by their EXIF dates, then test it against the photos/ folder"
+
+Tasks where the agent does one turn and stops don't need `/goal`. Tasks where *you'd otherwise have to say "keep going" three times* are where this shines.
+
+## Quick start
+
+```
+/goal Fix every failing test in tests/hermes_cli/ and make sure scripts/run_tests.sh passes for that directory
+```
+
+What you'll see:
+
+1. **Goal accepted** — `⊙ Goal set (20-turn budget): <your goal>`
+2. **Turn 1 runs** — Hermes starts working as if you'd sent the goal as a normal message.
+3. **Judge runs** — after the turn, the judge model decides `done` or `continue`.
+4. **Loop fires if needed** — if `continue`, you'll see `↻ Continuing toward goal (1/20): <judge's reason>` and Hermes takes the next step automatically.
+5. **Terminates** — eventually you see either `✓ Goal achieved: <reason>` or `⏸ Goal paused — N/20 turns used`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/goal <text>` | Set (or replace) the standing goal. Kicks off the first turn immediately so you don't need to send a separate message. |
+| `/goal` or `/goal status` | Show the current goal, its status, and turns used. |
+| `/goal pause` | Stop the auto-continuation loop without clearing the goal. |
+| `/goal resume` | Resume the loop (resets the turn counter back to zero). |
+| `/goal clear` | Drop the goal entirely. |
+
+Works identically on the CLI and every gateway platform (Telegram, Discord, Slack, Matrix, Signal, WhatsApp, SMS, iMessage, Webhook, API server, and the web dashboard).
+
+## Behavior details
+
+### The judge
+
+After every turn, Hermes calls an auxiliary model with:
+
+- The standing goal text
+- The agent's most recent final response (last ~4 KB of text)
+- A system prompt telling the judge to reply with strict JSON: `{"done": <bool>, "reason": "<one-sentence rationale>"}`
+
+The judge is deliberately conservative: it marks a goal `done` only when the response **explicitly** confirms the goal is complete, when the final deliverable is clearly produced, or when the goal is unachievable/blocked (treated as DONE with a block reason so we don't burn budget on impossible tasks).
+
+### Fail-open semantics
+
+If the judge errors (network blip, malformed response, unavailable aux client), Hermes treats the verdict as `continue` — a broken judge never wedges progress. The **turn budget** is the real backstop.
+
+### Turn budget
+
+Default is 20 continuation turns (`goals.max_turns` in `config.yaml`). When the budget is hit, Hermes auto-pauses and tells you exactly how to proceed:
+
+```
+⏸ Goal paused — 20/20 turns used. Use /goal resume to keep going, or /goal clear to stop.
+```
+
+`/goal resume` resets the counter to zero, so you can keep going in measured chunks.
+
+### User messages always preempt
+
+Any real message you send while a goal is active takes priority over the continuation loop. On the CLI your message lands in `_pending_input` ahead of the queued continuation; on the gateway it goes through the adapter FIFO the same way. The judge runs again after your turn — so if your message happens to complete the goal, the judge will catch it and stop.
+
+### Mid-run safety (gateway)
+
+While an agent is already running, `/goal status`, `/goal pause`, and `/goal clear` are safe to run — they only touch control-plane state and don't interrupt the current turn. Setting a **new** goal mid-run (`/goal <new text>`) is rejected with a message telling you to `/stop` first, so the old continuation can't race the new one.
+
+### Persistence
+
+Goal state lives in `SessionDB.state_meta` keyed by `goal:<session_id>`. That means `/resume` picks up right where you left off — set a goal, close your laptop, come back tomorrow, `/resume`, and the goal is still standing exactly as you left it (active, paused, or done).
+
+### Prompt cache
+
+The continuation prompt is a plain user-role message appended to history. It does **not** mutate the system prompt, swap toolsets, or touch the conversation in any way that invalidates Hermes' prompt cache. Running a 20-turn goal costs the same cache-wise as 20 turns of normal conversation.
+
+## Configuration
+
+Add to `~/.hermes/config.yaml`:
+
+```yaml
+goals:
+  # Max continuation turns before Hermes auto-pauses and asks you to
+  # /goal resume. Default 20. Lower this if you want tighter loops;
+  # raise it for long-running refactors.
+  max_turns: 20
+```
+
+### Choosing the judge model
+
+The judge uses the `goal_judge` auxiliary task. By default it resolves to your main model (see [Auxiliary Models](/docs/user-guide/configuration#auxiliary-models)). If you want to route the judge to a cheap fast model to keep costs down, add an override:
+
+```yaml
+auxiliary:
+  goal_judge:
+    provider: openrouter
+    model: google/gemini-3-flash-preview
+```
+
+The judge call is small (~200 output tokens) and runs once per turn, so a cheap fast model is usually the right call.
+
+## Example walkthrough
+
+```
+You: /goal Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text
+
+  ⊙ Goal set (20-turn budget): Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text
+
+Hermes: Creating /tmp/note_1.txt now.
+  💻 echo "1" > /tmp/note_1.txt   (0.1s)
+  I've created /tmp/note_1.txt with the content "1". I'll continue with the remaining files on the next turn as you specified.
+
+  ↻ Continuing toward goal (1/20): Only 1 of 4 files has been created; 3 files remain.
+
+Hermes: [Continuing toward your standing goal]
+  💻 echo "2" > /tmp/note_2.txt   (0.1s)
+  Created /tmp/note_2.txt. Two more to go.
+
+  ↻ Continuing toward goal (2/20): 2 of 4 files created; 2 remain.
+
+Hermes: [Continuing toward your standing goal]
+  💻 echo "3" > /tmp/note_3.txt   (0.1s)
+  Created /tmp/note_3.txt.
+
+  ↻ Continuing toward goal (3/20): 3 of 4 files created; 1 remains.
+
+Hermes: [Continuing toward your standing goal]
+  💻 echo "4" > /tmp/note_4.txt   (0.1s)
+  All four files have been created: /tmp/note_1.txt through /tmp/note_4.txt, each containing its number.
+
+  ✓ Goal achieved: All four files were created with the specified content, completing the goal.
+
+You: _
+```
+
+Four turns, one `/goal` invocation, zero "keep going" prompts from you.
+
+## When the judge gets it wrong
+
+No judge is perfect. Two failure modes to watch for:
+
+**False negative — judge says continue when the goal is actually done.** The turn budget catches this. You'll see `⏸ Goal paused` and can `/goal clear` or just send a new message.
+
+**False positive — judge says done when work remains.** You'll see `✓ Goal achieved` but you know better. Send a follow-up message to continue, or re-set the goal more precisely: `/goal <more specific text>`. The judge's system prompt is deliberately conservative to make false positives rarer than false negatives.
+
+If you find a judge verdict unconvincing, the reason text in the `↻ Continuing toward goal` or `✓ Goal achieved` line tells you exactly what the judge saw. That's usually enough to diagnose whether the goal text was ambiguous or the model's response was.
+
+## Attribution
+
+`/goal` is Hermes' take on the **Ralph loop** pattern. The user-facing design — keep a goal alive across turns, don't stop until it's achieved, with create/pause/resume/clear controls — was popularised and shipped in [Codex CLI 0.128.0](https://github.com/openai/codex) by Eric Traut on OpenAI's Codex team. Our implementation is independent (central `CommandDef` registry, `SessionDB.state_meta` persistence, auxiliary-client judge, adapter-FIFO continuation on the gateway side) but the idea is theirs. Credit where credit's due.
@@ -201,19 +201,45 @@ FEISHU_GROUP_POLICY=allowlist   # default
 | `allowlist` | Hermes only responds to @mentions from users listed in `FEISHU_ALLOWED_USERS`. |
 | `disabled` | Hermes ignores all group messages entirely. |

-In all modes, the bot must be explicitly @mentioned (or @all) in the group before the message is processed. Direct messages bypass this gate.
+In all modes, the bot must be explicitly @mentioned (or @all) in the group before the message is processed. Direct messages always bypass this gate.

-### Bot Identity for @Mention Gating
-
-For precise @mention detection in groups, the adapter needs to know the bot's identity. It can be provided explicitly:
+Set `FEISHU_REQUIRE_MENTION=false` to let Hermes read all group traffic without requiring an @mention:

 ```bash
-FEISHU_BOT_OPEN_ID=ou_xxx
-FEISHU_BOT_USER_ID=xxx
-FEISHU_BOT_NAME=MyBot
+FEISHU_REQUIRE_MENTION=false
 ```

-If none of these are set, the adapter will attempt to auto-discover the bot name via the Application Info API on startup. For this to work, grant the `admin:app.info:readonly` or `application:application:self_manage` permission scope.
+For per-chat control, set `require_mention` on a `group_rules` entry — see [Per-Group Access Control](#per-group-access-control) below.
+
+### Bot Identity
+
+Hermes auto-detects the bot's `open_id` and display name on startup. You only need to set these manually when auto-detection cannot reach the Feishu API, or when your app uses tenant-scoped user IDs:
+
+```bash
+FEISHU_BOT_OPEN_ID=ou_xxx     # only when auto-detection fails
+FEISHU_BOT_USER_ID=xxx        # required if your app uses sender_id_type=user_id
+FEISHU_BOT_NAME=MyBot         # only when auto-detection fails
+```
+
+## Bot-to-Bot Messaging
+
+By default Hermes ignores messages sent by other bots. Enable bot-to-bot messaging when you want Hermes to participate in A2A orchestration or receive notifications from other bots in the same group.
+
+```bash
+FEISHU_ALLOW_BOTS=mentions   # default: none
+```
+
+| Value | Behavior |
+|-------|----------|
+| `none` | Ignore all messages from other bots (default). |
+| `mentions` | Accept only when the peer bot @mentions Hermes. |
+| `all` | Accept every peer bot message. |
+
+Also configurable as `feishu.allow_bots` in `config.yaml` (env wins when both are set).
+
+Peer bots do not need to be added to `FEISHU_ALLOWED_USERS` — that allowlist applies to human senders only.
+
+Grant the `application:bot.basic_info:read` scope to display peer bot names; without it, peer bots still route correctly but appear as their `open_id`.

 ## Interactive Card Actions

@@ -426,6 +452,9 @@ platforms:
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
+        "oc_free_chat":
+          policy: "open"
+          require_mention: false       # overrides FEISHU_REQUIRE_MENTION for this chat
 ```

 | Policy | Description |
@@ -436,6 +465,8 @@ platforms:
 | `admin_only` | Only users in the global `admins` list can use the bot in this group |
 | `disabled` | Bot ignores all messages in this group |

+Set `require_mention: false` on a `group_rules` entry to skip the @-mention requirement for that specific chat. When omitted, the chat inherits the global `FEISHU_REQUIRE_MENTION` value.
+
 Groups not listed in `group_rules` fall back to `default_group_policy` (defaults to the value of `FEISHU_GROUP_POLICY`).

 ## Deduplication
@@ -455,6 +486,8 @@ Inbound messages are deduplicated using message IDs with a 24-hour TTL. The dedu
 | `FEISHU_DOMAIN` | — | `feishu` | `feishu` (China) or `lark` (international) |
 | `FEISHU_CONNECTION_MODE` | — | `websocket` | `websocket` or `webhook` |
 | `FEISHU_ALLOWED_USERS` | — | _(empty)_ | Comma-separated open_id list for user allowlist |
+| `FEISHU_ALLOW_BOTS` | — | `none` | Accept messages from other bots: `none`, `mentions`, or `all` |
+| `FEISHU_REQUIRE_MENTION` | — | `true` | Whether group messages must @mention the bot |
 | `FEISHU_HOME_CHANNEL` | — | — | Chat ID for cron/notification output |
 | `FEISHU_ENCRYPT_KEY` | — | _(empty)_ | Encrypt key for webhook signature verification |
 | `FEISHU_VERIFICATION_TOKEN` | — | _(empty)_ | Verification token for webhook payload auth |
@@ -487,7 +520,9 @@ WebSocket and per-group ACL settings are configured via `config.yaml` under `pla
 | `Webhook rejected: invalid signature` | Ensure `FEISHU_ENCRYPT_KEY` matches the encrypt key in your Feishu app config |
 | Post messages show as plain text | The Feishu API rejected the post payload; this is normal fallback behavior. Check logs for details. |
 | Images/files not received by bot | Grant `im:message` and `im:resource` permission scopes to your Feishu app |
-| Bot identity not auto-detected | Grant `admin:app.info:readonly` scope, or set `FEISHU_BOT_OPEN_ID` / `FEISHU_BOT_NAME` manually |
+| Bot identity not auto-detected | Usually a transient network issue reaching Feishu's bot info endpoint. Set `FEISHU_BOT_OPEN_ID` and `FEISHU_BOT_NAME` manually as a workaround. |
+| Peer bot messages still ignored after enabling `FEISHU_ALLOW_BOTS` | Hermes can't identify itself yet — set `FEISHU_BOT_OPEN_ID` (and `FEISHU_BOT_USER_ID` if your app uses `sender_id_type=user_id`). |
+| Peer bots show as `ou_xxxxxx` instead of by name | Grant the `application:bot.basic_info:read` scope. |
 | Error 200340 when clicking approval buttons | Enable **Interactive Card** capability and configure **Card Request URL** in the Feishu Developer Console. See [Required Feishu App Configuration](#required-feishu-app-configuration) above. |
 | `Webhook rate limit exceeded` | More than 120 requests/minute from the same IP. This is usually a misconfiguration or loop. |

@@ -232,10 +232,13 @@ By default, messaging a busy agent interrupts it. Two other modes are available:
 ```yaml
 display:
  busy_input_mode: steer   # or queue, or interrupt (default)
+  busy_ack_enabled: true   # set to false to suppress the ⚡/⏳/⏩ chat reply entirely
 ```

 The first time you message a busy agent on any platform, Hermes appends a one-line reminder to the busy-ack explaining the knob (`"💡 First-time tip — …"`). The reminder fires once per install — a flag under `onboarding.seen.busy_input_prompt` latches it. Delete that key to see the tip again.

+If you find the busy-ack noisy — especially with voice input or rapid-fire messages — set `display.busy_ack_enabled: false`. Your input is still queued/steered/interrupts as normal, only the chat reply is silenced.
+
 ## Tool Progress Notifications

 Control how much tool activity is displayed in `~/.hermes/config.yaml`:
@@ -13,8 +13,10 @@ Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Te
 | Context | Behavior |
 |---------|----------|
 | **Personal chat (DM)** | Bot responds to every message. No @mention needed. |
-| **Group chat** | Bot responds to every message in the chat. |
-| **Channel** | Bot only responds when @mentioned (Teams delivers @mentions as regular messages with `<at>BotName</at>` tags, which Hermes strips automatically). |
+| **Group chat** | Bot only responds when @mentioned. |
+| **Channel** | Bot only responds when @mentioned. |
+
+Teams delivers @mentions as regular messages with `<at>BotName</at>` tags, which Hermes strips automatically before processing.

 ---

@@ -35,21 +37,21 @@ teams status --verbose

 ---

-## Step 2: Expose Port 3978
+## Step 2: Expose the Webhook Port

-Teams cannot deliver messages to `localhost`. For local development, use any tunnel tool to get a public HTTPS URL:
+Teams cannot deliver messages to `localhost`. For local development, use any tunnel tool to get a public HTTPS URL. The default port is `3978` — change it with `TEAMS_PORT` if needed.

 ```bash
 # devtunnel (Microsoft)
 devtunnel create hermes-bot --allow-anonymous
-devtunnel port create hermes-bot -p 3978 --protocol https
+devtunnel port create hermes-bot -p 3978 --protocol https  # replace 3978 with TEAMS_PORT if changed
 devtunnel host hermes-bot

 # ngrok
-ngrok http 3978
+ngrok http 3978  # replace 3978 with TEAMS_PORT if changed

 # cloudflared
-cloudflared tunnel --url http://localhost:3978
+cloudflared tunnel --url http://localhost:3978  # replace 3978 with TEAMS_PORT if changed
 ```

 Copy the `https://` URL from the output — you'll use it in the next step. Leave the tunnel running while developing.
@@ -66,7 +68,7 @@ teams app create \
  --endpoint "https://<your-tunnel-url>/api/messages"
 ```

-The CLI outputs your `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID`. Save them — you'll need all three.
+The CLI outputs your `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID`, plus an install link for Step 6. Save the client secret — it won't be shown again.

 ---

@@ -93,7 +95,7 @@ TEAMS_ALLOWED_USERS=<your-aad-object-id>
 HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway
 ```

-This starts the gateway and maps port 3978 on your host to the container. Check that it's running:
+This starts the gateway. The default webhook port is `3978` (override with `TEAMS_PORT`). Check that it's running:

 ```bash
 curl http://localhost:3978/health   # should return: ok
@@ -110,10 +112,10 @@ Look for:
 ## Step 6: Install the App in Teams

 ```bash
-teams app install --id <teamsAppId>
+teams app get <teamsAppId> --install-link
 ```

-The `teamsAppId` was printed by `teams app create` in Step 3. After installing, open Microsoft Teams and send a direct message to your bot — it's ready.
+Open the printed link in your browser — it opens directly in the Teams client. After installing, send a direct message to your bot — it's ready.

 ---

@@ -127,6 +129,7 @@ The `teamsAppId` was printed by `teams app create` in Step 3. After installing,
 | `TEAMS_CLIENT_SECRET` | Azure AD client secret |
 | `TEAMS_TENANT_ID` | Azure AD tenant ID |
 | `TEAMS_ALLOWED_USERS` | Comma-separated AAD object IDs allowed to use the bot |
+| `TEAMS_ALLOW_ALL_USERS` | Set `true` to skip the allowlist and allow anyone |
 | `TEAMS_HOME_CHANNEL` | Conversation ID for cron/proactive message delivery |
 | `TEAMS_HOME_CHANNEL_NAME` | Display name for the home channel |
 | `TEAMS_PORT` | Webhook port (default: `3978`) |
@@ -179,7 +182,7 @@ If you've already created the bot and just need to update the endpoint:
 teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"
 ```

-Make sure port 3978 (or your configured `TEAMS_PORT`) is reachable from the internet and that your TLS certificate is valid — Teams rejects self-signed certificates.
+Make sure your configured port (`TEAMS_PORT`, default `3978`) is reachable from the internet and that your TLS certificate is valid — Teams rejects self-signed certificates.

 ---

@@ -8,7 +8,7 @@ description: "Generate images, video, and audio with ComfyUI — install, launch

 # Comfyui

-Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST API for execution.
+Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution.

 ## Skill metadata

@@ -16,11 +16,11 @@ Generate images, video, and audio with ComfyUI — install, launch, manage nodes
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/creative/comfyui` |
-| Version | `4.1.0` |
+| Version | `5.0.0` |
 | Author | ['kshitijk4poor', 'alt-glitch'] |
 | License | MIT |
 | Platforms | macos, linux, windows |
-| Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `creative`, `generative-ai`, `video-generation` |
+| Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
 | Related skills | [`stable-diffusion-image-generation`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |

 ## Reference: full SKILL.md
@@ -31,327 +31,333 @@ The following is the complete skill definition that Hermes loads when this skill

 # ComfyUI

-Generate images, video, and audio through ComfyUI using the official `comfy-cli` for
-setup/management and direct REST API calls for workflow execution.
+Generate images, video, audio, and 3D content through ComfyUI using the
+official `comfy-cli` for setup/lifecycle and direct REST/WebSocket API
+for workflow execution.

-**Reference files in this skill:**
+## What's in this skill

- `references/official-cli.md` — comfy-cli command reference (install, launch, nodes, models)
- `references/rest-api.md` — ComfyUI REST API endpoints (local + cloud)
- `references/workflow-format.md` — workflow JSON format, common node types, parameter mapping
+**Reference docs (`references/`):**

-**Scripts in this skill:**
+- `official-cli.md` — every `comfy ...` command, with flags
+- `rest-api.md` — REST + WebSocket endpoints (local + cloud), payload schemas
+- `workflow-format.md` — API-format JSON, common node types, param mapping

- `scripts/hardware_check.py` — detect GPU/VRAM/Apple Silicon, decide local vs Comfy Cloud
- `scripts/comfyui_setup.sh` — full setup automation (hardware check + install + launch + verify)
- `scripts/extract_schema.py` — reads workflow JSON, outputs which parameters are controllable
- `scripts/run_workflow.py` — injects user args, submits workflow, monitors progress, downloads outputs
- `scripts/check_deps.py` — checks if required custom nodes and models are installed
+**Scripts (`scripts/`):**
+
+| Script | Purpose |
+|--------|---------|
+| `_common.py` | Shared HTTP, cloud routing, node catalogs (don't run directly) |
+| `hardware_check.py` | Probe GPU/VRAM/disk → recommend local vs Comfy Cloud |
+| `comfyui_setup.sh` | Hardware check + comfy-cli + ComfyUI install + launch + verify |
+| `extract_schema.py` | Read a workflow → list controllable params + model deps |
+| `check_deps.py` | Check workflow against running server → list missing nodes/models |
+| `auto_fix_deps.py` | Run check_deps then `comfy node install` / `comfy model download` |
+| `run_workflow.py` | Inject params, submit, monitor, download outputs (HTTP or WS) |
+| `run_batch.py` | Submit a workflow N times with sweeps, parallel up to your tier |
+| `ws_monitor.py` | Real-time WebSocket viewer for executing jobs (live progress) |
+| `health_check.py` | Verification checklist runner — comfy-cli + server + models + smoke test |
+| `fetch_logs.py` | Pull traceback / status messages for a given prompt_id |
+
+**Example workflows (`workflows/`):** SD 1.5, SDXL, Flux Dev, SDXL img2img,
+SDXL inpaint, ESRGAN upscale, AnimateDiff video, Wan T2V. See
+`workflows/README.md`.

 ## When to Use

- User asks to generate images with Stable Diffusion, SDXL, Flux, or other diffusion models
- User wants to run a specific ComfyUI workflow
+- User asks to generate images with Stable Diffusion, SDXL, Flux, SD3, etc.
+- User wants to run a specific ComfyUI workflow file
 - User wants to chain generative steps (txt2img → upscale → face restore)
 - User needs ControlNet, inpainting, img2img, or other advanced pipelines
 - User asks to manage ComfyUI queue, check models, or install custom nodes
- User wants video/audio generation via AnimateDiff, Hunyuan, AudioCraft, etc.
+- User wants video/audio/3D generation via AnimateDiff, Hunyuan, Wan, AudioCraft, etc.

 ## Architecture: Two Layers

 <!-- ascii-guard-ignore -->
 ```
 ┌─────────────────────────────────────────────────────┐
-│ Layer 1: comfy-cli (official)                       │
-│   Setup, lifecycle, nodes, models                   │
-│   comfy install / launch / stop / node / model      │
+│ Layer 1: comfy-cli (official lifecycle tool)        │
+│   Setup, server lifecycle, custom nodes, models     │
+│   → comfy install / launch / stop / node / model    │
 └─────────────────────────┬───────────────────────────┘
                          │
 ┌─────────────────────────▼───────────────────────────┐
-│ Layer 2: REST API + skill scripts                   │
+│ Layer 2: REST/WebSocket API + skill scripts         │
 │   Workflow execution, param injection, monitoring   │
-│   POST /api/prompt, GET /api/view, WebSocket        │
-│   scripts/run_workflow.py, extract_schema.py        │
+│   POST /api/prompt, GET /api/view, WS /ws           │
+│   → run_workflow.py, run_batch.py, ws_monitor.py    │
 └─────────────────────────────────────────────────────┘
 ```
 <!-- ascii-guard-ignore-end -->

-**Why two layers?** The official CLI handles installation and server management excellently
-but has minimal workflow execution support (just raw file submission, no param injection,
-no structured output). The REST API fills that gap — the scripts in this skill handle the
-param injection, execution monitoring, and output download that the CLI doesn't do.
+**Why two layers?** The official CLI is excellent for installation and server
+management but has minimal workflow execution support. The REST/WS API fills
+that gap — the scripts handle param injection, execution monitoring, and
+output download that the CLI doesn't do.

 ## Quick Start

-### Detect Environment
+### Detect environment

 ```bash
 # What's available?
 command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
 curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"

-# Can this machine actually run ComfyUI locally? (GPU/VRAM/Apple Silicon check)
+# Can this machine run ComfyUI locally? (GPU/VRAM/disk check)
 python3 scripts/hardware_check.py
 ```

-If nothing is installed, go to **Setup & Onboarding** below — but always run the
-hardware check first, before picking an install path.
-If the server is already running, skip to **Core Workflow**.
+If nothing is installed, see **Setup & Onboarding** below — but always run the
+hardware check first.
+
+### One-line health check
+
+```bash
+python3 scripts/health_check.py
+# → JSON: comfy_cli on PATH? server reachable? at least one checkpoint? smoke-test passes?
+```

 ## Core Workflow

-### Step 1: Get a Workflow
+### Step 1: Get a workflow JSON in API format

-Users provide workflow JSON files. These come from:
- ComfyUI web editor → "Save (API Format)" button
- Community downloads (civitai, Reddit, Discord)
- The `scripts/` directory of this skill (example workflows)
+Workflows must be in API format (each node has `class_type`). They come from:

-**The workflow must be in API format** (node IDs as keys with `class_type`).
-If user has editor format (has `nodes[]` and `links[]` at top level), they
-need to re-export using "Save (API Format)" in the ComfyUI web editor.
+- ComfyUI web UI → **Workflow → Export (API)** (newer UI) or
+  the legacy "Save (API Format)" button (older UI)
+- This skill's `workflows/` directory (ready-to-run examples)
+- Community downloads (civitai, Reddit, Discord) — usually editor format,
+  must be loaded into ComfyUI then re-exported

-### Step 2: Understand What's Controllable
+Editor format (top-level `nodes` and `links` arrays) is **not directly
+executable**. The scripts detect this and tell you to re-export.
+
+### Step 2: See what's controllable

 ```bash
+python3 scripts/extract_schema.py workflow_api.json --summary-only
+# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}
+
 python3 scripts/extract_schema.py workflow_api.json
+# → full schema with parameters, model deps, embedding refs
 ```

-Output (JSON):
-```json
-{
-  "parameters": {
-    "prompt": {"node_id": "6", "field": "text", "type": "string", "value": "a cat"},
-    "negative_prompt": {"node_id": "7", "field": "text", "type": "string", "value": "bad quality"},
-    "seed": {"node_id": "3", "field": "seed", "type": "int", "value": 42},
-    "steps": {"node_id": "3", "field": "steps", "type": "int", "value": 20},
-    "width": {"node_id": "5", "field": "width", "type": "int", "value": 512},
-    "height": {"node_id": "5", "field": "height", "type": "int", "value": 512}
-  }
-}
-```
+### Step 3: Run with parameters

-### Step 3: Run with Parameters
-
-**Local:**
 ```bash
+# Local (defaults to http://127.0.0.1:8188)
 python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
-  --args '{"prompt": "a beautiful sunset over mountains", "seed": 123, "steps": 30}' \
+  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
  --output-dir ./outputs
-```

-**Cloud:**
-```bash
+# Cloud (export API key once; uses correct /api routing automatically)
+export COMFY_CLOUD_API_KEY="comfyui-..."
 python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
-  --args '{"prompt": "a beautiful sunset", "seed": 123}' \
+  --args '{"prompt": "..."}' \
  --host https://cloud.comfy.org \
-  --api-key "$COMFY_CLOUD_API_KEY" \
  --output-dir ./outputs
+
+# Real-time progress via WebSocket (requires `pip install websocket-client`)
+python3 scripts/run_workflow.py \
+  --workflow flux_dev.json \
+  --args '{"prompt": "..."}' \
+  --ws
+
+# img2img / inpaint: pass --input-image to upload + reference automatically
+python3 scripts/run_workflow.py \
+  --workflow sdxl_img2img.json \
+  --input-image image=./photo.png \
+  --args '{"prompt": "make it watercolor", "denoise": 0.6}'
+
+# Batch / sweep: 8 random seeds, parallel up to cloud tier limit
+python3 scripts/run_batch.py \
+  --workflow sdxl.json \
+  --args '{"prompt": "abstract"}' \
+  --count 8 --randomize-seed --parallel 3 \
+  --output-dir ./outputs/batch
 ```

-### Step 4: Present Results
+`-1` for `seed` (or omitting it with `--randomize-seed`) generates a fresh
+random seed per run.
+
+### Step 4: Present results
+
+The scripts emit JSON to stdout describing every output file:

-The script outputs JSON with file paths:
 ```json
 {
  "status": "success",
+  "prompt_id": "abc-123",
  "outputs": [
-    {"file": "./outputs/ComfyUI_00001_.png", "node_id": "9", "type": "image"}
+    {"file": "./outputs/sdxl_00001_.png", "node_id": "9",
+     "type": "image", "filename": "sdxl_00001_.png"}
  ]
 }
 ```

-Show images to the user via `vision_analyze` or return the file path directly.
-
 ## Decision Tree

 | User says | Tool | Command |
 |-----------|------|---------|
-| "install ComfyUI" | comfy-cli | `comfy install` |
+| **Lifecycle (use comfy-cli)** | | |
+| "install ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
 | "start ComfyUI" | comfy-cli | `comfy launch --background` |
 | "stop ComfyUI" | comfy-cli | `comfy stop` |
 | "install X node" | comfy-cli | `comfy node install <name>` |
-| "download X model" | comfy-cli | `comfy model download --url <url>` |
+| "download X model" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
 | "list installed models" | comfy-cli | `comfy model list` |
 | "list installed nodes" | comfy-cli | `comfy node show installed` |
-| "generate an image" | script | `run_workflow.py --args '{"prompt": "..."}'` |
-| "use this image" (img2img) | REST | upload image, then run_workflow.py |
-| "what can I change in this workflow?" | script | `extract_schema.py workflow.json` |
-| "check if workflow deps are met" | script | `check_deps.py workflow.json` |
-| "what's in the queue?" | REST | `curl http://HOST:8188/queue` |
+| **Execution (use scripts)** | | |
+| "is everything ready?" | script | `health_check.py` (optionally with `--workflow X --smoke-test`) |
+| "what can I change in this workflow?" | script | `extract_schema.py W.json` |
+| "check if W's deps are met" | script | `check_deps.py W.json` |
+| "fix missing deps" | script | `auto_fix_deps.py W.json` |
+| "generate an image" | script | `run_workflow.py --workflow W --args '{...}'` |
+| "use this image" (img2img) | script | `run_workflow.py --input-image image=./x.png ...` |
+| "8 variations with random seeds" | script | `run_batch.py --count 8 --randomize-seed ...` |
+| "show me live progress" | script | `ws_monitor.py --prompt-id <id>` |
+| "fetch the error from job X" | script | `fetch_logs.py <prompt_id>` |
+| **Direct REST** | | |
+| "what's in the queue?" | REST | `curl http://HOST:8188/queue` (local) or `--host https://cloud.comfy.org` |
 | "cancel that" | REST | `curl -X POST http://HOST:8188/interrupt` |
 | "free GPU memory" | REST | `curl -X POST http://HOST:8188/free` |

 ## Setup & Onboarding

-When a user asks to set up ComfyUI, the FIRST thing to do is ask them whether
-they want **Comfy Cloud** (hosted, zero install, API key) or **Local** (install
-ComfyUI on their machine). Do NOT start running install commands or hardware
+When a user asks to set up ComfyUI, **the FIRST thing to do is ask whether
+they want Comfy Cloud (hosted, zero install, API key) or Local (install
+ComfyUI on their machine)**. Don't start running install commands or hardware
 checks until they've answered.

 **Official docs:** https://docs.comfy.org/installation
 **CLI docs:** https://docs.comfy.org/comfy-cli/getting-started
 **Cloud docs:** https://docs.comfy.org/get_started/cloud
+**Cloud API:** https://docs.comfy.org/development/cloud/overview

 ### Step 0: Ask Local vs Cloud (ALWAYS FIRST)

-Present the tradeoff clearly and wait for the user to choose. Suggested script:
+Suggested script:

 > "Do you want to run ComfyUI locally on your machine, or use Comfy Cloud?
 >
-> - **Comfy Cloud** — hosted on RTX 6000 Pro GPUs, all models pre-installed, zero setup. Requires an API key (paid subscription). Best if you don't have a capable GPU or want to skip installation.
+> - **Comfy Cloud** — hosted on RTX 6000 Pro GPUs, all common models pre-installed,
+>   zero setup. Requires an API key (paid subscription required to actually run
+>   workflows; free tier is read-only). Best if you don't have a capable GPU.
 > - **Local** — free, but your machine MUST meet the hardware requirements:
->   - NVIDIA GPU with **≥6 GB VRAM** (≥8 GB recommended for SDXL, ≥12 GB for Flux/video), OR
+>   - NVIDIA GPU with **≥6 GB VRAM** (≥8 GB for SDXL, ≥12 GB for Flux/video), OR
 >   - AMD GPU with ROCm support (Linux), OR
->   - Apple Silicon Mac (M1 or newer) with **≥16 GB unified memory** (≥32 GB recommended).
+>   - Apple Silicon Mac (M1+) with **≥16 GB unified memory** (≥32 GB recommended).
 >   - Intel Macs and machines with no GPU will NOT work — use Cloud instead.
 >
 > Which would you like?"

-Route based on their answer:
+Routing:

- **User picks Cloud** → skip to **Path A** (no hardware check needed).
- **User picks Local** → go to **Step 1: Hardware Check** to verify their machine actually meets the requirements, then pick an install path from Paths B-E based on the verdict.
- **User is unsure / asks for a recommendation** → run the hardware check anyway and let the verdict decide.
+- **Cloud** → skip to **Path A**.
+- **Local** → run hardware check first, then pick a path from Paths B–E based on the verdict.
+- **Unsure** → run the hardware check and let the verdict decide.

 ### Step 1: Verify Hardware (ONLY if user chose local)

 ```bash
 python3 scripts/hardware_check.py --json
+# Optional: also probe `torch` for actual CUDA/MPS:
+python3 scripts/hardware_check.py --json --check-pytorch
 ```

-It detects OS, GPU (NVIDIA CUDA / AMD ROCm / Apple Silicon / Intel Arc), VRAM,
-and unified/system RAM, then returns a verdict plus a suggested `comfy-cli` flag:
+| Verdict    | Meaning                                                       | Action |
+|------------|---------------------------------------------------------------|--------|
+| `ok`       | ≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon)       | Local install — use `comfy_cli_flag` from report |
+| `marginal` | SD1.5 works; SDXL tight; Flux/video unlikely                  | Local OK for light workflows, else **Path A (Cloud)** |
+| `cloud`    | No usable GPU, &lt;6 GB VRAM, &lt;16 GB Apple unified, Intel Mac, Rosetta Python | **Switch to Cloud** unless user explicitly forces local |

-| Verdict    | Meaning                                                   | Action                                          |
-|------------|-----------------------------------------------------------|-------------------------------------------------|
-| `ok`       | ≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon)   | Local install — use `comfy_cli_flag` from report |
-| `marginal` | SD1.5 works; SDXL tight; Flux/video unlikely              | Local OK for light workflows, else **Path A (Cloud)** |
-| `cloud`    | No usable GPU, &lt;6 GB VRAM, &lt;16 GB Apple unified, Intel Mac | **User chose local but their machine doesn't meet requirements** — surface the `notes` and ask if they want to switch to Cloud |
+The script also surfaces `wsl: true` (WSL2 with NVIDIA passthrough) and
+`rosetta: true` (x86_64 Python on Apple Silicon — must reinstall as ARM64).

-Hardware thresholds the skill enforces:
-
- **Discrete GPU minimum:** 6 GB VRAM. Below that, most modern models won't load.
- **Apple Silicon:** M1 or newer (ARM64). Intel Macs have no MPS backend — Cloud only.
- **Apple Silicon memory:** 16 GB unified minimum. 8 GB M1/M2 will swap/OOM on SDXL/Flux.
- **No accelerator at all:** CPU-only is listed as a comfy-cli option but a single SDXL
-  image takes 10+ minutes — treat it as unusable and route to Cloud.
-
-If verdict is `cloud` but the user explicitly wanted local, DO NOT proceed
-silently. Show the `notes` array verbatim, explain which requirement they
-don't meet, and ask whether they want to (a) switch to Cloud or (b) force
-a local install anyway (marginal/cloud-verdict local installs will OOM or
-be unusably slow on modern models).
-
-The report's `comfy_cli_flag` field gives you the exact flag for Step 2 below:
-`--nvidia`, `--amd`, or `--m-series`. For Intel Arc, use Path E (manual install).
-
-Surface the `notes` array verbatim to the user so they understand why a
-particular path was recommended.
+If verdict is `cloud` but the user wants local, do not proceed silently.
+Show the `notes` array verbatim and ask whether they want to (a) switch to
+Cloud or (b) force a local install (will OOM or be unusably slow on modern models).

 ### Choosing an Installation Path

-Use the hardware check result first. The table below is a fallback for when the user
-has already told you their hardware or you need to narrow down between multiple
-viable paths:
+Use the hardware check first. The table below is the fallback for when the
+user has already told you their hardware:

 | Situation | Recommended Path |
-|-----------|-----------------|
+|-----------|------------------|
 | `verdict: cloud` from hardware check | **Path A: Comfy Cloud** |
-| No GPU / just want to try it | **Path A: Comfy Cloud** (zero setup) |
-| Windows + NVIDIA GPU + non-technical | **Path B: ComfyUI Desktop** (one-click installer) |
-| Windows + NVIDIA GPU + technical | **Path C: Portable** or **Path D: comfy-cli** |
-| Linux + any GPU | **Path D: comfy-cli** (easiest) or Path E manual |
-| macOS + Apple Silicon | **Path B: ComfyUI Desktop** or **Path D: comfy-cli** |
-| Headless / server / CI | **Path D: comfy-cli** |
+| No GPU / want to try without commitment | **Path A: Comfy Cloud** |
+| Windows + NVIDIA + non-technical | **Path B: ComfyUI Desktop** |
+| Windows + NVIDIA + technical | **Path C: Portable** or **Path D: comfy-cli** |
+| Linux + any GPU | **Path D: comfy-cli** (easiest) |
+| macOS + Apple Silicon | **Path B: Desktop** or **Path D: comfy-cli** |
+| Headless / server / CI / agents | **Path D: comfy-cli** |

-For the fully automated path (hardware check → install → launch), just run:
+For the fully automated path (hardware check → install → launch → verify):

 ```bash
 bash scripts/comfyui_setup.sh
+# Or with overrides:
+bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
 ```

-It runs `hardware_check.py` internally, refuses to install locally when the verdict
-is `cloud`, picks the right `comfy-cli` flag otherwise, then installs and launches.
+It runs `hardware_check.py` internally, refuses to install locally when the
+verdict is `cloud` (unless `--force-cloud-override`), picks the right
+`comfy-cli` flag, and prefers `pipx`/`uvx` over global `pip` to avoid polluting
+system Python.

 ---

 ### Path A: Comfy Cloud (No Local Install)

-For users without a capable GPU or who want zero setup.
-Powered by RTX 6000 Pro GPUs, all models pre-installed.
+For users without a capable GPU or who want zero setup. Hosted on RTX 6000 Pro.

 **Docs:** https://docs.comfy.org/get_started/cloud

-1. Go to https://comfy.org/cloud and sign up
-2. Get an API key at https://platform.comfy.org/login
-   - Click `+ New` in API Keys section → Generate
-   - Save immediately (only visible once)
+1. Sign up at https://comfy.org/cloud
+2. Generate an API key at https://platform.comfy.org/login
 3. Set the key:
   ```bash
   export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
   ```
-4. Run workflows via the script or web UI:
+4. Run workflows:
   ```bash
   python3 scripts/run_workflow.py \
-     --workflow workflow_api.json \
-     --args '{"prompt": "a cat"}' \
+     --workflow workflows/flux_dev_txt2img.json \
+     --args '{"prompt": "..."}' \
     --host https://cloud.comfy.org \
-     --api-key "$COMFY_CLOUD_API_KEY" \
     --output-dir ./outputs
   ```

 **Pricing:** https://www.comfy.org/cloud/pricing
-Subscription required. Concurrent limits: Free/Standard: 1 job, Creator: 3, Pro: 5.
+**Concurrent jobs:** Free/Standard 1, Creator 3, Pro 5. Free tier
+**cannot run workflows via API** — only browse models. Paid subscription
+required for `/api/prompt`, `/api/upload/*`, `/api/view`, etc.

 ---

-### Path B: ComfyUI Desktop (Windows/macOS)
+### Path B: ComfyUI Desktop (Windows / macOS)

 One-click installer for non-technical users. Currently Beta.

 **Docs:** https://docs.comfy.org/installation/desktop
-
 - **Windows (NVIDIA):** https://download.comfy.org/windows/nsis/x64
- **macOS (Apple Silicon):** Available from https://comfy.org (download page)
+- **macOS (Apple Silicon):** https://comfy.org

-Steps:
-1. Download and run installer
-2. Select GPU type (NVIDIA recommended, or CPU mode)
-3. Choose install location (SSD recommended, ~15GB needed)
-4. Optionally migrate from existing ComfyUI Portable install
-5. Desktop launches automatically — web UI opens in browser
-
-Desktop manages its own Python environment. For CLI access to the bundled env:
-```bash
-cd <install_dir>/ComfyUI
-.venv/Scripts/activate   # Windows
-# or use the built-in terminal in the Desktop UI
-```
-
-**Limitations:** Desktop uses stable releases (may lag behind latest).
-Linux not supported for Desktop — use comfy-cli or manual install.
+Linux is **not supported** for Desktop — use Path D.

 ---

 ### Path C: ComfyUI Portable (Windows Only)

-Standalone package with embedded Python. Extract and run. No install.
-
 **Docs:** https://docs.comfy.org/installation/comfyui_portable_windows

-1. Download from https://github.com/comfyanonymous/ComfyUI/releases
-   - Standard: Python 3.13 + CUDA 13.0 (modern NVIDIA GPUs)
-   - Alt: PyTorch CUDA 12.6 + Python 3.12 (NVIDIA 10 series and older)
-   - AMD (experimental)
-2. Extract with 7-Zip
-3. Run `run_nvidia_gpu.bat` (or `run_cpu.bat`)
-4. Wait for "To see the GUI go to: http://127.0.0.1:8188"
-
-Update: run `update/update_comfyui.bat` (latest commit) or
-`update/update_comfyui_stable.bat` (latest stable release).
+Download from https://github.com/comfyanonymous/ComfyUI/releases, extract,
+run `run_nvidia_gpu.bat`. Update via `update/update_comfyui_stable.bat`.

 ---

@@ -360,22 +366,19 @@ Update: run `update/update_comfyui.bat` (latest commit) or
 The official CLI is the best path for headless/automated setups.

 **Docs:** https://docs.comfy.org/comfy-cli/getting-started
-**Repo:** https://github.com/Comfy-Org/comfy-cli
-
-#### Prerequisites
- Python 3.10+ (3.13 recommended)
- pip (or conda/uv)
- GPU drivers installed (CUDA for NVIDIA, ROCm for AMD)

 #### Install comfy-cli

 ```bash
-pip install comfy-cli
-# or
+# Recommended:
+pipx install comfy-cli
+# Or use uvx without installing:
 uvx --from comfy-cli comfy --help
+# Or (if pipx/uvx unavailable):
+pip install --user comfy-cli
 ```

-Disable analytics (avoids interactive prompt):
+Disable analytics non-interactively:
 ```bash
 comfy --skip-prompt tracking disable
 ```
@@ -383,270 +386,225 @@ comfy --skip-prompt tracking disable
 #### Install ComfyUI

 ```bash
-# Interactive (prompts for GPU type)
-comfy install
-
-# Non-interactive variants:
 comfy --skip-prompt install --nvidia              # NVIDIA (CUDA)
 comfy --skip-prompt install --amd                 # AMD (ROCm, Linux)
 comfy --skip-prompt install --m-series            # Apple Silicon (MPS)
 comfy --skip-prompt install --cpu                 # CPU only (slow)
-
-# With faster dependency resolution:
-comfy --skip-prompt install --nvidia --fast-deps
+comfy --skip-prompt install --nvidia --fast-deps  # uv-based dep resolution
 ```

-Default location: `~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI` (macOS/Win).
-Override with: `comfy --workspace /custom/path install`
+Default location: `~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI`
+(macOS/Win). Override with `comfy --workspace /custom/path install`.

-#### Launch Server
+#### Launch / verify

 ```bash
-comfy launch --background              # background daemon on :8188
-comfy launch                           # foreground (see logs)
-comfy launch -- --listen 0.0.0.0       # accessible on LAN
-comfy launch -- --port 8190            # custom port
-comfy launch -- --lowvram              # low VRAM mode (6GB cards)
-```
-
-Verify server is running:
-```bash
-curl -s http://127.0.0.1:8188/system_stats | python3 -m json.tool
-```
-
-Stop background server:
-```bash
-comfy stop
+comfy launch --background                       # background daemon on :8188
+comfy launch -- --listen 0.0.0.0 --port 8190    # LAN-accessible custom port
+curl -s http://127.0.0.1:8188/system_stats      # health check
 ```

 ---

-### Path E: Manual Install (Advanced / All Hardware)
+### Path E: Manual Install (Advanced / Unsupported Hardware)

-For full control or unsupported hardware (Ascend NPU, Cambricon MLU, Intel Arc).
+For Ascend NPU, Cambricon MLU, Intel Arc, or other unsupported hardware.

 **Docs:** https://docs.comfy.org/installation/manual_install
-**GitHub:** https://github.com/comfyanonymous/ComfyUI

 ```bash
-# 1. Create environment
-conda create -n comfyenv python=3.13
-conda activate comfyenv
-
-# 2. Clone
 git clone https://github.com/comfyanonymous/ComfyUI.git
 cd ComfyUI
-
-# 3. Install PyTorch (pick your hardware)
-# NVIDIA:
 pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
-# AMD (ROCm 6.4):
-pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.4
-# Apple Silicon:
-pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu
-# Intel Arc:
-pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/xpu
-# CPU only:
-pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cpu
-
-# 4. Install ComfyUI deps
 pip install -r requirements.txt
-
-# 5. Run
 python main.py
-# With options: python main.py --listen 0.0.0.0 --port 8188
 ```

 ---

 ### Post-Install: Download Models

-ComfyUI needs at least one checkpoint model to generate images.
-
-**Using comfy-cli:**
 ```bash
-# SDXL (general purpose, ~6.5GB)
+# SDXL (general purpose, ~6.5 GB)
 comfy model download \
  --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
  --relative-path models/checkpoints

-# SD 1.5 (lighter, ~4GB, good for low VRAM)
+# SD 1.5 (lighter, ~4 GB, good for 6 GB cards)
 comfy model download \
  --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
  --relative-path models/checkpoints

-# From CivitAI (may need API token):
+# Flux Dev fp8 (smaller variant, ~12 GB)
+comfy model download \
+  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
+  --relative-path models/checkpoints
+
+# CivitAI (set token first):
 comfy model download \
  --url "https://civitai.com/api/download/models/128713" \
  --relative-path models/checkpoints \
  --set-civitai-api-token "YOUR_TOKEN"
-
-# LoRA adapters:
-comfy model download --url "<URL>" --relative-path models/loras
 ```

-**Manual download:** Place `.safetensors` / `.ckpt` files directly into the
-`ComfyUI/models/checkpoints/` directory (or `loras/`, `vae/`, etc.).
-
-List installed models:
-```bash
-comfy model list
-```
-
---
+List installed: `comfy model list`.

 ### Post-Install: Install Custom Nodes

-Custom nodes extend ComfyUI's capabilities (upscaling, video, ControlNet, etc.).
-
 ```bash
-comfy node install comfyui-impact-pack           # popular utility pack
-comfy node install comfyui-animatediff-evolved    # video generation
-comfy node install comfyui-controlnet-aux         # ControlNet preprocessors
-comfy node install comfyui-essentials             # common helpers
-comfy node update all                            # update all nodes
+comfy node install comfyui-impact-pack             # popular utility pack
+comfy node install comfyui-animatediff-evolved     # video generation
+comfy node install comfyui-controlnet-aux          # ControlNet preprocessors
+comfy node install comfyui-essentials              # common helpers
+comfy node update all
+comfy node install-deps --workflow=workflow.json   # install everything a workflow needs
 ```

-Check what's installed:
-```bash
-comfy node show installed
-```
-
-Install deps for a specific workflow:
-```bash
-comfy node install-deps --workflow=workflow_api.json
-```
-
---
-
-### Post-Install: Verify Setup
+### Post-Install: Verify

 ```bash
-# Check server is responsive
-curl -s http://127.0.0.1:8188/system_stats | python3 -m json.tool
+python3 scripts/health_check.py
+# → comfy_cli on PATH? server reachable? checkpoints? smoke test?

-# Check a workflow's dependencies
-python3 scripts/check_deps.py workflow_api.json --host 127.0.0.1 --port 8188
+python3 scripts/check_deps.py my_workflow.json
+# → are this workflow's nodes/models/embeddings installed?

-# Test a generation
 python3 scripts/run_workflow.py \
-  --workflow workflow_api.json \
-  --args '{"prompt": "test image, high quality"}' \
+  --workflow workflows/sd15_txt2img.json \
+  --args '{"prompt": "test", "steps": 4}' \
  --output-dir ./test-outputs
 ```

 ## Image Upload (img2img / Inpainting)

-Upload files directly via REST:
+The simplest way is to use `--input-image` with `run_workflow.py`:

 ```bash
-# Upload input image
+python3 scripts/run_workflow.py \
+  --workflow workflows/sdxl_img2img.json \
+  --input-image image=./photo.png \
+  --args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
+```
+
+The flag uploads `photo.png`, then injects its server-side filename into
+whatever schema parameter is named `image`. For inpainting, pass both:
+
+```bash
+python3 scripts/run_workflow.py \
+  --workflow workflows/sdxl_inpaint.json \
+  --input-image image=./photo.png \
+  --input-image mask_image=./mask.png \
+  --args '{"prompt": "fill with flowers"}'
+```
+
+Manual upload via REST:
+```bash
 curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
 # Returns: {"name": "photo.png", "subfolder": "", "type": "input"}

-# Upload mask for inpainting
-curl -X POST "http://127.0.0.1:8188/upload/mask" \
-  -F "image=@mask.png" -F "type=input" \
-  -F 'original_ref={"filename":"photo.png","subfolder":"","type":"input"}'
-```
-
-Then reference the uploaded filename in workflow args:
-```bash
-python3 scripts/run_workflow.py --workflow inpaint.json \
-  --args '{"image": "photo.png", "mask": "mask.png", "prompt": "fill with flowers"}'
-```
-
-## Cloud Execution
-
-Base URL: `https://cloud.comfy.org`
-Auth: `X-API-Key` header
-
-```bash
-# Submit workflow
-python3 scripts/run_workflow.py \
-  --workflow workflow_api.json \
-  --args '{"prompt": "cyberpunk city"}' \
-  --host https://cloud.comfy.org \
-  --api-key "$COMFY_CLOUD_API_KEY" \
-  --output-dir ./outputs \
-  --timeout 300
-
-# Upload image for cloud workflows
+# Cloud equivalent:
 curl -X POST "https://cloud.comfy.org/api/upload/image" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
-  -F "image=@input.png" -F "type=input" -F "overwrite=true"
+  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
 ```

-Concurrent job limits:
-| Tier | Concurrent Jobs |
-|------|----------------|
-| Free/Standard | 1 |
-| Creator | 3 |
-| Pro | 5 |
+## Cloud Specifics

-Extra submissions queue automatically.
+- **Base URL:** `https://cloud.comfy.org`
+- **Auth:** `X-API-Key` header (or `?token=KEY` for WebSocket)
+- **API key:** set `$COMFY_CLOUD_API_KEY` once and the scripts pick it up automatically
+- **Output download:** `/api/view` returns a 302 to a signed URL; the scripts
+  follow it and strip `X-API-Key` before fetching from the storage backend
+  (don't leak the API key to S3/CloudFront).
+- **Endpoint differences from local ComfyUI:**
+  - `/api/object_info`, `/api/queue`, `/api/userdata` — **403 on free tier**;
+    paid only.
+  - `/history` is renamed to `/history_v2` on cloud (the scripts route
+    automatically).
+  - `/models/<folder>` is renamed to `/experiment/models/<folder>` on cloud
+    (the scripts route automatically).
+  - `clientId` in WebSocket is currently ignored — all connections for a
+    user receive the same broadcast. Filter by `prompt_id` client-side.
+  - `subfolder` is accepted on uploads but ignored — cloud has a flat namespace.
+- **Concurrent jobs:** Free/Standard: 1, Creator: 3, Pro: 5. Extras queue
+  automatically. Use `run_batch.py --parallel N` to saturate your tier.

 ## Queue & System Management

 ```bash
-# Check queue
+# Local
 curl -s http://127.0.0.1:8188/queue | python3 -m json.tool
-
-# Clear pending queue
-curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'
-
-# Cancel running job
-curl -X POST http://127.0.0.1:8188/interrupt
-
-# Free GPU memory (unload all models)
-curl -X POST http://127.0.0.1:8188/free -H "Content-Type: application/json" \
+curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'    # cancel pending
+curl -X POST http://127.0.0.1:8188/interrupt                      # cancel running
+curl -X POST http://127.0.0.1:8188/free \
+  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

-# System stats (VRAM, RAM, GPU info)
-curl -s http://127.0.0.1:8188/system_stats | python3 -m json.tool
+# Cloud — same paths under /api/, plus:
+python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
 ```

 ## Pitfalls

-1. **API format required** — `comfy run` and the scripts only accept API-format workflow JSON.
-   If the user has editor format (from "Save" not "Save (API Format)"), they need to
-   re-export. Check: API format has `class_type` in each node object, editor format has
-   top-level `nodes` and `links` arrays.
+1. **API format required** — every script and the `/api/prompt` endpoint expect
+   API-format workflow JSON. The scripts detect editor format (top-level
+   `nodes` and `links` arrays) and tell you to re-export via
+   "Workflow → Export (API)" (newer UI) or "Save (API Format)" (older UI).

-2. **Server must be running** — All execution requires a live server. `comfy launch --background`
-   starts one. Check with `curl http://127.0.0.1:8188/system_stats`.
+2. **Server must be running** — all execution requires a live server.
+   `comfy launch --background` starts one. Verify with
+   `curl http://127.0.0.1:8188/system_stats`.

-3. **Model names are exact** — Case-sensitive, includes file extension. Use
+3. **Model names are exact** — case-sensitive, includes file extension.
+   `check_deps.py` does fuzzy matching (with/without extension and folder
+   prefix), but the workflow itself must use the canonical name. Use
   `comfy model list` to discover what's installed.

-4. **Missing custom nodes** — "class_type not found" means a required node isn't installed.
-   Run `check_deps.py` to find what's missing, then `comfy node install <name>`.
+4. **Missing custom nodes** — "class_type not found" means a required node
+   isn't installed. `check_deps.py` reports which package to install;
+   `auto_fix_deps.py` runs the install for you.

-5. **Working directory** — `comfy-cli` auto-detects the ComfyUI workspace. If commands
-   fail with "no workspace found", use `comfy --workspace /path/to/ComfyUI <command>`
-   or `comfy set-default /path/to/ComfyUI`.
+5. **Working directory** — `comfy-cli` auto-detects the ComfyUI workspace.
+   If commands fail with "no workspace found", use
+   `comfy --workspace /path/to/ComfyUI <command>` or
+   `comfy set-default /path/to/ComfyUI`.

-6. **Cloud vs local output download** — Cloud `/api/view` returns a 302 redirect to a
-   signed URL. Always follow redirects (`curl -L`). The `run_workflow.py` script handles
-   this automatically.
+6. **Cloud free-tier API limits** — `/api/prompt`, `/api/view`, `/api/upload/*`,
+   `/api/object_info` all return 403 on free accounts. `health_check.py` and
+   `check_deps.py` handle this gracefully and surface a clear message.

-7. **Timeout for video/audio** — Long generations (video, high step counts) can take
-   minutes. Pass `--timeout 600` to `run_workflow.py`. Default is 120 seconds.
+7. **Timeout for video/audio workflows** — auto-detected when an output node
+   is `VHS_VideoCombine`, `SaveVideo`, etc.; the default jumps from 300 s to
+   900 s. Override explicitly with `--timeout 1800`.

-8. **tracking prompt** — First run of `comfy` may prompt for analytics tracking consent.
-   Use `comfy --skip-prompt tracking disable` to skip it non-interactively.
+8. **Path traversal in output filenames** — server-supplied filenames are
+   passed through `safe_path_join` to refuse anything escaping `--output-dir`.
+   Keep this protection on — workflows with custom save nodes can produce
+   arbitrary paths.

-9. **comfy-cli invocation via uvx** — If comfy-cli is not installed globally, invoke with
-   `uvx --from comfy-cli comfy <command>`. All examples in this skill use bare `comfy`
-   but prepend `uvx --from comfy-cli` if needed.
+9. **Workflow JSON is arbitrary code** — custom nodes run Python, so
+   submitting an unknown workflow has the same trust profile as `eval`.
+   Inspect workflows from untrusted sources before running.
+
+10. **Auto-randomized seed** — pass `seed: -1` in `--args` (or use
+    `--randomize-seed` and omit the seed) to get a fresh seed per run.
+    The actual seed is logged to stderr.
+
+11. **`tracking` prompt** — first run of `comfy` may prompt for analytics.
+    Use `comfy --skip-prompt tracking disable` to skip non-interactively.
+    `comfyui_setup.sh` does this for you.

 ## Verification Checklist

+Use `python3 scripts/health_check.py` to run the whole list at once. Manual:
+
 - [ ] `hardware_check.py` verdict is `ok` OR the user explicitly chose Comfy Cloud
- [ ] `comfy` available on PATH (or `uvx --from comfy-cli comfy --help` works)
- [ ] `curl http://127.0.0.1:8188/system_stats` returns JSON
- [ ] `comfy model list` shows at least one checkpoint
- [ ] Workflow JSON is in API format (has `class_type` keys)
- [ ] `check_deps.py` reports no missing nodes/models
- [ ] Test run completes and outputs are saved
+- [ ] `comfy --version` works (or `uvx --from comfy-cli comfy --help`)
+- [ ] `curl http://HOST:PORT/system_stats` returns JSON
+- [ ] `comfy model list` shows at least one checkpoint (local) OR
+      `/api/experiment/models/checkpoints` returns models (cloud)
+- [ ] Workflow JSON is in API format
+- [ ] `check_deps.py` reports `is_ready: true` (or only `node_check_skipped`
+      on cloud free tier)
+- [ ] Test run with a small workflow completes; outputs land in `--output-dir`
@@ -0,0 +1,170 @@
+---
+title: "Kanban Orchestrator"
+sidebar_label: "Kanban Orchestrator"
+description: "Decomposition playbook + specialist-roster conventions + anti-temptation rules for an orchestrator profile routing work through Kanban"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Kanban Orchestrator
+
+Decomposition playbook + specialist-roster conventions + anti-temptation rules for an orchestrator profile routing work through Kanban. The "don't do the work yourself" rule and the basic lifecycle are auto-injected into every kanban worker's system prompt; this skill is the deeper playbook when you're specifically playing the orchestrator role.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/devops/kanban-orchestrator` |
+| Version | `2.0.0` |
+| Tags | `kanban`, `multi-agent`, `orchestration`, `routing` |
+| Related skills | [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Kanban Orchestrator — Decomposition Playbook
+
+> The **core worker lifecycle** (including the `kanban_create` fan-out pattern and the "decompose, don't execute" rule) is auto-injected into every kanban process via the `KANBAN_GUIDANCE` system-prompt block. This skill is the deeper playbook when you're an orchestrator profile whose whole job is routing.
+
+## When to use the board (vs. just doing the work)
+
+Create Kanban tasks when any of these are true:
+
+1. **Multiple specialists are needed.** Research + analysis + writing is three profiles.
+2. **The work should survive a crash or restart.** Long-running, recurring, or important.
+3. **The user might want to interject.** Human-in-the-loop at any step.
+4. **Multiple subtasks can run in parallel.** Fan-out for speed.
+5. **Review / iteration is expected.** A reviewer profile loops on drafter output.
+6. **The audit trail matters.** Board rows persist in SQLite forever.
+
+If *none* of those apply — it's a small one-shot reasoning task — use `delegate_task` instead or answer the user directly.
+
+## The anti-temptation rules
+
+Your job description says "route, don't execute." The rules that enforce that:
+
+- **Do not execute the work yourself.** Your restricted toolset usually doesn't even include terminal/file/code/web for implementation. If you find yourself "just fixing this quickly" — stop and create a task for the right specialist.
+- **For any concrete task, create a Kanban task and assign it.** Every single time.
+- **If no specialist fits, ask the user which profile to create.** Do not default to doing it yourself under "close enough."
+- **Decompose, route, and summarize — that's the whole job.**
+
+## The standard specialist roster (convention)
+
+Unless the user's setup has customized profiles, assume these exist. Adjust to whatever the user actually has — ask if you're unsure.
+
+| Profile | Does | Typical workspace |
+|---|---|---|
+| `researcher` | Reads sources, gathers facts, writes findings | `scratch` |
+| `analyst` | Synthesizes, ranks, de-dupes. Consumes multiple `researcher` outputs | `scratch` |
+| `writer` | Drafts prose in the user's voice | `scratch` or `dir:` into their Obsidian vault |
+| `reviewer` | Reads output, leaves findings, gates approval | `scratch` |
+| `backend-eng` | Writes server-side code | `worktree` |
+| `frontend-eng` | Writes client-side code | `worktree` |
+| `ops` | Runs scripts, manages services, handles deployments | `dir:` into ops scripts repo |
+| `pm` | Writes specs, acceptance criteria | `scratch` |
+
+## Decomposition playbook
+
+### Step 1 — Understand the goal
+
+Ask clarifying questions if the goal is ambiguous. Cheap to ask; expensive to spawn the wrong fleet.
+
+### Step 2 — Sketch the task graph
+
+Before creating anything, draft the graph out loud (in your response to the user). Example for "Analyze whether we should migrate to Postgres":
+
+```
+T1  researcher        research: Postgres cost vs current
+T2  researcher        research: Postgres performance vs current
+T3  analyst           synthesize migration recommendation       parents: T1, T2
+T4  writer            draft decision memo                       parents: T3
+```
+
+Show this to the user. Let them correct it before you create anything.
+
+### Step 3 — Create tasks and link
+
+```python
+t1 = kanban_create(
+    title="research: Postgres cost vs current",
+    assignee="researcher",
+    body="Compare estimated infrastructure costs, migration costs, and ongoing ops costs over a 3-year window. Sources: AWS/GCP pricing, team time estimates, current Postgres bills from peers.",
+    tenant=os.environ.get("HERMES_TENANT"),
+)["task_id"]
+
+t2 = kanban_create(
+    title="research: Postgres performance vs current",
+    assignee="researcher",
+    body="Compare query latency, throughput, and scaling characteristics at our expected data volume (~500GB, 10k QPS peak). Sources: benchmark papers, public case studies, pgbench results if easy.",
+)["task_id"]
+
+t3 = kanban_create(
+    title="synthesize migration recommendation",
+    assignee="analyst",
+    body="Read the findings from T1 (cost) and T2 (performance). Produce a 1-page recommendation with explicit trade-offs and a go/no-go call.",
+    parents=[t1, t2],
+)["task_id"]
+
+t4 = kanban_create(
+    title="draft decision memo",
+    assignee="writer",
+    body="Turn the analyst's recommendation into a 2-page memo for the CTO. Match the tone of previous decision memos in the team's knowledge base.",
+    parents=[t3],
+)["task_id"]
+```
+
+`parents=[...]` gates promotion — children stay in `todo` until every parent reaches `done`, then auto-promote to `ready`. No manual coordination needed; the dispatcher and dependency engine handle it.
+
+### Step 4 — Complete your own task
+
+If you were spawned as a task yourself (e.g. `planner` profile was assigned `T0: "investigate Postgres migration"`), mark it done with a summary of what you created:
+
+```python
+kanban_complete(
+    summary="decomposed into T1-T4: 2 researchers parallel, 1 analyst on their outputs, 1 writer on the recommendation",
+    metadata={
+        "task_graph": {
+            "T1": {"assignee": "researcher", "parents": []},
+            "T2": {"assignee": "researcher", "parents": []},
+            "T3": {"assignee": "analyst", "parents": ["T1", "T2"]},
+            "T4": {"assignee": "writer", "parents": ["T3"]},
+        },
+    },
+)
+```
+
+### Step 5 — Report back to the user
+
+Tell them what you created in plain prose:
+
+> I've queued 4 tasks:
+> - **T1** (researcher): cost comparison
+> - **T2** (researcher): performance comparison, in parallel with T1
+> - **T3** (analyst): synthesizes T1 + T2 into a recommendation
+> - **T4** (writer): turns T3 into a CTO memo
+>
+> The dispatcher will pick up T1 and T2 now. T3 starts when both finish. You'll get a gateway ping when T4 completes. Use the dashboard or `hermes kanban tail <id>` to follow along.
+
+## Common patterns
+
+**Fan-out + fan-in (research → synthesize):** N `researcher` tasks with no parents, one `analyst` task with all of them as parents.
+
+**Pipeline with gates:** `pm → backend-eng → reviewer`. Each stage's `parents=[previous_task]`. Reviewer blocks or completes; if reviewer blocks, the operator unblocks with feedback and respawns.
+
+**Same-profile queue:** 50 tasks, all assigned to `translator`, no dependencies between them. Dispatcher serializes — translator processes them in priority order, accumulating experience in their own memory.
+
+**Human-in-the-loop:** Any task can `kanban_block()` to wait for input. Dispatcher respawns after `/unblock`. The comment thread carries the full context.
+
+## Pitfalls
+
+**Reassignment vs. new task.** If a reviewer blocks with "needs changes," create a NEW task linked from the reviewer's task — don't re-run the same task with a stern look. The new task is assigned to the original implementer profile.
+
+**Argument order for links.** `kanban_link(parent_id=..., child_id=...)` — parent first. Mixing them up demotes the wrong task to `todo`.
+
+**Don't pre-create the whole graph if the shape depends on intermediate findings.** If T3's structure depends on what T1 and T2 find, let T3 exist as a "synthesize findings" task whose own first step is to read parent handoffs and plan the rest. Orchestrators can spawn orchestrators.
+
+**Tenant inheritance.** If `HERMES_TENANT` is set in your env, pass `tenant=os.environ.get("HERMES_TENANT")` on every `kanban_create` call so child tasks stay in the same namespace.
@@ -0,0 +1,152 @@
+---
+title: "Kanban Worker — Pitfalls, examples, and edge cases for Hermes Kanban workers"
+sidebar_label: "Kanban Worker"
+description: "Pitfalls, examples, and edge cases for Hermes Kanban workers"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Kanban Worker
+
+Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper detail on specific scenarios.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/devops/kanban-worker` |
+| Version | `2.0.0` |
+| Tags | `kanban`, `multi-agent`, `collaboration`, `workflow`, `pitfalls` |
+| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Kanban Worker — Pitfalls and Examples
+
+> You're seeing this skill because the Hermes Kanban dispatcher spawned you as a worker with `--skills kanban-worker` — it's loaded automatically for every dispatched worker. The **lifecycle** (6 steps: orient → work → heartbeat → block/complete) also lives in the `KANBAN_GUIDANCE` block that's auto-injected into your system prompt. This skill is the deeper detail: good handoff shapes, retry diagnostics, edge cases.
+
+## Workspace handling
+
+Your workspace kind determines how you should behave inside `$HERMES_KANBAN_WORKSPACE`:
+
+| Kind | What it is | How to work |
+|---|---|---|
+| `scratch` | Fresh tmp dir, yours alone | Read/write freely; it gets GC'd when the task is archived. |
+| `dir:<path>` | Shared persistent directory | Other runs will read what you write. Treat it like long-lived state. Path is guaranteed absolute (the kernel rejects relative paths). |
+| `worktree` | Git worktree at the resolved path | If `.git` doesn't exist, run `git worktree add <path> <branch>` from the main repo first, then cd and work normally. Commit work here. |
+
+## Tenant isolation
+
+If `$HERMES_TENANT` is set, the task belongs to a tenant namespace. When reading or writing persistent memory, prefix memory entries with the tenant so context doesn't leak across tenants:
+
+- Good: `business-a: Acme is our biggest customer`
+- Bad (leaks): `Acme is our biggest customer`
+
+## Good summary + metadata shapes
+
+The `kanban_complete(summary=..., metadata=...)` handoff is how downstream workers read what you did. Patterns that work:
+
+**Coding task:**
+```python
+kanban_complete(
+    summary="shipped rate limiter — token bucket, keys on user_id with IP fallback, 14 tests pass",
+    metadata={
+        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
+        "tests_run": 14,
+        "tests_passed": 14,
+        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
+    },
+)
+```
+
+**Research task:**
+```python
+kanban_complete(
+    summary="3 competing libraries reviewed; vLLM wins on throughput, SGLang on latency, Tensorrt-LLM on memory efficiency",
+    metadata={
+        "sources_read": 12,
+        "recommendation": "vLLM",
+        "benchmarks": {"vllm": 1.0, "sglang": 0.87, "trtllm": 0.72},
+    },
+)
+```
+
+**Review task:**
+```python
+kanban_complete(
+    summary="reviewed PR #123; 2 blocking issues found (SQL injection in /search, missing CSRF on /settings)",
+    metadata={
+        "pr_number": 123,
+        "findings": [
+            {"severity": "critical", "file": "api/search.py", "line": 42, "issue": "raw SQL concat"},
+            {"severity": "high", "file": "api/settings.py", "issue": "missing CSRF middleware"},
+        ],
+        "approved": False,
+    },
+)
+```
+
+Shape `metadata` so downstream parsers (reviewers, aggregators, schedulers) can use it without re-reading your prose.
+
+## Block reasons that get answered fast
+
+Bad: `"stuck"` — the human has no context.
+
+Good: one sentence naming the specific decision you need. Leave longer context as a comment instead.
+
+```python
+kanban_comment(
+    task_id=os.environ["HERMES_KANBAN_TASK"],
+    body="Full context: I have user IPs from Cloudflare headers but some users are behind NATs with thousands of peers. Keying on IP alone causes false positives.",
+)
+kanban_block(reason="Rate limit key choice: IP (simple, NAT-unsafe) or user_id (requires auth, skips anonymous endpoints)?")
+```
+
+The block message is what appears in the dashboard / gateway notifier. The comment is the deeper context a human reads when they open the task.
+
+## Heartbeats worth sending
+
+Good heartbeats name progress: `"epoch 12/50, loss 0.31"`, `"scanned 1.2M/2.4M rows"`, `"uploaded 47/120 videos"`.
+
+Bad heartbeats: `"still working"`, empty notes, sub-second intervals. Every few minutes max; skip entirely for tasks under ~2 minutes.
+
+## Retry scenarios
+
+If you open the task and `kanban_show` returns `runs: [...]` with one or more closed runs, you're a retry. The prior runs' `outcome` / `summary` / `error` tell you what didn't work. Don't repeat that path. Typical retry diagnostics:
+
+- `outcome: "timed_out"` — the previous attempt hit `max_runtime_seconds`. You may need to chunk the work or shorten it.
+- `outcome: "crashed"` — OOM or segfault. Reduce memory footprint.
+- `outcome: "spawn_failed"` + `error: "..."` — usually a profile config issue (missing credential, bad PATH). Ask the human via `kanban_block` instead of retrying blindly.
+- `outcome: "reclaimed"` + `summary: "task archived..."` — operator archived the task out from under the previous run; you probably shouldn't be running at all, check status carefully.
+- `outcome: "blocked"` — a previous attempt blocked; the unblock comment should be in the thread by now.
+
+## Do NOT
+
+- Call `delegate_task` as a substitute for `kanban_create`. `delegate_task` is for short reasoning subtasks inside YOUR run; `kanban_create` is for cross-agent handoffs that outlive one API loop.
+- Modify files outside `$HERMES_KANBAN_WORKSPACE` unless the task body says to.
+- Create follow-up tasks assigned to yourself — assign to the right specialist.
+- Complete a task you didn't actually finish. Block it instead.
+
+## Pitfalls
+
+**Task state can change between dispatch and your startup.** Between when the dispatcher claimed and when your process actually booted, the task may have been blocked, reassigned, or archived. Always `kanban_show` first. If it reports `blocked` or `archived`, stop — you shouldn't be running.
+
+**Workspace may have stale artifacts.** Especially `dir:` and `worktree` workspaces can have files from previous runs. Read the comment thread — it usually explains why you're running again and what state the workspace is in.
+
+**Don't rely on the CLI when the guidance is available.** The `kanban_*` tools work across all terminal backends (Docker, Modal, SSH). `hermes kanban <verb>` from your terminal tool will fail in containerized backends because the CLI isn't installed there. When in doubt, use the tool.
+
+## CLI fallback (for scripting)
+
+Every tool has a CLI equivalent for human operators and scripts:
+- `kanban_show` ↔ `hermes kanban show <id> --json`
+- `kanban_complete` ↔ `hermes kanban complete <id> --summary "..." --metadata '{...}'`
+- `kanban_block` ↔ `hermes kanban block <id> "reason"`
+- `kanban_create` ↔ `hermes kanban create "title" --assignee <profile> [--parent <id>]`
+- etc.
+
+Use the tools from inside an agent; the CLI exists for the human at the terminal.
@@ -0,0 +1,231 @@
+---
+title: "Here.Now — Publish static sites to {slug}"
+sidebar_label: "Here.Now"
+description: "Publish static sites to {slug}"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Here.Now
+
+Publish static sites to &#123;slug&#125;.here.now and store private files in cloud Drives for agent-to-agent handoff.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/here-now` |
+| Path | `optional-skills/productivity/here-now` |
+| Version | `1.15.3` |
+| Author | here.now |
+| License | MIT |
+| Platforms | macos, linux |
+| Tags | `here.now`, `herenow`, `publish`, `deploy`, `hosting`, `static-site`, `web`, `share`, `URL`, `drive`, `storage` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# here.now
+
+here.now lets agents publish websites and store private files in cloud Drives.
+
+Use here.now for two jobs:
+
+- **Sites**: publish websites and files at `{slug}.here.now`.
+- **Drives**: store private agent files in cloud folders.
+
+## Current docs
+
+**Before answering questions about here.now capabilities, features, or workflows, read the current docs:**
+
+→ **https://here.now/docs**
+
+Read the docs:
+
+- at the first here.now-related interaction in a conversation
+- any time the user asks how to do something
+- any time the user asks what is possible, supported, or recommended
+- before telling the user a feature is unsupported
+
+Topics that require current docs (do not rely on local skill text alone):
+
+- Drives and Drive sharing
+- custom domains
+- payments and payment gating
+- forking
+- proxy routes and service variables
+- handles and links
+- limits and quotas
+- SPA routing
+- error handling and remediation
+- feature availability
+
+**If docs and live API behavior disagree, trust the live API behavior.**
+
+If the docs fetch fails or times out, continue with the local skill and live API/script output. Prefer live API behavior for active operations.
+
+## Requirements
+
+- Required binaries: `curl`, `file`, `jq`
+- Optional environment variable: `$HERENOW_API_KEY`
+- Optional Drive token variable: `$HERENOW_DRIVE_TOKEN`
+- Optional credentials file: `~/.herenow/credentials`
+- Skill helper paths:
+  - `${HERMES_SKILL_DIR}/scripts/publish.sh` for publishing sites
+  - `${HERMES_SKILL_DIR}/scripts/drive.sh` for private Drive storage
+
+## Create a site
+
+```bash
+PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
+bash "$PUBLISH" {file-or-dir} --client hermes
+```
+
+Outputs the live URL (e.g. `https://bright-canvas-a7k2.here.now/`).
+
+Under the hood this is a three-step flow: create/update -> upload files -> finalize. A site is not live until finalize succeeds.
+
+Without an API key this creates an **anonymous site** that expires in 24 hours.
+With a saved API key, the site is permanent.
+
+**File structure:** For HTML sites, place `index.html` at the root of the directory you publish, not inside a subdirectory. The directory's contents become the site root. For example, publish `my-site/` where `my-site/index.html` exists — don't publish a parent folder that contains `my-site/`.
+
+You can also publish raw files without any HTML. Single files get a rich auto-viewer (images, PDF, video, audio). Multiple files get an auto-generated directory listing with folder navigation and an image gallery.
+
+## Update an existing site
+
+```bash
+PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
+bash "$PUBLISH" {file-or-dir} --slug {slug} --client hermes
+```
+
+The script auto-loads the `claimToken` from `.herenow/state.json` when updating anonymous sites. Pass `--claim-token {token}` to override.
+
+Authenticated updates require a saved API key.
+
+## Use a Drive
+
+Use a Drive when the user wants private cloud storage for agent files: documents, context, memory, plans, assets, media, research, code, and anything else that should persist without being published as a website.
+
+Every signed-in account has a default Drive named `My Drive`.
+
+```bash
+DRIVE="${HERMES_SKILL_DIR}/scripts/drive.sh"
+bash "$DRIVE" default
+bash "$DRIVE" ls "My Drive"
+bash "$DRIVE" put "My Drive" notes/today.md --from ./notes/today.md
+bash "$DRIVE" cat "My Drive" notes/today.md
+bash "$DRIVE" share "My Drive" --perms write --prefix notes/ --ttl 7d
+```
+
+Use scoped Drive tokens for agent-to-agent handoff. If you receive a `herenow_drive` share block, use its `token` as `Authorization: Bearer <token>` against `api_base`, respect `pathPrefix` when present, and preserve ETags on writes. A `pathPrefix` of `null` means full-Drive access. If the skill is available, prefer `drive.sh`; otherwise call the listed API operations directly.
+
+## API key storage
+
+The publish script reads the API key from these sources (first match wins):
+
+1. `--api-key {key}` flag (CI/scripting only — avoid in interactive use)
+2. `$HERENOW_API_KEY` environment variable
+3. `~/.herenow/credentials` file (recommended for agents)
+
+To store a key, write it to the credentials file:
+
+```bash
+mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
+```
+
+**IMPORTANT**: After receiving an API key, save it immediately — run the command above yourself. Do not ask the user to run it manually. Avoid passing the key via CLI flags (e.g. `--api-key`) in interactive sessions; the credentials file is the preferred storage method.
+
+Never commit credentials or local state files (`~/.herenow/credentials`, `.herenow/state.json`) to source control.
+
+## Getting an API key
+
+To upgrade from anonymous (24h) to permanent sites:
+
+1. Ask the user for their email address.
+2. Request a one-time sign-in code:
+
+```bash
+curl -sS https://here.now/api/auth/agent/request-code \
+  -H "content-type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+3. Tell the user: "Check your inbox for a sign-in code from here.now and paste it here."
+4. Verify the code and get the API key:
+
+```bash
+curl -sS https://here.now/api/auth/agent/verify-code \
+  -H "content-type: application/json" \
+  -d '{"email":"user@example.com","code":"ABCD-2345"}'
+```
+
+5. Save the returned `apiKey` yourself (do not ask the user to do this):
+
+```bash
+mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
+```
+
+## State file
+
+After every site create/update, the script writes to `.herenow/state.json` in the working directory:
+
+```json
+{
+  "publishes": {
+    "bright-canvas-a7k2": {
+      "siteUrl": "https://bright-canvas-a7k2.here.now/",
+      "claimToken": "abc123",
+      "claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123",
+      "expiresAt": "2026-02-18T01:00:00.000Z"
+    }
+  }
+}
+```
+
+Before creating or updating sites, you may check this file to find prior slugs.
+Treat `.herenow/state.json` as internal cache only.
+Never present this local file path as a URL, and never use it as source of truth for auth mode, expiry, or claim URL.
+
+## What to tell the user
+
+For published sites:
+
+- Always share the `siteUrl` from the current script run.
+- Read and follow `publish_result.*` lines from script stderr to determine auth mode.
+- When `publish_result.auth_mode=authenticated`: tell the user the site is **permanent** and saved to their account. No claim URL is needed.
+- When `publish_result.auth_mode=anonymous`: tell the user the site **expires in 24 hours**. Share the claim URL (if `publish_result.claim_url` is non-empty and starts with `https://`) so they can keep it permanently. Warn that claim tokens are only returned once and cannot be recovered.
+- Never tell the user to inspect `.herenow/state.json` for claim URLs or auth status.
+
+For Drives:
+
+- Do not describe Drive files as public URLs.
+- Tell the user Drive contents are private unless shared with a scoped token.
+- When sharing access with another agent, prefer a scoped token with a narrow `pathPrefix` and short TTL.
+
+## publish.sh options
+
+| Flag                   | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `--slug {slug}`        | Update an existing site instead of creating |
+| `--claim-token {token}`| Override claim token for anonymous updates    |
+| `--title {text}`       | Viewer title (non-HTML sites)             |
+| `--description {text}` | Viewer description                            |
+| `--ttl {seconds}`      | Set expiry (authenticated only)               |
+| `--client {name}`      | Agent name for attribution (e.g. `hermes`)    |
+| `--base-url {url}`     | API base URL (default: `https://here.now`)    |
+| `--allow-nonherenow-base-url` | Allow sending auth to non-default `--base-url` |
+| `--api-key {key}`      | API key override (prefer credentials file)    |
+| `--spa`                | Enable SPA routing (serve index.html for unknown paths) |
+| `--forkable`           | Allow others to fork this site                           |
+
+## Beyond publish.sh
+
+For Drive operations, use `drive.sh` or the Drive API. For broader account and site management — delete, metadata, passwords, payments, domains, handles, links, variables, proxy routes, forking, duplication, and more — see the current docs:
+
+→ **https://here.now/docs**
+
+Full docs: https://here.now/docs
@@ -0,0 +1,376 @@
+---
+title: "Shopify — Shopify Admin & Storefront GraphQL APIs via curl"
+sidebar_label: "Shopify"
+description: "Shopify Admin & Storefront GraphQL APIs via curl"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Shopify
+
+Shopify Admin & Storefront GraphQL APIs via curl. Products, orders, customers, inventory, metafields.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/shopify` |
+| Path | `optional-skills/productivity/shopify` |
+| Version | `1.0.0` |
+| Author | community |
+| License | MIT |
+| Tags | `Shopify`, `E-commerce`, `Commerce`, `API`, `GraphQL` |
+| Related skills | [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable), [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Shopify — Admin & Storefront GraphQL APIs
+
+Work with Shopify stores directly through `curl`: list products, manage inventory, pull orders, update customers, read metafields. No SDK, no app framework — just the GraphQL endpoint and a custom-app access token.
+
+The REST Admin API is legacy since 2024-04 and only receives security fixes. **Use GraphQL Admin** for all admin work. Use **Storefront GraphQL** for read-only customer-facing queries (products, collections, cart).
+
+## Prerequisites
+
+1. In Shopify admin: **Settings → Apps and sales channels → Develop apps → Create an app**.
+2. Click **Configure Admin API scopes**, select what you need (examples below), save.
+3. **Install app** → the Admin API access token appears ONCE. Copy it immediately — Shopify will never show it again. Tokens start with `shpat_`.
+4. Save to `~/.hermes/.env`:
+   ```
+   SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx
+   SHOPIFY_STORE_DOMAIN=my-store.myshopify.com
+   SHOPIFY_API_VERSION=2026-01
+   ```
+
+> **Heads up:** As of January 1, 2026, new "legacy custom apps" created in the Shopify admin are gone. New setups should use the **Dev Dashboard** (`shopify.dev/docs/apps/build/dev-dashboard`). Existing admin-created apps keep working. If the user's shop has no existing custom app and it's after 2026-01-01, direct them to Dev Dashboard instead of the admin flow.
+
+Common scopes by task:
+- Products / collections: `read_products`, `write_products`
+- Inventory: `read_inventory`, `write_inventory`, `read_locations`
+- Orders: `read_orders`, `write_orders` (30 most recent without `read_all_orders`)
+- Customers: `read_customers`, `write_customers`
+- Draft orders: `read_draft_orders`, `write_draft_orders`
+- Fulfillments: `read_fulfillments`, `write_fulfillments`
+- Metafields / metaobjects: covered by the matching resource scopes
+
+## API Basics
+
+- **Endpoint:** `https://$SHOPIFY_STORE_DOMAIN/admin/api/$SHOPIFY_API_VERSION/graphql.json`
+- **Auth header:** `X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN` (NOT `Authorization: Bearer`)
+- **Method:** always `POST`, always `Content-Type: application/json`, body is `{"query": "...", "variables": {...}}`
+- **HTTP 200 does not mean success.** GraphQL returns errors in a top-level `errors` array and per-field `userErrors`. Always check both.
+- **IDs are GID strings:** `gid://shopify/Product/10079467700516`, `gid://shopify/Variant/...`, `gid://shopify/Order/...`. Pass these verbatim — don't strip the prefix.
+- **Rate limit:** calculated via query cost (leaky bucket). Each response has `extensions.cost` with `requestedQueryCost`, `actualQueryCost`, `throttleStatus.{currentlyAvailable, maximumAvailable, restoreRate}`. Back off when `currentlyAvailable` drops below your next query's cost. Standard shops = 100 points bucket, 50/s restore; Plus = 1000/100.
+
+Base curl pattern (reusable):
+
+```bash
+shop_gql() {
+  local query="$1"
+  local variables="${2:-{}}"
+  curl -sS -X POST \
+    "https://${SHOPIFY_STORE_DOMAIN}/admin/api/${SHOPIFY_API_VERSION:-2026-01}/graphql.json" \
+    -H "Content-Type: application/json" \
+    -H "X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}" \
+    --data "$(jq -nc --arg q "$query" --argjson v "$variables" '{query: $q, variables: $v}')"
+}
+```
+
+Pipe through `jq` for readable output. `-sS` keeps errors visible but hides the progress bar.
+
+## Discovery
+
+### Shop info + current API version
+```bash
+shop_gql '{ shop { name myshopifyDomain primaryDomain { url } currencyCode plan { displayName } } }' | jq
+```
+
+### List all supported API versions
+```bash
+shop_gql '{ publicApiVersions { handle supported } }' | jq '.data.publicApiVersions[] | select(.supported)'
+```
+
+## Products
+
+### Search products (first 20 matching query)
+```bash
+shop_gql '
+query($q: String!) {
+  products(first: 20, query: $q) {
+    edges { node { id title handle status totalInventory variants(first: 5) { edges { node { id sku price inventoryQuantity } } } } }
+    pageInfo { hasNextPage endCursor }
+  }
+}' '{"q":"hoodie status:active"}' | jq
+```
+
+Query syntax supports `title:`, `sku:`, `vendor:`, `product_type:`, `status:active`, `tag:`, `created_at:>2025-01-01`. Full grammar: https://shopify.dev/docs/api/usage/search-syntax
+
+### Paginate products (cursor)
+```bash
+shop_gql '
+query($cursor: String) {
+  products(first: 100, after: $cursor) {
+    edges { cursor node { id handle } }
+    pageInfo { hasNextPage endCursor }
+  }
+}' '{"cursor":null}'
+# subsequent calls: pass the previous endCursor
+```
+
+### Get a product with variants + metafields
+```bash
+shop_gql '
+query($id: ID!) {
+  product(id: $id) {
+    id title handle descriptionHtml tags status
+    variants(first: 20) { edges { node { id sku price compareAtPrice inventoryQuantity selectedOptions { name value } } } }
+    metafields(first: 20) { edges { node { namespace key type value } } }
+  }
+}' '{"id":"gid://shopify/Product/10079467700516"}' | jq
+```
+
+### Create a product with one variant
+```bash
+shop_gql '
+mutation($input: ProductCreateInput!) {
+  productCreate(product: $input) {
+    product { id handle }
+    userErrors { field message }
+  }
+}' '{"input":{"title":"Test Hoodie","status":"DRAFT","vendor":"Hermes","productType":"Apparel","tags":["test"]}}'
+```
+
+Variants now have their own mutations in recent versions:
+
+```bash
+# Add variants after creating the product
+shop_gql '
+mutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
+  productVariantsBulkCreate(productId: $productId, variants: $variants) {
+    productVariants { id sku price }
+    userErrors { field message }
+  }
+}' '{"productId":"gid://shopify/Product/...","variants":[{"optionValues":[{"optionName":"Size","name":"M"}],"price":"49.00","inventoryItem":{"sku":"HD-M","tracked":true}}]}'
+```
+
+### Update price / SKU
+```bash
+shop_gql '
+mutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
+  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
+    productVariants { id sku price }
+    userErrors { field message }
+  }
+}' '{"productId":"gid://shopify/Product/...","variants":[{"id":"gid://shopify/ProductVariant/...","price":"55.00"}]}'
+```
+
+## Orders
+
+### List recent orders (last 30 by default without `read_all_orders`)
+```bash
+shop_gql '
+{
+  orders(first: 20, reverse: true, query: "financial_status:paid") {
+    edges { node {
+      id name createdAt displayFinancialStatus displayFulfillmentStatus
+      totalPriceSet { shopMoney { amount currencyCode } }
+      customer { id displayName email }
+      lineItems(first: 10) { edges { node { title quantity sku } } }
+    } }
+  }
+}' | jq
+```
+
+Useful order query filters: `financial_status:paid|pending|refunded`, `fulfillment_status:unfulfilled|fulfilled`, `created_at:>2025-01-01`, `tag:gift`, `email:foo@example.com`.
+
+### Fetch a single order with shipping address
+```bash
+shop_gql '
+query($id: ID!) {
+  order(id: $id) {
+    id name email
+    shippingAddress { name address1 address2 city province country zip phone }
+    lineItems(first: 50) { edges { node { title quantity variant { sku } originalUnitPriceSet { shopMoney { amount currencyCode } } } } }
+    transactions { id kind status amountSet { shopMoney { amount currencyCode } } }
+  }
+}' '{"id":"gid://shopify/Order/...."}' | jq
+```
+
+## Customers
+
+```bash
+# Search
+shop_gql '
+{
+  customers(first: 10, query: "email:*@example.com") {
+    edges { node { id email displayName numberOfOrders amountSpent { amount currencyCode } } }
+  }
+}'
+
+# Create
+shop_gql '
+mutation($input: CustomerInput!) {
+  customerCreate(input: $input) {
+    customer { id email }
+    userErrors { field message }
+  }
+}' '{"input":{"email":"test@example.com","firstName":"Test","lastName":"User","tags":["api-created"]}}'
+```
+
+## Inventory
+
+Inventory lives on **inventory items** tied to variants, quantities tracked per **location**.
+
+```bash
+# Get inventory for a variant across all locations
+shop_gql '
+query($id: ID!) {
+  productVariant(id: $id) {
+    id sku
+    inventoryItem {
+      id tracked
+      inventoryLevels(first: 10) {
+        edges { node { location { id name } quantities(names: ["available","on_hand","committed"]) { name quantity } } }
+      }
+    }
+  }
+}' '{"id":"gid://shopify/ProductVariant/..."}'
+```
+
+Adjust stock (delta) — uses `inventoryAdjustQuantities`:
+
+```bash
+shop_gql '
+mutation($input: InventoryAdjustQuantitiesInput!) {
+  inventoryAdjustQuantities(input: $input) {
+    inventoryAdjustmentGroup { reason changes { name delta } }
+    userErrors { field message }
+  }
+}' '{
+  "input": {
+    "reason": "correction",
+    "name": "available",
+    "changes": [{"delta": 5, "inventoryItemId": "gid://shopify/InventoryItem/...", "locationId": "gid://shopify/Location/..."}]
+  }
+}'
+```
+
+Set absolute stock (not delta) — `inventorySetQuantities`:
+
+```bash
+shop_gql '
+mutation($input: InventorySetQuantitiesInput!) {
+  inventorySetQuantities(input: $input) {
+    inventoryAdjustmentGroup { id }
+    userErrors { field message }
+  }
+}' '{"input":{"reason":"correction","name":"available","ignoreCompareQuantity":true,"quantities":[{"inventoryItemId":"gid://shopify/InventoryItem/...","locationId":"gid://shopify/Location/...","quantity":100}]}}'
+```
+
+## Metafields & Metaobjects
+
+Metafields attach custom data to resources (products, customers, orders, shop).
+
+```bash
+# Read
+shop_gql '
+query($id: ID!) {
+  product(id: $id) {
+    metafields(first: 10, namespace: "custom") {
+      edges { node { key type value } }
+    }
+  }
+}' '{"id":"gid://shopify/Product/..."}'
+
+# Write (works for any owner type)
+shop_gql '
+mutation($metafields: [MetafieldsSetInput!]!) {
+  metafieldsSet(metafields: $metafields) {
+    metafields { id key namespace }
+    userErrors { field message code }
+  }
+}' '{"metafields":[{"ownerId":"gid://shopify/Product/...","namespace":"custom","key":"care_instructions","type":"multi_line_text_field","value":"Wash cold. Tumble dry low."}]}'
+```
+
+## Storefront API (public read-only)
+
+Different endpoint, different token, used for customer-facing apps/hydrogen-style headless setups. Headers differ:
+
+- **Endpoint:** `https://$SHOPIFY_STORE_DOMAIN/api/$SHOPIFY_API_VERSION/graphql.json`
+- **Auth header (public):** `X-Shopify-Storefront-Access-Token: <public token>` — embeddable in browser
+- **Auth header (private):** `Shopify-Storefront-Private-Token: <private token>` — server-only
+
+```bash
+curl -sS -X POST \
+  "https://${SHOPIFY_STORE_DOMAIN}/api/${SHOPIFY_API_VERSION:-2026-01}/graphql.json" \
+  -H "Content-Type: application/json" \
+  -H "X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}" \
+  -d '{"query":"{ shop { name } products(first: 5) { edges { node { id title handle } } } }"}' | jq
+```
+
+## Bulk Operations
+
+For dumps larger than rate limits allow (full product catalog, all orders for a year):
+
+```bash
+# 1. Start bulk query
+shop_gql '
+mutation {
+  bulkOperationRunQuery(query: """
+    { products { edges { node { id title handle variants { edges { node { sku price } } } } } } }
+  """) {
+    bulkOperation { id status }
+    userErrors { field message }
+  }
+}'
+
+# 2. Poll status
+shop_gql '{ currentBulkOperation { id status errorCode objectCount fileSize url partialDataUrl } }'
+
+# 3. When status=COMPLETED, download the JSONL file
+curl -sS "$URL" > products.jsonl
+```
+
+Each JSONL line is a node, and nested connections are emitted as separate lines with `__parentId`. Reassemble client-side if needed.
+
+## Webhooks
+
+Subscribe to events so you don't have to poll:
+
+```bash
+shop_gql '
+mutation($topic: WebhookSubscriptionTopic!, $sub: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $sub) {
+    webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } } }
+    userErrors { field message }
+  }
+}' '{"topic":"ORDERS_CREATE","sub":{"callbackUrl":"https://example.com/webhook","format":"JSON"}}'
+```
+
+Verify incoming webhook HMAC using the app's client secret (not the access token):
+
+```bash
+echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$APP_SECRET" -binary | base64
+# Compare to X-Shopify-Hmac-Sha256 header
+```
+
+## Pitfalls
+
+- **REST endpoints still exist but are frozen.** Don't write new integrations against `/admin/api/.../products.json`. Use GraphQL.
+- **Token format check.** Admin tokens start with `shpat_`. Storefront public tokens with `shpua_`. If you have one and the wrong header, every request returns 401 without a useful error body.
+- **403 with a valid token = missing scope.** Shopify returns `{"errors":[{"message":"Access denied for ..."}]}`. Re-configure Admin API scopes on the app, then reinstall to regenerate the token.
+- **`userErrors` is empty != success.** Also check `data.<mutation>.<resource>` is non-null. Some failures populate neither — inspect the whole response.
+- **GID vs numeric ID.** Legacy REST gave numeric IDs; GraphQL wants full GID strings. To convert: `gid://shopify/Product/<numeric>`.
+- **Rate limit surprise.** A single `products(first: 250)` with deep nesting can cost 1000+ points and throttle immediately on a standard-plan shop. Start narrow, read `extensions.cost`, adjust.
+- **Pagination order.** `products(first: N, reverse: true)` sorts by `id DESC`, not `created_at`. Use `sortKey: CREATED_AT, reverse: true` for "newest first."
+- **`read_all_orders` for historical data.** Without it, `orders(...)` silently caps at the 60-day window. You won't get an error, just fewer results than expected. For Shopify Plus merchants with many orders, request this scope via the app's protected-data settings.
+- **Currencies are strings.** Amounts come back as `"49.00"` not `49.0`. Don't `jq tonumber` blindly if you care about zero-padding.
+- **Multi-currency Money fields** have `shopMoney` (store's currency) AND `presentmentMoney` (customer's). Pick one consistently.
+
+## Safety
+
+Mutations in Shopify are real — they create products, charge refunds, cancel orders, ship fulfillments. Before running `productDelete`, `orderCancel`, `refundCreate`, or any bulk mutation: state clearly what the change is, on which shop, and confirm with the user. There is no staging clone of production data unless the user has a separate dev store.
@@ -0,0 +1,10 @@
+---
+title: User Stories & Use Cases
+description: Real stories from the Hermes Agent community — what people are actually building, scraped from X, GitHub, Reddit, Hacker News, YouTube, blogs, and podcasts.
+hide_title: true
+hide_table_of_contents: true
+---
+
+import UserStoriesCollage from '@site/src/components/UserStoriesCollage';
+
+<UserStoriesCollage />