From 6c84724facbb9a951327e681099621f69e3d7287 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 22:38:03 -0700
Subject: [PATCH 1/9] feat(signup): render the agent signup guides from the
 vendored setup skills

- /signup/agent/teams and /signup/agent/flows keep only the signup header
  (policy, progress, web input) and include the AgentWorkforce/skills setup
  skills verbatim from a pinned commit (web/scripts/sync-setup-skills.mjs,
  --check fails on drift).
- Flows parts: Cloud account, Flows, and writing-relayflows (v2) for the
  custom-flow path; the web-input example asks prebuilt or custom instead of
  listing code-review, which is not in the catalog.
- Name the flow Software Garden in the /flows examples, the onboarding
  handoff, the builder copy, the local START-HERE and the cookbook. The id
  stays software-factory.
- TODO in flow-workflows.ts: align WORKFLOWS step lists with the cloud
  deploy wizard once it reports its final step names.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/app/flows/flow-examples.ts                |   2 +-
 web/app/flows/onboarding/FactoryBuilder.tsx   |   6 +-
 web/content/docs/relayflows/cookbook.mdx      |   2 +-
 web/content/setup-skills/SOURCE.json          |  11 +
 .../setting-up-agent-relay-desktop.md         | 922 ++++++++++++++++++
 .../setting-up-agent-relay-flows.md           | 220 +++++
 .../setting-up-agent-relay-sessions.md        | 487 +++++++++
 .../signing-in-to-agent-relay-cloud.md        | 111 +++
 .../setup-skills/writing-relayflows.md        | 539 ++++++++++
 web/lib/agent-signup-progress.ts              |   6 +-
 web/lib/agent-signup.ts                       | 470 ++-------
 web/lib/flow-local.ts                         |   2 +-
 web/lib/flow-onboarding.ts                    |   2 +-
 web/lib/flow-workflows.ts                     |   2 +
 web/lib/generated/setup-skills.ts             |  11 +
 web/lib/test/agent-signup-progress.test.ts    |  14 +-
 web/lib/test/agent-signup.test.ts             | 102 +-
 web/scripts/sync-setup-skills.mjs             |  83 ++
 18 files changed, 2590 insertions(+), 402 deletions(-)
 create mode 100644 web/content/setup-skills/SOURCE.json
 create mode 100644 web/content/setup-skills/setting-up-agent-relay-desktop.md
 create mode 100644 web/content/setup-skills/setting-up-agent-relay-flows.md
 create mode 100644 web/content/setup-skills/setting-up-agent-relay-sessions.md
 create mode 100644 web/content/setup-skills/signing-in-to-agent-relay-cloud.md
 create mode 100644 web/content/setup-skills/writing-relayflows.md
 create mode 100644 web/lib/generated/setup-skills.ts
 create mode 100644 web/scripts/sync-setup-skills.mjs

diff --git a/web/app/flows/flow-examples.ts b/web/app/flows/flow-examples.ts
index 06d18b22..32a74b52 100644
--- a/web/app/flows/flow-examples.ts
+++ b/web/app/flows/flow-examples.ts
@@ -1,7 +1,7 @@
 export const flowExamples = [
   {
     "id": "software-factory",
-    "label": "Software factory",
+    "label": "Software Garden",
     "title": "Turn a ticket into a pull request.",
     "description": "Plan the change, write the code, and run the tests before opening a PR.",
     "filename": "software-factory.flow.ts",
diff --git a/web/app/flows/onboarding/FactoryBuilder.tsx b/web/app/flows/onboarding/FactoryBuilder.tsx
index c61ca24f..ef3e216b 100644
--- a/web/app/flows/onboarding/FactoryBuilder.tsx
+++ b/web/app/flows/onboarding/FactoryBuilder.tsx
@@ -225,8 +225,8 @@ export function FactoryBuilder() {
       <div className={s.waveBreak} aria-hidden="true" />
       <div className={s.workspace}>
       {!started ? <section className={s.welcome} aria-labelledby="welcome-title">
-        <h2 id="welcome-title">Start with a software factory.</h2>
-        <p>A software factory is the easiest flow to set up. It’ll take about 5 minutes. Once you get the hang of Flows, you can build another one for other use cases.</p>
+        <h2 id="welcome-title">Start with Software Garden.</h2>
+        <p>Software Garden is the easiest flow to set up. It’ll take about 5 minutes. Once you get the hang of Flows, you can build another one for other use cases.</p>
         <button type="button" className={s.primary} disabled={!hydrated} onClick={showQuestions}>
           {draft.step > 0 ? 'Continue building my flow' : 'Let’s get started'}<ArrowRight size={17} />
         </button>
@@ -281,7 +281,7 @@ export function FactoryBuilder() {
 
           </div> : <div className={s.ready}>
             <h2 tabIndex={-1} ref={questionHeading}>Let’s run your first flow.</h2>
-            <p className={s.runDescription}>Your software factory is built. Choose where to put it to work.</p>
+            <p className={s.runDescription}>Your Software Garden is built. Choose where to put it to work.</p>
             <RunOptions draft={draft} chosen={destination} setDestination={setDestination} onNotice={setNotice} onTrack={track} getJourneyId={getJourneyId} getDistinctId={getDistinctId} markOutcome={markOutcome} />
             <details className={s.flowReview} onToggle={event => track('help_toggled', { section: 'review_flow', open: event.currentTarget.open })}>
               <summary>Review your flow<ChevronDown size={16} /></summary>
diff --git a/web/content/docs/relayflows/cookbook.mdx b/web/content/docs/relayflows/cookbook.mdx
index 27fa56fa..d29afd52 100644
--- a/web/content/docs/relayflows/cookbook.mdx
+++ b/web/content/docs/relayflows/cookbook.mdx
@@ -48,7 +48,7 @@ stale-prs: [![Deploy Flow](https://agentrelay.com/deploy-flow_small.svg)](https:
 
 [![Deploy Flow](https://agentrelay.com/deploy-flow_small.svg)](https://agentrelay.com/cloud/flows/deploy?flow=https%3A%2F%2Fgithub.com%2FAgentWorkforce%2Fflows-cookbook%2Fblob%2Fmain%2Fpr-reviewer%2Fpr-reviewer.flow.ts)
 
-## Software Factory
+## Software Garden
 
 An issue becomes a pull request: implementation agent → deterministic tests, run outside the agent → adversarial review agent that must write an explicit verdict → PR for a human.
 
diff --git a/web/content/setup-skills/SOURCE.json b/web/content/setup-skills/SOURCE.json
new file mode 100644
index 00000000..85c960de
--- /dev/null
+++ b/web/content/setup-skills/SOURCE.json
@@ -0,0 +1,11 @@
+{
+  "repository": "AgentWorkforce/skills",
+  "commit": "23a0754950654d765c417c188af52d130864b664",
+  "skills": [
+    "signing-in-to-agent-relay-cloud",
+    "setting-up-agent-relay-desktop",
+    "setting-up-agent-relay-sessions",
+    "setting-up-agent-relay-flows",
+    "writing-relayflows"
+  ]
+}
diff --git a/web/content/setup-skills/setting-up-agent-relay-desktop.md b/web/content/setup-skills/setting-up-agent-relay-desktop.md
new file mode 100644
index 00000000..0000e184
--- /dev/null
+++ b/web/content/setup-skills/setting-up-agent-relay-desktop.md
@@ -0,0 +1,922 @@
+# Set Up Agent Relay Desktop
+
+Complete the setup through the private session socket. Do not ask the human to
+click through the desktop app. The only normal human step is approving one
+device-login link when no reusable `agent-relay` CLI login exists.
+
+Prefer setting this up with the Agent Relay agent at
+<https://arelay.to/agent-relay>, which checks your current state and confirms
+each step. Fetch its instructions with
+`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.
+
+The finished state is:
+
+- the current release is installed and running;
+- sign-in is complete;
+- sharing mode is `new` (new sessions upload automatically), unless an existing
+  install already uses another mode and the human chose to keep it (section 4);
+- auto-activate is on, with every existing live session and every future session on the relay;
+- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);
+- this Codex or Claude session is registered and accepts direct delivery;
+- the requested webhook and integration subscriptions work;
+- the human receives the session's `agent@machine` address and verification evidence.
+
+Never put a Cloud token, workspace key, agent token, or webhook secret in a
+Relay message. The webhook secret is returned once to this local calling
+session; keep it in a mode-0600 temporary file and delete the file after the
+test.
+
+## Install this skill for Codex and Claude Code
+
+When the task includes installing this skill, install its canonical Claude
+package, then place that unchanged `SKILL.md` where Codex actually loads global
+skills:
+
+```sh
+npx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y
+codex_skill="$HOME/.codex/skills/setting-up-agent-relay-desktop"
+mkdir -p "$codex_skill"
+install -m 0644 \
+  "$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md" \
+  "$codex_skill/SKILL.md"
+cmp \
+  "$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md" \
+  "$codex_skill/SKILL.md"
+```
+
+Do not use prpm's `--as codex` conversion for this package. It currently writes
+under `~/.agents/skills`, which Codex does not load as its global skill folder,
+and its conversion drops explanatory paragraphs from this Markdown workflow.
+Confirm both final paths explicitly before continuing.
+
+## 1. Detect the host and current session
+
+Run setup commands from this agent's own shell tool. Do not run them from an
+unrelated terminal: the app identifies the caller from kernel credentials and
+the Codex/Claude process ancestry.
+
+```sh
+uname -s
+uname -m
+test -n "${TMUX:-}" && printf 'session=tmux\n' || true
+test -n "${SSH_CONNECTION:-}" && printf 'transport=ssh\n' || true
+if test "$(uname -s)" = Linux; then
+  if command -v dpkg-query >/dev/null; then
+    printf 'linux_install=deb\n'
+  else
+    printf 'linux_install=per-user-tarball\n'
+  fi
+fi
+command -v systemctl >/dev/null && systemctl --user is-system-running || true
+```
+
+On Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other
+systemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball
+path; do not try to install the `.deb`. The app scans same-user process trees
+and TTYs; it does not require the service itself to share the tmux session.
+
+`systemctl --user is-system-running` may report `degraded` because an unrelated
+user unit failed. That is not a Relay failure when
+`systemctl --user is-active agent-relay.service` reports `active` and the Relay
+socket passes its status check.
+
+Find an existing socket without printing private files:
+
+```sh
+pointer="$HOME/.agentworkforce/desktop/relay-socket"
+if test -r "$pointer"; then relay_socket=$(sed -n '1p' "$pointer"); fi
+if test -n "${relay_socket:-}" && ! test -S "$relay_socket"; then unset relay_socket; fi
+if test -z "${relay_socket:-}" && test -n "${XDG_RUNTIME_DIR:-}"; then
+  relay_socket="$XDG_RUNTIME_DIR/agent-relay/relay.sock"
+fi
+if ! test -S "${relay_socket:-/nonexistent}" && test "$(uname -s)" = Linux; then
+  relay_socket="/run/user/$(id -u)/agent-relay/relay.sock"
+fi
+c="$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock"
+if ! test -S "${relay_socket:-/nonexistent}" && test "$(uname -s)" = Darwin && test -S "$c"; then   # pointer file missing: use the app's own socket
+  relay_socket=$c
+fi
+test -S "${relay_socket:-/nonexistent}" && printf 'socket=%s\n' "$relay_socket"
+```
+
+If the socket exists, inspect it before installing anything:
+
+```sh
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq
+```
+
+**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
+take about 30 seconds on a busy Desktop (tracked in
+AgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout
+(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's
+`relay socket-request` can give up sooner with "Probe could not finish. Check
+your connection and run setup again"; on these paths that is the same latency,
+not a setup problem. Retry the call once before reporting a blocker, and do not
+start a second install or sign-in because of it.
+
+Preserve a working newer install. When the socket is absent, check for an
+installed-but-stopped copy before downloading: use `dpkg-query -W agent-relay`
+when `dpkg-query` exists and `systemctl --user status agent-relay.service` on
+Linux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry
+status first.
+Update an older install only when it lacks the setup contract or reports an
+older version. A `404` from `/setup/status` means the installed build is too
+old for agent-driven setup and should be updated.
+
+## 2. Install or update with checksum verification
+
+Use a private temporary directory. Never skip the published SHA-256 check.
+
+### Ubuntu LTS, headless `.deb` (preferred)
+
+Select the release architecture and install:
+
+This path needs passwordless sudo or one human-approved sudo prompt for the
+package install and `loginctl enable-linger`. Explain that prerequisite before
+starting; never capture or relay a sudo password.
+
+```sh
+case "$(uname -m)" in
+  x86_64|amd64) relay_arch=x64 ;;
+  aarch64|arm64) relay_arch=arm64 ;;
+  *) printf 'Unsupported Linux architecture: %s\n' "$(uname -m)" >&2; exit 2 ;;
+esac
+relay_tmp=$(mktemp -d)
+chmod 700 "$relay_tmp"
+release=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download
+curl -fL "$release/AgentRelay-Linux-$relay_arch.deb" -o "$relay_tmp/AgentRelay.deb"
+curl -fL "$release/AgentRelay-Linux-$relay_arch.deb.sha256" -o "$relay_tmp/AgentRelay.deb.sha256"
+if ! (cd "$relay_tmp" && sed "s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#" AgentRelay.deb.sha256 | sha256sum --check -); then
+  printf 'Agent Relay checksum verification failed; refusing installation.\n' >&2
+  exit 1
+fi
+sudo apt-get install -y "$relay_tmp/AgentRelay.deb"
+sudo loginctl enable-linger "$USER"
+systemctl --user daemon-reload
+systemctl --user enable agent-relay.service
+systemctl --user restart agent-relay.service
+systemctl --user is-active agent-relay.service
+loginctl show-user "$USER" -p Linger
+```
+
+The unit runs the bundled core headless: no display, X server, or GTK
+window is needed. This session's own GitHub subscriptions (section 6) go
+through the Desktop and need no CLI. The separate Agent Relay CLI is needed
+only to subscribe a fleet-spawned or named agent; record whether it is present
+and at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app
+discovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:
+
+```sh
+relay_cli=
+for candidate in \
+  "$HOME/.local/bin/agent-relay" \
+  "$HOME/.npm-global/bin/agent-relay" \
+  "$HOME/.agentworkforce/relay/bin/agent-relay"
+do
+  if test -x "$candidate" && test "$candidate" != /usr/bin/agent-relay; then
+    relay_cli=$candidate
+    break
+  fi
+done
+if test -z "$relay_cli"; then
+  for relay_root in \
+    "$HOME/.local/share/mise/installs/node" \
+    "$HOME/.nvm/versions/node"
+  do
+    test -d "$relay_root" || continue
+    candidate=$(find -L "$relay_root" -mindepth 3 -maxdepth 3 \
+      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)
+    if test -n "$candidate" && test "$candidate" != /usr/bin/agent-relay; then
+      relay_cli=$candidate
+      break
+    fi
+  done
+fi
+if test -n "$relay_cli"; then
+  "$relay_cli" --version
+  "$relay_cli" integration subscribe --help >/dev/null
+else
+  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\n'
+fi
+```
+
+On Linux without `dpkg`, use this per-user tarball installation under a
+versioned user directory. It is also the fallback on Ubuntu when `.deb`
+installation is unavailable and the human approves a per-user install. The
+archive contains a unit whose `/usr/bin` path is correct for packages, so
+rewrite only that `ExecStart` in the user copy:
+
+```sh
+case "$(uname -m)" in
+  x86_64|amd64) relay_arch=x64 ;;
+  aarch64|arm64) relay_arch=arm64 ;;
+  *) printf 'Unsupported Linux architecture: %s\n' "$(uname -m)" >&2; exit 2 ;;
+esac
+relay_tmp=$(mktemp -d)
+chmod 700 "$relay_tmp"
+release=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download
+curl -fL "$release/AgentRelay-Linux-$relay_arch.tar.gz" -o "$relay_tmp/AgentRelay.tar.gz"
+curl -fL "$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256" -o "$relay_tmp/AgentRelay.tar.gz.sha256"
+if ! (cd "$relay_tmp" && sed "s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#" AgentRelay.tar.gz.sha256 | sha256sum --check -); then
+  printf 'Agent Relay checksum verification failed; refusing installation.\n' >&2
+  exit 1
+fi
+mkdir "$relay_tmp/extracted"
+tar -xzf "$relay_tmp/AgentRelay.tar.gz" -C "$relay_tmp/extracted"
+relay_tree="$relay_tmp/extracted/AgentRelay-linux-$relay_arch"
+test -x "$relay_tree/usr/bin/agent-relay"
+relay_version=$(sed -n 's/^__version__ = "\([0-9A-Za-z._-]*\)"$/\1/p' \
+  "$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py")
+case "$relay_version" in
+  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\n' >&2; exit 1 ;;
+esac
+relay_unit="$HOME/.config/systemd/user/agent-relay.service"
+relay_installed_version=
+if test -S "${relay_socket:-/nonexistent}"; then
+  relay_installed_version=$(curl -fsS --unix-socket "$relay_socket" \
+    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)
+fi
+if test -z "$relay_installed_version" && test -r "$relay_unit"; then
+  relay_installed_version=$(sed -n \
+    's#^ExecStart=.*/\.local/lib/agent-relay/\([^/ ]*\)/.*#\1#p' \
+    "$relay_unit")
+fi
+case "$relay_installed_version" in
+  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;
+esac
+if test -n "$relay_installed_version" && \
+   test "$relay_installed_version" != "$relay_version" && \
+   test "$(printf '%s\n%s\n' "$relay_version" "$relay_installed_version" | sort -V | tail -n 1)" = "$relay_installed_version"; then
+  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\n' \
+    "$relay_installed_version" "$relay_version" >&2
+  exit 1
+fi
+relay_prefix="$HOME/.local/lib/agent-relay/$relay_version"
+mkdir -p "$relay_prefix"
+cp -a "$relay_tree/usr" "$relay_prefix/"
+mkdir -p "$(dirname "$relay_unit")"
+sed "s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#" \
+  "$relay_tree/usr/lib/systemd/user/agent-relay.service" >"$relay_unit.tmp"
+chmod 0644 "$relay_unit.tmp"
+mv "$relay_unit.tmp" "$relay_unit"
+grep -F "ExecStart=$relay_prefix/usr/" "$relay_unit" | grep -q -- ' --headless$'
+if ! loginctl show-user "$USER" -p Linger | grep -qx 'Linger=yes'; then
+  sudo loginctl enable-linger "$USER"
+fi
+systemd-analyze --user verify "$relay_unit"
+systemctl --user daemon-reload
+systemctl --user enable agent-relay.service
+systemctl --user restart agent-relay.service
+systemctl --user is-active agent-relay.service
+loginctl show-user "$USER" -p Linger
+# List the app in the desktop's app launcher (no-op on a headless server).
+# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the
+# entry the first time it is opened.
+if test -x "$relay_prefix/usr/bin/agent-relay-desktop"; then
+  "$relay_prefix/usr/bin/agent-relay-desktop" --install-launcher || true
+fi
+```
+
+The unit's `ExecStart` names the archive's own path under `/usr/`, either the
+launcher or the bundled `agent-relay-probe`; the rewrite moves whichever it is
+under `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its
+full path, never the bare `agent-relay`, which is also the CLI's name.
+
+Do not improvise Alpine or RHEL distribution packages. On a compatible
+systemd host without `dpkg`, use only the verified per-user tarball path above;
+non-systemd hosts remain unsupported by this Linux workflow.
+
+### macOS DMG
+
+```sh
+case "$(uname -m)" in
+  arm64) relay_arch=arm64 ;;
+  x86_64) relay_arch=x64 ;;
+  *) printf 'Unsupported Mac architecture: %s\n' "$(uname -m)" >&2; exit 2 ;;
+esac
+relay_tmp=$(mktemp -d)
+chmod 700 "$relay_tmp"
+release=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download
+curl -fL "$release/AgentRelay-macOS-$relay_arch.dmg" -o "$relay_tmp/AgentRelay.dmg"
+curl -fL "$release/AgentRelay-macOS-$relay_arch.dmg.sha256" -o "$relay_tmp/AgentRelay.dmg.sha256"
+if ! (cd "$relay_tmp" && sed "s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then
+  printf 'Agent Relay checksum verification failed; refusing installation.\n' >&2
+  exit 1
+fi
+mount_point=$(hdiutil attach -nobrowse -readonly "$relay_tmp/AgentRelay.dmg" | awk '/\/Volumes\// {sub(/^.*\/Volumes\//,"/Volumes/"); print; exit}')
+incoming_id=$(defaults read "$mount_point/Agent Relay.app/Contents/Info" CFBundleIdentifier 2>/dev/null || true)
+if test "$incoming_id" != com.agentrelay.desktop; then
+  hdiutil detach "$mount_point" >/dev/null 2>&1 || true
+  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\n' "$incoming_id" >&2
+  exit 1
+fi
+if test -d "/Applications/Agent Relay.app"; then
+  existing_id=$(defaults read "/Applications/Agent Relay.app/Contents/Info" CFBundleIdentifier 2>/dev/null || true)
+  if test "$existing_id" != com.agentrelay.desktop; then
+    hdiutil detach "$mount_point" >/dev/null 2>&1 || true
+    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\n' "$existing_id" >&2
+    exit 1
+  fi
+fi
+osascript -e 'tell application "Agent Relay" to quit' 2>/dev/null || true
+ditto "$mount_point/Agent Relay.app" "/Applications/Agent Relay.app"
+hdiutil detach "$mount_point"
+open -a "Agent Relay"
+```
+
+If `/Applications` needs administrator access, use `sudo ditto` only after the
+human has authorized installation. Do not remove or overwrite another app with
+an unexpected bundle identity.
+
+After either install, wait up to 30 seconds for the pointer:
+
+```sh
+app_sock="$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock"
+for _ in $(seq 1 30); do
+  test -r "$HOME/.agentworkforce/desktop/relay-socket" && break
+  test "$(uname -s)" = Darwin && test -S "$app_sock" && break   # the app is already listening
+  sleep 1
+done
+relay_socket=$(sed -n '1p' "$HOME/.agentworkforce/desktop/relay-socket" 2>/dev/null)
+if ! test -S "$relay_socket" && test "$(uname -s)" = Darwin && test -S "$app_sock"; then
+  relay_socket=$app_sock
+fi
+if ! test -S "$relay_socket" && test "$(uname -s)" = Linux; then
+  relay_socket="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock"
+fi
+test -S "$relay_socket"
+curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
+```
+
+## 3. Sign in by device approval
+
+Before choosing a workspace, check what the human already has. These commands
+only read state. The CLI checks run only when section 2 found a `relay_cli`;
+never call the `.deb`'s `/usr/bin/agent-relay` launcher for them:
+
+```sh
+curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'
+if test -n "${relay_cli:-}"; then
+  "$relay_cli" cloud whoami       # signed in, and as whom
+  "$relay_cli" workspace active   # the active Cloud workspace (keys stay masked)
+  "$relay_cli" cloud workspaces   # every workspace this login can use, with ids
+  "$relay_cli" status             # workspace, cloud login and local broker
+fi
+```
+
+Sign in to the workspace they already use. Pick a different or new workspace
+only when the human explicitly asks for it.
+
+For a multi-server rollout, obtain the existing enterprise workspace UUID from
+the human and pass it explicitly on every server. Do not guess it and do not
+use `{}` when the target workspace is known: that could select a default/free
+workspace and split the fleet. Use `{}` only for an individual setup where the
+human has confirmed that the reusable login's current workspace is intended.
+
+```sh
+relay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'
+sign_in_payload=$(jq -nc --arg workspace "$relay_workspace_uuid" '{workspace:$workspace}')
+sign_in=$(curl -sS --unix-socket "$relay_socket" \
+  -H 'Content-Type: application/json' \
+  -d "$sign_in_payload" http://relay/setup/sign-in)
+printf '%s\n' "$sign_in" | jq \
+  '{ok, data: {
+    status: .data.status,
+    reused_login: .data.reused_login,
+    workspace: .data.workspace
+  }, error}'
+```
+
+If sign-in reports that older upload schedules could not be inspected, first
+inspect the user's legacy cron, launchd, and user-service upload schedules.
+After completing that safety check, retry the original request with the
+acknowledgement added; never use it merely to suppress the error:
+
+```sh
+sign_in_payload=$(printf '%s\n' "$sign_in_payload" | \
+  jq '. + {acknowledge_uninspected_schedules:true}')
+sign_in=$(curl -sS --unix-socket "$relay_socket" \
+  -H 'Content-Type: application/json' \
+  -d "$sign_in_payload" http://relay/setup/sign-in)
+printf '%s\n' "$sign_in" | jq \
+  '{ok, data: {
+    status: .data.status,
+    reused_login: .data.reused_login,
+    workspace: .data.workspace
+  }, error}'
+```
+
+Print a device link and code only when the response actually contains a code:
+
+```sh
+user_code=$(printf '%s\n' "$sign_in" | jq -r '.data.user_code // empty')
+if test -n "$user_code"; then
+  verification_url_complete=$(printf '%s\n' "$sign_in" | \
+    jq -r '.data.verification_url_complete // empty')
+  if test -n "$verification_url_complete"; then
+    printf 'Open %s and approve code %s\n' "$verification_url_complete" "$user_code"
+  else
+    verification_url=$(printf '%s\n' "$sign_in" | \
+      jq -r '.data.verification_url // empty')
+    printf 'Open %s and enter code %s\n' "$verification_url" "$user_code"
+  fi
+fi
+```
+
+If the response is `signed_in` with `reused_login:true`, the app reused an
+eligible same-origin CLI or desktop login and intentionally issued no device
+code. Confirm the returned workspace id and name with the human rather than
+waiting for a code, then continue only if it is the intended workspace.
+
+For `pending_approval`, the human can approve from any phone or browser. Do not
+create another code while this one is pending. A `preparing` response is also
+normal: poll `/setup/status` at the reported interval. Preparing local history
+can take about a minute when the app reuses an existing `agent-relay` CLI login.
+Poll both states until sign-in finishes. The reason for a failure is in
+`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so
+print it, and map the known messages to their fix instead of dumping raw state:
+
+```sh
+while :; do
+  state=$(curl -sS --unix-socket "$relay_socket" http://relay/setup/status)
+  phase=$(printf '%s' "$state" | jq -r '.data.sign_in // .error.code')
+  case "$phase" in
+    signed_in)
+      printf '%s\n' "$state" | jq \
+        '{sign_in: .data.sign_in, workspace: .data.workspace}'
+      break
+      ;;
+    preparing|pending_approval) ;;
+    denied|expired|error)
+      msg=$(printf '%s' "$state" | jq -r '.data.sign_in_message // .error.message // "no message reported"')
+      printf 'Sign-in %s: %s\n' "$phase" "$msg" >&2
+      case "$msg" in
+        *"older managed history uploader"*)
+          printf 'See "Sign-in blocked by a legacy uploader" under Recovery.\n' >&2 ;;
+        *"older upload schedules"*)
+          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\n' >&2 ;;
+        *) printf '%s\n' "$state" | jq '.data' >&2 ;;
+      esac
+      exit 1
+      ;;
+  esac
+  sleep "$(printf '%s' "$sign_in" | jq -r '.data.interval // 5')"
+done
+```
+
+## 4. Apply the agent-led defaults and register this session
+
+Read the current sharing mode before changing it. `/setup/status` reports it as
+`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is
+uploading yet). The probe reports the same field, `sharing_mode`, in
+`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.
+
+```sh
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq -r '.data.sharing_mode'
+```
+
+On a fresh install, or when it already reports `new`, use `new`. When an
+existing install reports `all` (which also uploads past sessions, so it is
+broader than this skill's default) or `selected`, tell the human the current
+mode and ask whether to keep it or change it to `new`. Never change it silently.
+Set `relay_sharing_mode` below to the human's answer.
+
+Then set and verify all three agent-led defaults even when the app's `/setup/*`
+bootstrap already applied them. Sharing mode `new` uploads every new session;
+auto-activation puts every existing live session and every future session on
+the relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:
+
+```sh
+relay_sharing_mode=new   # or the existing mode the human chose to keep
+direct_delivery=$(curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d '{"enabled":true}' http://relay/setup/direct-delivery)
+printf '%s\n' "$direct_delivery" | jq
+if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; then
+  if printf '%s\n' "$direct_delivery" | jq -e '.error.code == "managed_policy"' >/dev/null; then
+    printf 'Organization-managed Claude settings forbid direct delivery.\n' >&2
+  fi
+  exit 1
+fi
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg mode "$relay_sharing_mode" '{mode:$mode}')" \
+  http://relay/setup/sharing | jq
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d '{"enabled":true}' \
+  http://relay/setup/auto-activate | jq
+register=$(curl -sS --unix-socket "$relay_socket" \
+  -H 'Content-Type: application/json' \
+  -d '{}' http://relay/register)
+printf '%s\n' "$register" | jq
+registration_status=$(curl -sS --unix-socket "$relay_socket" \
+  http://relay/setup/status)
+printf '%s\n' "$registration_status" | \
+  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'
+printf '%s\n' "$registration_status" | jq -e \
+  '.ok and (.data.session.id | type == "string" and length > 0) and
+   .data.session.registered == true and .data.session.direct_delivery == true'
+```
+
+Direct delivery is checked first so a managed-policy refusal stops setup
+before auto-activation or upload settings are changed. Report that refusal
+clearly; never claim the three-default setup completed.
+
+Sharing mode and auto-activate are different settings: the former
+controls upload eligibility and the latter controls Relay registration. The
+setup flow requires both.
+
+`POST /register` discovers the nearest live Codex or Claude ancestor. A session
+inside tmux over SSH is valid. Never pass a session id or token in the body.
+The default name includes a 128-bit session-derived suffix, so dozens of
+sessions in the same checkout receive distinct `name@direct` addresses. Save
+and report the address from `/setup/status` for each session; never reuse one
+session's address for another. `/register` may omit the session id or
+direct-delivery state, so its response alone is not verification. Require the
+status response to show this session's non-empty id, `registered:true`, and
+`session.direct_delivery:true` as above. An app fix is expected to add those
+fields to `/register`, but the status check remains authoritative.
+
+## 5. Create and test the webhook
+
+Perform this section only when the human requested a webhook (or explicitly
+asked for the full end-to-end setup). Otherwise skip it; webhook creation is a
+persistent external mutation, not an install prerequisite.
+
+Capture the one-time secret without echoing it:
+
+```sh
+umask 077
+hook_file=$(mktemp)
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d '{}' http://relay/webhooks >"$hook_file"
+jq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' "$hook_file"
+```
+
+When `created:true`, send a unique marker. Initialize every temporary path so
+cleanup can name and delete exact files without `-f` or globs:
+
+```sh
+hook_config=
+marker=
+webhook_post_ok=false
+webhook_post_status=0
+if test "$(jq -r '.data.created // false' "$hook_file")" = true && \
+   test "$(jq -r '.data.secret // empty' "$hook_file")" != ''; then
+  hook_url=$(jq -r '.data.url' "$hook_file")
+  hook_secret=$(jq -r '.data.secret' "$hook_file")
+  hook_config=$(mktemp)
+  chmod 600 "$hook_config"
+  printf 'header = "Authorization: Bearer %s"\n' "$hook_secret" >"$hook_config"
+  marker="agent-relay-webhook-test-$(date +%s)"
+  if curl -fsS --config "$hook_config" -X POST "$hook_url" \
+      -H 'Content-Type: application/json' \
+      -d "{\"text\":\"$marker\",\"source\":\"agent-driven-setup\"}"; then
+    webhook_post_ok=true
+  else
+    webhook_post_status=$?
+  fi
+else
+  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\n' >&2
+fi
+if test -n "$hook_config" && test -e "$hook_config"; then
+  rm -- "$hook_config"
+fi
+if test -e "$hook_file"; then
+  rm -- "$hook_file"
+fi
+unset hook_secret
+if test "$webhook_post_ok" = true; then
+  printf 'Webhook test sent; end this turn and wait for marker: %s\n' "$marker"
+elif test -n "$marker"; then
+  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\n' \
+    "$webhook_post_status" >&2
+  exit "$webhook_post_status"
+fi
+```
+
+Do not claim success merely because the POST returned 2xx, and do not sleep or
+poll for the injected message during the same turn. Relay injects only after
+the session becomes idle between turns. After the POST and exact-file cleanup,
+end the current turn by saying that setup is waiting for the exact marker. On
+the next turn, confirm that the injected body contains that marker and its
+Agent Relay header contains a full message id; record that id in the final
+evidence. If a polling consumer is part of the setup, also observe that same id
+there before declaring the webhook test complete. If the webhook already
+existed, its secret is correctly returned as null; do not revoke or recreate it
+without human authorization. Ask for the existing secret or report that the
+delivery test could not be repeated.
+
+## 6. Subscribe requested integrations
+
+Require the provider and repository from the human. A GitHub pull request needs
+one resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's
+reviews, review comments, conversation comments and check runs to that glob by
+the PR they reference, so no other glob is needed: nothing is written under
+`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or
+`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This
+works on every released Desktop and is the path to use today. If a review or
+comment then never arrives, read it back in relayfile at its own path (the
+table in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event
+never reached relayfile
+([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),
+not that the subscription is wrong.
+
+First find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions
+(below) and it is the client for the one-command form once that ships:
+
+```sh
+relay_probe=
+for candidate in \
+  "$HOME/.local/bin/agent-relay-probe" \
+  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \
+  "/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe"
+do
+  if test -x "$candidate"; then relay_probe=$candidate; break; fi
+done
+if test -z "$relay_probe" && test -d "$HOME/.local/lib/agent-relay"; then
+  relay_probe=$(find "$HOME/.local/lib/agent-relay" -type f -perm -u+x \
+    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)
+fi
+printf 'relay_probe=%s\n' "${relay_probe:-none}"
+```
+
+A running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the
+other candidates are the copies bundled by the `.deb`, the macOS app, and the
+per-user tarball. Then subscribe through the socket. On macOS use the probe
+client when there is one: the system `curl` hides a Codex session's identity
+there and is refused `not_a_relay_session`, so a Codex session with no probe
+stops instead. `curl` is correct for Claude Code and on Linux:
+
+```sh
+# One client for every socket request in this section and in undo: the probe
+# on macOS (system curl hides a Codex session there), curl elsewhere.
+relay_req() {  # METHOD PATH [JSON body]
+  if test "$(uname -s)" = Darwin && test -n "${relay_probe:-}"; then
+    printf '%s' "${3:-}" | "$relay_probe" relay socket-request \
+      --socket "$relay_socket" --method "$1" --path "$2"
+  elif test "$(uname -s)" = Darwin && test -n "${CODEX_THREAD_ID:-}"; then
+    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\n' >&2
+    return 1
+  elif test -n "${3:-}"; then
+    curl -sS --unix-socket "$relay_socket" -X "$1" \
+      -H 'Content-Type: application/json' -d "$3" "http://relay$2"
+  else
+    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+  fi
+}
+
+# This PR's subscriptions, in whichever form they were made. Fails, rather than
+# answering "none", when the status cannot be read: both callers stop then.
+pr_url='https://github.com/OWNER/REPO/pull/NUMBER'
+pr_resources() {
+  relay_status=$(relay_req GET /setup/status) || return 1
+  # -s reads the whole body as one list, so an empty body is an error too.
+  printf '%s\n' "$relay_status" | jq -rs --arg url "$pr_url" \
+    --arg short 'OWNER/REPO#NUMBER' \
+    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \
+    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '
+    if length == 1 and .[0].ok == true
+       and (.[0].data.integrations | type) == "array" then
+      .[0].data.integrations[] | select(.provider == "github") | .resource
+      | select(. == $url or . == $short or startswith($url + "/")
+               or startswith($pulls) or startswith($issues))
+    else
+      error("Agent Relay status is unreadable; no subscription was changed.")
+    end'
+}
+
+held=$(pr_resources) || exit 1
+if printf '%s\n' "$held" | grep -Fqx -e "$pr_url" -e 'OWNER/REPO#NUMBER'; then
+  # The one-command subscription is a single complete request: nothing to add.
+  printf 'Already subscribed:\n%s\n' "$held"
+elif test -z "$held" && test -n "${relay_probe:-}" && \
+     "$relay_probe" relay --help 2>&1 | grep -q '^  subscribe'; then
+  # The one-command form (below), only for a PR with no subscription yet and
+  # only when the installed probe has it.
+  "$relay_probe" relay subscribe "$pr_url" | jq
+else
+  relay_req POST /integrations/subscribe \
+    "$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \
+      '{provider:"github",resource:$resource}')" | jq
+fi
+relay_req GET /setup/status | jq -c '.data.integrations'
+```
+
+Require `.ok` and `.data.subscribed` to be `true`, and the entry in the status
+list to be `ready: true`. A repeated request returns HTTP 409
+`conflict` ("already subscribed"). That is success only for a binding made on
+or after 2026-09-19. Earlier bindings predate PR-identity matching
+(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews
+and comments. If the binding may be older, or you cannot tell, recreate it
+once: `relay_req DELETE /integrations/subscribe` with the same body, then
+subscribe again. Verified on
+Desktop 2026.10.6 with both the probe client and `curl`.
+
+**One-command form (not yet released).** `relay-desktop#216` adds
+`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`
+(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription
+that the Desktop correlates with the PR's reviews, comments, and checks. It is
+absent from Desktop 2026.10.6, where it fails with `unrecognized subcommand
+'subscribe'`, so do not lead with it. Use it only when the installed probe
+advertises it. The block above makes that choice, and first checks the
+session's existing subscriptions. A pull request already subscribed with the
+one-command form is left alone. A pull request already holding
+the number glob answers 409 `conflict` on a repeat; recreate that binding once
+if it may predate 2026-09-19 (see above). Extra `reviews`, `status` or
+`issues/NUMBER/comments` globs from an earlier version of this skill never
+deliver; unsubscribe them.
+
+Once released, re-test it before relying on its details; the behavior described
+in that PR (a repeat answering `"already_subscribed":true`, `--remove` to end it,
+and a numeric subscription covering reviews, comments and checks) has not been verified here.
+
+Refusals and what they mean:
+
+- `not_a_relay_session`, "Register this session before subscribing it": run
+  section 4's `POST /register` first.
+- `not_a_relay_session`, "already managed by this computer's relay" from
+  `/register`: this session was started by the Agent Relay fleet broker, not
+  the Desktop. Use the workspace CLI below instead.
+- `refused` or `busy`: an earlier subscription is still being made or cleaned
+  up; repeat the command shortly.
+
+A fleet-spawned session, or an operator subscribing a named agent, uses the
+`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in
+`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let
+the worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail
+with `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`
+is set:
+
+```sh
+pull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'
+relay_cli_major=
+if test -n "${relay_cli:-}"; then
+  relay_cli_major=$("$relay_cli" --version 2>/dev/null | sed -n 's/^[^0-9]*\([0-9][0-9]*\)\..*/\1/p' | sed -n '1p')
+fi
+if test -n "$relay_cli_major" && test "$relay_cli_major" -ge 13; then
+  "$relay_cli" integration subscribe github \
+    --resource "$pull_glob" --to '@AGENT_NAME' --no-input
+elif test -n "$relay_cli_major"; then
+  # 12.x and older: keep the ambient agent token from displacing the key.
+  env -u RELAY_AGENT_TOKEN "$relay_cli" integration subscribe github \
+    --resource "$pull_glob" --to '@AGENT_NAME' --no-input
+else
+  # No usable installed CLI: run the fixed release without installing it.
+  npx -y agent-relay@13 integration subscribe github \
+    --resource "$pull_glob" --to '@AGENT_NAME' --no-input
+fi
+```
+
+Use the `relay_cli` found in section 2, never a bare `agent-relay`: on a
+`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may
+resolve to it or to a different, older CLI than the one whose version was
+checked.
+
+The CLI path follows `orchestrating-agent-relay`, which subscribes the same
+single `pulls/NUMBER/**` glob. Never put the workspace key in argv.
+
+Make the subscribe step a required post-create step in the agent's PR
+workflow: whenever it authors a PR, it subscribes its own live session
+immediately, without waiting for an operator to name the PR. This is the
+authored-PR pattern from `orchestrating-agent-relay`; it covers every future PR
+the agent authors without subscribing unrelated repository traffic. The
+Desktop removes the subscription itself after the PR closes or merges.
+For real GitHub verification, use a harmless event the human authorized
+on that PR (for example, a test conversation comment and a requested bot
+review). After causing the event, do not wait or poll within the active turn:
+end the turn saying which event marker is expected. Confirm the injected event
+and record its full message id on the next turn after Relay has delivered it.
+Do not create a comment, review, or rerun without authorization. A successful
+subscribe response alone does not prove end-to-end delivery.
+
+## 7. Coexist with a REST-polling MCP
+
+Do not disable an existing polling consumer. Desktop injection acknowledges
+only this registered agent's delivery queue and does not advance a separate
+workspace consumer's cursor. A polling MCP should use its own identity/cursor,
+not this session agent's `/v1/deliveries` token.
+
+Injected text contains both the full Relaycast message id and a short `ref`.
+When polling and injection can surface the same workspace message, deduplicate
+on the full message id before acting. During verification, leave the poller
+running and observe the test message there. Then end the current turn so Relay
+can inject it, and on the next turn confirm the same full id arrived while the
+agent acted only once.
+
+## 8. Final verification and report
+
+Read status again:
+
+```sh
+curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'
+```
+
+Require all three defaults before declaring setup complete:
+
+```sh
+curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq -e --arg mode "${relay_sharing_mode:-new}" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'
+```
+
+Report the exact version, `signed_in`, signed-in workspace id and name, sharing
+mode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,
+uploader health, session address, direct-delivery state, webhook test marker,
+subscriptions, real GitHub event evidence, and polling-coexistence result.
+Separate verified facts from steps that still require a human or external
+event.
+
+## Recovery and undo
+
+- **Socket missing or slow:** check `systemctl --user status agent-relay.service`
+  on Linux or `open -a "Agent Relay"` on macOS. Confirm the pointer names a
+  socket. Never delete a live socket; restart the owning service/app. A reply
+  that takes up to about 30 seconds is the known latency in section 1
+  (relay-desktop#333), not a fault: allow 60 seconds and retry once.
+- **`not_a_relay_session`:** the command is not a descendant of a supported
+  live Codex/Claude session, or the session id/process start no longer matches.
+  Run it through this agent's shell tool. In tmux, confirm the agent process and
+  shell share the pane's process tree.
+- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message "An older
+  managed history uploader is active. Stop it explicitly before enabling this
+  probe."): the probe counts any of these legacy `ai-hist push` registrations as
+  active, even when idle: the file
+  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded
+  launchd label `com.ai-hist.push`, or a crontab line containing
+  `# ai-hist push (managed)`. Check each, then with the human's approval unload
+  and move aside (do not delete) what exists. Create the backup directory first,
+  use a unique no-clobber destination, and confirm the move before retrying:
+
+  ```sh
+  # bootout exits non-zero when the label was never loaded; that is fine, so
+  # judge success by whether the label is still loaded, not by its exit code.
+  launchctl bootout "gui/$(id -u)/com.ai-hist.push" 2>/dev/null || true
+  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then
+    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2
+    exit 1
+  fi
+  plist="$HOME/Library/LaunchAgents/com.ai-hist.push.plist"
+  if test -e "$plist"; then
+    backup_dir="$HOME/.agentworkforce/backup"
+    mkdir -p "$backup_dir"
+    mv -n "$plist" "$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)"
+    test ! -e "$plist" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }
+  fi
+  ```
+
+  If instead the marked cron line is the cause, back up the full crontab first
+  and remove only that line, so the change can be reversed with
+  `crontab <backup-file>`:
+
+  ```sh
+  mkdir -p "$HOME/.agentworkforce/backup"
+  cron_backup="$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)"
+  crontab -l > "$cron_backup" && test -s "$cron_backup" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }
+  grep -vF '# ai-hist push (managed)' "$cron_backup" | crontab -
+  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }
+  ```
+
+  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run
+  `/setup/sign-in` with the same payload.
+- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the
+  request. Restart after `expired` or `denied` to obtain a new code.
+- **Older schedules could not be inspected:** inspect the user's legacy cron,
+  launchd, or user-service upload schedules first. Only after that inspection,
+  retry `/setup/sign-in` with the original payload plus
+  `"acknowledge_uninspected_schedules":true`. This flag records a completed
+  safety check; never send it merely to silence an error.
+- **`not_allowed` from `/register`:** enable the app's self-registration
+  setting. Do not bypass it with workspace credentials.
+- **Managed Claude policy:** if direct delivery reports `managed_policy`, the
+  organization controls `crossSessionInbound`; report the policy block rather
+  than modifying managed settings.
+- **Undo registration:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
+- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,
+  `relay_req`, and `pr_resources` defined, remove every subscription the
+  session holds for the pull request, in whichever form it was made. On macOS
+  `relay_req` uses the probe, and a Codex session without one stops instead of
+  sending a `curl` request that cannot be identified:
+
+  ```sh
+  held=$(pr_resources) || exit 1
+  printf '%s\n' "$held" | while IFS= read -r resource; do
+    test -n "$resource" || continue
+    relay_req DELETE /integrations/subscribe \
+      "$(jq -nc --arg resource "$resource" '{provider:"github",resource:$resource}')" | jq
+  done
+  relay_req GET /setup/status | jq -c '.data.integrations'
+  ```
+
+  Require the final list to hold none of that pull request's resources.
+- **Undo a webhook:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
+- **Undo direct delivery:** POST `{"enabled":false}` to
+  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed
+  organization policy still wins.
+- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to
+  `/setup/sharing`. Ask before changing it when the earlier value is unknown.
+- **Auto-activate accidentally enabled:** POST `{"enabled":false}` to
+  `/setup/auto-activate`. This does not remove existing registrations.
+- **Uninstall:** stop/disable the user service before removing the Linux
+  package, or quit the Mac app before removing it. Do not delete app data or
+  revoke webhooks unless the human explicitly asks for data removal.
diff --git a/web/content/setup-skills/setting-up-agent-relay-flows.md b/web/content/setup-skills/setting-up-agent-relay-flows.md
new file mode 100644
index 00000000..d6358bb1
--- /dev/null
+++ b/web/content/setup-skills/setting-up-agent-relay-flows.md
@@ -0,0 +1,220 @@
+# Set Up Agent Relay Flows
+
+Drive the setup through the documented Cloud APIs and the official CLI. Do not
+use computer use, browser automation, or the dashboard UI. The human approves
+sign-in, tool consent, and provider logins on their own approval pages; open
+those links with the OS URL opener (or give them the link), then verify by
+polling the API, never by inspecting the browser.
+
+Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
+including its `/cloud` prefix; the site is `https://agentrelay.com`. When a
+guide names a different site and Cloud base (for example a local development
+stack), use those exact origins throughout and never fall back to production.
+Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
+
+## Requires
+
+A signed-in Cloud session: an access token and the `user.id` and
+`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`
+first, and send `Authorization: Bearer <access_token>` on every request below.
+
+## API map
+
+- Flow catalog: `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.
+- Tool consent links: `POST /api/v1/integrations/connect-link`; poll
+  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.
+- Coding-agent credentials: the official CLI's `cloud connect` (section 3);
+  `GET /api/v1/cloud-agents` inspects existing connections.
+- Activation: `POST /api/v1/flows/deploy` with the body in section 4.
+- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`
+  reports whether it is available.
+- Verification: `GET /api/v1/flows/listeners/<agentId>`.
+
+## 1. Prebuilt or custom?
+
+Ask the human first, unless their request already says: a **prebuilt** flow
+from the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**
+flow of their own? In an agent-driven signup, ask through that guide's
+web-input protocol on the signup page, not in chat.
+
+- Prebuilt: continue with section 2.
+- Custom: follow **Custom flow: deploy journey** below. A custom flow is
+  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and
+  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is
+  no separate custom API.
+
+## 2. Choose the flow and repository
+
+Ask the human for missing product choices: repository, desired
+workflow/trigger, and approver. In an agent-driven signup, ask through that
+guide's web-input protocol on the signup page, not in chat. Ask for the approver's
+GitHub username in plain language (for example, "octocat" or "@octocat"),
+not an internal provider-address format or their Google email. Normalize the
+answer to github:@handle when constructing the deploy API request. Human-gate
+replies are matched to that provider identity. Infer choices from the user's request and current
+repository where clear.
+Do not invent a repository or enable automation on an unrelated project.
+
+GET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.
+GET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
+kind before doing anything executable: only an entry with kind: flow (or a
+legacy entry with kind omitted) is deployable through the direct-source API
+below. An entry with kind: extension is discoverable metadata, not a standalone
+listener. Do not download or deploy its source, even when it declares trigger
+and input fields. Inspect baseFlowId and extension.activation instead. If the
+extension is blocked, report the unmet dependencies and that it can only be
+added to its base flow after a supported extension activation path is available;
+never substitute a standalone flow deployment.
+
+For a deployable flow, use the catalog's
+supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
+inputs.allowedAgents. Name a model per harness in inputs.models when the house
+default is wrong (for example {"claude": "claude-sonnet-4"}); omit it to fund
+the house default for each declared agent. Download source.rawUrl, verify its bytes against
+source.sha256, and use that source text unchanged for a recommended flow.
+The source is TypeScript, not the source URL. Do not guess a template or hash.
+
+## Custom flow: deploy journey
+
+There is no journey API. A `journey_id` (for example in a
+`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it
+through unchanged where you received it, and never call an endpoint with it or
+wait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`
+as a prebuilt one; only where the source comes from differs.
+
+1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,
+   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that
+   skill for the flow's shape and checks; Flows are always v2. Cloud's
+   prompt generator is an optional shortcut: use it only when
+   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it
+   reports unavailable, refuses your session (403 `session_required`), or
+   fails, author with `writing-relayflows` instead; do not retry into it.
+2. Choose its repository, trigger and approver as in section 2.
+3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the
+   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent
+   only when the prompt generator produced one. `base` and `extensions` are
+   optional and only for a flow that names them.
+
+The human-only steps are the same for both paths: Google sign-in and device
+approval, GitHub and trigger-app OAuth including the repository grants,
+model-provider login, and confirming the repository and trigger before
+activation. Do every other step yourself through the APIs.
+
+## 3. Connect the required tools and coding agents
+
+Use bearer-authenticated POST /api/v1/integrations/connect-link:
+
+```json
+{"provider":"github","workspaceId":"<currentWorkspace.id>"}
+```
+
+Open the returned connectUrl for the user to approve. Keep token/sessionToken
+private. Connect only the repository and tools the chosen flow requires.
+For GitHub the user must grant repository access. Repeat with the chosen trigger
+provider if different. Reuse existing ready connections rather than relinking.
+Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
+until oauth.connected is true (poll with backoff and a bounded timeout); a
+returned connect link or a closed popup alone does not prove the connection.
+For the GitHub-triggered Software Garden flow, activation separately checks
+that the connected GitHub App covers the selected repository. Its trigger
+does not require background data indexing, so do not block solely because
+the broader status.ready is false from queued syncs.
+If a different flow declares Relayfile data that requires synced records,
+verify that readiness separately before activating it.
+
+Do not connect a Claude or Codex subscription yet. The first three runs use
+Cloud's own model key, so no provider login is needed to activate. If the chosen
+flow declares more than one coding agent in inputs.agents, included Cloud runs
+can fund only one of them per run — connect your own subscription for at least
+one declared agent before activating a multi-agent flow. After the included
+runs, activation and launches will ask for your own subscription; only then use
+the official Relay CLI with the private credential environment from
+`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:
+
+This promotion depends on Cloud's internal house-key proxy and account
+enrollment. If local activation returns flow_credentials_unavailable or
+flow_model_not_connected before the three promotional runs, treat it as an
+internal configuration or eligibility issue. Do not ask the user to connect
+Claude/Codex, provide an API key, or choose an inactive draft as a workaround.
+Report the blocker (in a signup, through its Progress API) and have an internal developer
+verify the proxy, promotion flag, provider readiness, and enrollment. Never
+copy a house key into the agent environment or expose it in this guide.
+
+```sh
+npx --yes agent-relay@latest cloud connect anthropic --api-url 'https://agentrelay.com/cloud'
+```
+
+Use anthropic for Claude or openai for Codex, according to the selected flow.
+The command drives provider login; open its authorization URL for the user,
+and keep the process alive until it confirms the credential is connected.
+Google approval does not grant GitHub or model-provider access: those services
+may require their own consent. Never fabricate credentials or claim consent
+happened. GET /api/v1/cloud-agents lets you inspect the account's credential
+state without reconnecting.
+
+## 4. Activate through the same API as web onboarding
+
+POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
+session. The token must be the device-flow session from
+`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with
+`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the
+browser onboarding handoff: source is TypeScript text, repository is singular,
+and sources contains provider/settings objects. The catalog supplies the source
+reference and defaults; it is not itself a deploy request. The current endpoint
+does not accept a flowId/repositories-only catalog activation request or fetch
+the source for you. For multiple repositories, submit one deployment per
+repository with a distinct name and handoffId.
+
+For the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the
+workspace, verified source, repository, GitHub approver and a new UUID:
+
+```json
+{
+  "workspaceId": "<currentWorkspace.id>",
+  "name": "Software Garden",
+  "workflow": "software-factory",
+  "source": "<verified TypeScript source text>",
+  "handoffId": "<one UUID generated for this setup>",
+  "inputs": {"approver": "github:@octocat", "agents": ["claude"]},
+  "mode": "activate",
+  "repository": {"owner": "acme", "name": "api"},
+  "sources": [{"provider": "github", "settings": {"repository": "acme/api"}}]
+}
+```
+
+For another deployable kind: flow catalog entry use its id as workflow, allowed agents, and
+defaultTrigger for sources, then apply the user's trigger settings. Scope a
+GitHub issue trigger with settings.repository set to the chosen owner/name;
+for GitLab use settings.project. Cloud does not derive this filter from the
+deployment repository. An empty filter can trigger on other repositories in
+the workspace. Only use a different trigger scope when explicitly requested.
+Give each repository its own trigger filter for multi-repository setup. Do not send
+the example acme repository or octocat approver unchanged. The workflow field
+is a label, not a source lookup; keep the verified source in the request.
+For GitLab set repository.host to gitlab and use the namespace path
+as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
+failure, GET /api/v1/flows/listeners and check whether the flow already exists;
+do not create a new ID/name on every retry. Activation subscribes to matching
+future events and can run work; confirm the intended repository and trigger
+with the user if they have not specified them.
+
+HTTP 201 must contain agentId and status: listening. A draft is not completion.
+For a 409 workspace_mismatch, verify the active workspace; for connection
+preflight failures, fix the indicated connection before retrying. If the user
+wants to save incomplete work, use mode: draft explicitly and report that it
+is inactive. Never mask activation failures by silently falling back to draft.
+
+## 5. Verify
+
+GET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and
+verify its repository and sources match the request. Open
+https://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,
+workspace, repository, trigger, and verified listening state. This proves
+activation; only an actual completed run proves execution. Do not create a
+real issue or launch paid work merely to make the onboarding check turn green.
+Delete temporary authentication files after the work is complete.
+
+The desktop app is optional for Flows. If the user also wants local session
+sharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`
+with the same account (an agent-driven signup can follow
+https://agentrelay.com/signup/agent/teams).
diff --git a/web/content/setup-skills/setting-up-agent-relay-sessions.md b/web/content/setup-skills/setting-up-agent-relay-sessions.md
new file mode 100644
index 00000000..c5ebe0c2
--- /dev/null
+++ b/web/content/setup-skills/setting-up-agent-relay-sessions.md
@@ -0,0 +1,487 @@
+# Set Up Agent Relay Session Handoff
+
+Drive the whole onboarding from this agent's own shell and MCP tools. Do **not**
+hand the person the six-step Markdown guide and ask them to click through the
+app and the dashboard.
+
+Prefer setting this up with the Agent Relay agent at
+<https://arelay.to/agent-relay>, which checks your current state and confirms
+each step. Fetch its instructions with
+`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.
+
+The finished state is:
+
+- the desktop app is installed, signed in to the **intended workspace**, the
+  uploader is healthy, and this session is registered with direct delivery on;
+- the **agent-sessions cloud MCP** is installed in this project and loaded by
+  this session, so the handoff tools (`list_relay_agents`, `send_relay_message`,
+  `read_relay_conversation`, `check_relay_inbox`, `get_shared_session`,
+  `get_shared_session_context`, `search_shared_sessions`) are available;
+- a live round trip is proven when a teammate is online: this agent messages the
+  teammate's agent, **reads the teammate's real session back** with
+  `get_shared_session_context`, and the teammate reads this session and replies.
+  When no teammate is online yet, the fallback is the roster plus this person's
+  own uploaded session reading back cleanly — reported as self-verified, not as a
+  proven two-way handoff.
+
+## Requires
+
+This skill builds on `setting-up-agent-relay-desktop` (verified install, sign-in,
+registration, agent-led defaults). If that skill is **not installed** in this
+agent, stop, tell the person, and have them install the companions together,
+then restart the agent. Do not improvise the install or sign-in from memory.
+
+- prpm: `npx prpm install collections/agent-relay-setup --as claude --global -y`
+- skills.sh: `npx skills add https://github.com/AgentWorkforce/skills --skill setting-up-agent-relay-desktop --skill setting-up-agent-relay-sessions`
+- Codex: do not use prpm's `--as codex` (it drops paragraphs and writes under `~/.agents/skills`, which Codex does not load as its global skill folder). Mirror both installed `SKILL.md` files into `~/.codex/skills/<name>/` with the loop in **Install this skill (and its dependency)** below.
+
+## The only human steps
+
+Everything else is automatable; be honest that these are not. **Ask for all of
+them up front, before touching anything** — the token in particular is needed
+only at section 3, but minting it and exporting it into the launching
+environment takes the person a few minutes, so have them start it while the
+desktop install and sign-in run:
+
+1. **Approve one Google device-login link** — only when no reusable `agent-relay`
+   CLI/desktop login exists. A reused login needs zero clicks.
+2. **Provide one Bearer token** minted in the dashboard's **"Connect your agent"**
+   card. No setup route returns this token by design. **Do not have the person
+   paste it into this conversation** — the uploader shares this session's prompts
+   with teammates, so a pasted secret would become teammate-readable. Instead the
+   person puts it into the **environment that launches their agent** (or an OS
+   keychain / a mode-0600 file) via a shell *they* run, and this agent references
+   it only by variable name — never by value. See **Token handling** below.
+3. **Same workspace, both sides.** The teammate (or workspace admin) must have
+   invited this person's email to the **shared** workspace — two agents can only
+   reach each other inside one workspace. Confirm the workspace id matches on
+   both machines; do not guess it.
+
+One structural note so expectations are right: there is **no automatic ack** to
+the sender when a handoff is picked up, and **no partial session sharing** — a
+session is on-or-off on the relay. Confirm a handoff by activity, not a push.
+
+## How this composes with `setting-up-agent-relay-desktop`
+
+This skill is a thin layer on a working desktop. The desktop skill owns install,
+sign-in, defaults and self-registration; this one owns only the agent-sessions
+cloud MCP and the live handoff. Section 2 checks the desktop prerequisite and,
+if it is not met, invokes `/setting-up-agent-relay-desktop` to completion and
+returns here. Keep the `/setup/*` details in that one skill so a contract change
+updates it once.
+
+## Install this skill (and its dependency) for Codex and Claude Code
+
+When the task includes installing this skill, install its canonical Claude
+package **and** the desktop skill it depends on, then mirror both unchanged
+`SKILL.md` files where Codex loads global skills:
+
+```sh
+for pkg in setting-up-agent-relay-sessions setting-up-agent-relay-desktop; do
+  npx prpm install "@agent-relay/$pkg" --as claude --global -y
+  codex_skill="$HOME/.codex/skills/$pkg"
+  mkdir -p "$codex_skill"
+  install -m 0644 "$HOME/.claude/skills/$pkg/SKILL.md" "$codex_skill/SKILL.md"
+  cmp "$HOME/.claude/skills/$pkg/SKILL.md" "$codex_skill/SKILL.md"
+done
+```
+
+With skills.sh instead, use the command under **Requires**; it installs into each agent's skills folder directly, so the manual Codex mirror below is only for the prpm route.
+
+Do not use prpm's `--as codex` conversion for these packages: it writes under
+`~/.agents/skills`, which Codex does not load as its global skill folder, and it
+drops explanatory paragraphs from the Markdown workflow. Confirm both final
+paths explicitly before continuing.
+
+## Why ordering matters
+
+MCPs load at agent **startup**. The agent-sessions MCP must be installed
+**before** the session that will use it starts. A session already running when
+the MCP was added has no handoff tools and must be **restarted**. Install the
+MCP (section 3) before relying on the tools (sections 4–5); if this very session
+predates the MCP, say so and restart it rather than reporting missing tools as a
+failure.
+
+## Token handling
+
+The token must never land in the agent conversation, in a Relay message, in
+process argv, or in the repo. Three places leak it, and this skill avoids all
+three:
+
+- **The chat** — this session is uploaded and teammate-readable, so a token
+  pasted to the agent leaks to the workspace. The person sets it themselves (see
+  below); the agent only ever sees the variable **name**.
+- **Process argv** — a token interpolated into `claude mcp add --header
+  "... Bearer $TOKEN"` is visible to `ps` and gets written literally into
+  `~/.claude.json`. Pass the unexpanded placeholder `${AGENT_RELAY_SESSIONS_TOKEN}`
+  instead; Claude Code expands `${VAR}` in MCP headers from the environment at
+  launch, so the stored config holds only a reference and argv holds only the
+  literal `${…}`. **This expansion exists only in Claude Code ≥ 2.1.119** — an
+  older client sends the placeholder literally and auth fails, so check the
+  version first (section 3) and update Claude rather than inlining the token.
+- **The launching environment** — both CLIs read the token from an environment
+  variable (`${VAR}` for Claude, `--bearer-token-env-var` for Codex), so the
+  variable must exist in the environment that **launches the agent**, not in a
+  transient shell-tool subprocess (which cannot alter its parent or a later
+  process).
+
+Use the single variable name `AGENT_RELAY_SESSIONS_TOKEN` throughout. Keep the
+one-time entry separate from durable supply:
+
+- **One-time, into the current shell** (non-echoing, run by the person, never
+  the agent): `read -rs AGENT_RELAY_SESSIONS_TOKEN && export AGENT_RELAY_SESSIONS_TOKEN`,
+  then launch the agent from *that* shell. Do **not** add this `read` to a shell
+  profile — every shell that sources the profile would block waiting for input.
+- **Durable across restarts:** store the token in the OS keychain or a mode-0600
+  file, and have the launcher export it **non-interactively**, e.g.
+  `export AGENT_RELAY_SESSIONS_TOKEN="$(security find-generic-password -s agent-relay-sessions -w)"`
+  (macOS keychain) or from a 0600 file. Put that line in a dedicated launcher the
+  person starts the agent from — not an interactive prompt in the profile.
+
+The agent never prints the value; verify presence only with
+`test -n "${AGENT_RELAY_SESSIONS_TOKEN:-}"`.
+
+## 0. Preflight: collect the human inputs first
+
+Before section 1, tell the person what they need and ask for it in one message:
+
+1. the **shared workspace id** (or the teammate/admin who invited them);
+2. a **Bearer token** minted in the dashboard's "Connect your agent" card for
+   that workspace, stored by *them* as `AGENT_RELAY_SESSIONS_TOKEN` in the
+   environment that launches their agent (see **Token handling** — never pasted
+   into this chat);
+3. the **teammate's relay address** for the round trip, if one will be online.
+
+Before sending that message, check what this machine already has. If an Agent
+Relay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not
+the `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only
+checks. Without one, section 2 reads the signed-in workspace from
+`/setup/status` instead. The CLI is optional for this skill: check with
+`command -v agent-relay` and `agent-relay --version`, and do not install or
+upgrade it just for these checks.
+
+```sh
+agent-relay cloud whoami       # signed in, and as whom
+agent-relay workspace active   # the active Cloud workspace (keys stay masked)
+agent-relay cloud workspaces   # every workspace this login can use, with ids
+agent-relay status             # workspace, cloud login and local broker
+```
+
+If the active workspace is already the shared one, confirm it with the person
+instead of asking them to look it up. Never switch to or create another
+workspace unless they explicitly ask.
+
+Check presence without printing the value:
+
+```sh
+test -n "${AGENT_RELAY_SESSIONS_TOKEN:-}" && echo token=present || echo token=missing
+```
+
+A missing token does **not** block sections 1–3: the MCP config stores only a
+`${AGENT_RELAY_SESSIONS_TOKEN}` reference, never the value, so it can be added
+now. Do the desktop work and add the MCP, then have the person restart the agent
+**once**, from an environment that exports the token, so that single restart both
+loads the MCP and supplies the credential. Sections 4–5 are gated on that
+restart. If the person would rather not defer, they can export the token and
+restart first, which then costs a second restart only if the MCP was added after.
+
+## 1. Confirm the host and this session
+
+Run every command from this agent's own shell tool, and only from a **genuine
+interactive** Claude Code or Codex session. The app identifies the caller from
+kernel credentials and resolves its process ancestry against discovered live
+sessions, so a command from an unrelated terminal — or from a non-interactive
+`codex exec` / `claude -p` run — is rejected with `not_a_relay_session`. (This
+is verified: a plain SSH shell and a `codex exec` invocation are both refused;
+an interactive session is admitted.)
+
+```sh
+uname -s; uname -m
+test -n "${SSH_CONNECTION:-}" && printf 'transport=ssh\n' || true
+test -n "${TMUX:-}" && printf 'session=tmux\n' || true
+```
+
+Define the request helper once per shell. It finds the private setup socket
+without printing private files and uses the desktop's `agent-relay-probe` on
+macOS (the system `curl` hides a Codex session's identity there and is refused
+`not_a_relay_session`), `curl` elsewhere, and stops with a message for a macOS
+Codex session that has no probe:
+
+```sh
+pointer="$HOME/.agentworkforce/desktop/relay-socket"
+if test -r "$pointer"; then relay_socket=$(sed -n '1p' "$pointer"); fi
+if test -n "${relay_socket:-}" && ! test -S "$relay_socket"; then unset relay_socket; fi
+if test -z "${relay_socket:-}" && test "$(uname -s)" = Linux; then
+  for c in "${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock" "/run/user/$(id -u)/agent-relay/relay.sock"; do
+    if test -S "$c"; then relay_socket=$c; break; fi
+  done
+fi
+if test -z "${relay_socket:-}" && test "$(uname -s)" = Darwin; then   # pointer file missing: use the app's own socket
+  c="$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock"
+  if test -S "$c"; then relay_socket=$c; fi
+fi
+relay_probe=
+for c in "$HOME/.local/bin/agent-relay-probe" \
+         /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \
+         "/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe"; do
+  if test -x "$c"; then relay_probe=$c; break; fi
+done
+if test -z "$relay_probe" && test -d "$HOME/.local/lib/agent-relay"; then   # per-user tarball
+  relay_probe=$(find "$HOME/.local/lib/agent-relay" -type f -perm -u+x \
+    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)
+fi
+# relay_req METHOD PATH [JSON-BODY]
+relay_req() {
+  if ! test -S "${relay_socket:-/nonexistent}"; then
+    echo 'No Agent Relay socket found; start Agent Relay (the desktop) and retry.' >&2
+    return 1
+  fi
+  if test "$(uname -s)" = Darwin && test -n "$relay_probe"; then
+    printf '%s' "${3:-}" | "$relay_probe" relay socket-request \
+      --socket "$relay_socket" --method "$1" --path "$2"
+  elif test "$(uname -s)" = Darwin && test -n "${CODEX_THREAD_ID:-}"; then
+    echo 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.' >&2
+    return 1
+  elif test -n "${3:-}"; then
+    # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename
+    printf '%s' "$3" | curl -sS --unix-socket "$relay_socket" -X "$1" \
+      -H 'Content-Type: application/json' --data-binary @- "http://relay$2"
+  else
+    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+  fi
+}
+```
+
+**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
+take about 30 seconds on a busy Desktop (tracked in
+AgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add
+`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a
+failure. The probe's `relay socket-request` can give up sooner with "Probe
+could not finish. Check your connection and run setup again"; on these paths
+that is the same latency, not a setup problem. Retry once before reporting a
+blocker, and do not rerun desktop setup because of it.
+
+## 2. Make sure the desktop is set up first
+
+Session handoff needs a signed-in, healthy desktop underneath it. If the socket
+is missing, or `/setup/status` returns `404`, or sign-in/uploader/registration
+are not in the finished state below, **invoke the `setting-up-agent-relay-desktop`
+skill** (`/setting-up-agent-relay-desktop`; if it is not installed, see **Requires**), let it run to completion, and then
+return to section 2's verification. Do not re-implement its install, sign-in, or
+`/setup/*` steps here — that skill is the single source of truth for them, and
+this skill resumes once it reports a registered, signed-in session.
+
+Verify the desktop state this skill depends on:
+
+```sh
+relay_req GET /setup/status | jq '{
+  version: .data.version,
+  sign_in: .data.sign_in,
+  workspace: .data.workspace,
+  sharing_mode: .data.sharing_mode,
+  uploader: .data.uploader,
+  direct_delivery: .data.direct_delivery,
+  session: .data.session,
+  defaults_error: .data.defaults_error
+}'
+```
+
+Require all of these before continuing, and stop with a clear message if any
+fails. `/setup/status` reports sign-in as the string `sign_in` (match the desktop
+skill), and the flag that actually governs whether **this** session's handoff
+replies arrive live is the session-level `session.direct_delivery`, not the
+top-level default — require both:
+
+```sh
+relay_req GET /setup/status | jq -e '
+  .ok
+  and .data.sign_in == "signed_in"
+  and (.data.workspace.id | type == "string" and length > 0)
+  and .data.uploader.healthy == true
+  and .data.direct_delivery == true
+  and (.data.session.id | type == "string" and length > 0)
+  and .data.session.registered == true
+  and .data.session.direct_delivery == true'
+```
+
+Confirm `workspace.id` is the **shared** workspace both sides agreed on. A
+healthy uploader is the one non-obvious prerequisite: for a teammate's agent to
+read **this** person's session, this machine must have uploaded it. If
+`uploader.healthy` is false (paused, or a failed cycle), fix it before promising
+anyone can read this session — this is the single most common reason a live
+handoff silently fails.
+
+`sharing_mode` decides which sessions upload at all. `new` and `all` include
+this session. Under `selected`, only the sessions the person chose upload, so a
+teammate cannot read this one until the person selects it. Tell them that and
+ask; do not change the sharing mode or select sessions on their behalf.
+
+## 3. Install the agent-sessions cloud MCP (before the session uses it)
+
+Check whether the token is present in the environment **without printing it**
+(see **Token handling**). It is not required to *add* the MCP, since only a
+reference is stored, but it is required for the tools to authenticate after the
+restart. If it is missing, add the MCP anyway, tell the person plainly that the
+tools will fail auth until they restart the agent from an environment that
+exports `AGENT_RELAY_SESSIONS_TOKEN`, and do not report setup complete:
+
+```sh
+if ! test -n "${AGENT_RELAY_SESSIONS_TOKEN:-}"; then
+  echo 'AGENT_RELAY_SESSIONS_TOKEN is not set here; the MCP will be added by reference, but the agent must be restarted from an environment that exports it.' >&2
+fi
+```
+
+Detect which agent CLI this session runs and install accordingly.
+
+Claude Code — pass the **unexpanded** placeholder so the token stays out of argv
+and out of `~/.claude.json`; Claude expands `${VAR}` in MCP headers from the
+environment at launch. This expansion requires **Claude Code ≥ 2.1.119**, so
+verify the version first and update rather than inlining the token on an older
+client. Single-quote the header so the shell does not expand it here. Default
+scope is `local` (this project only), which is what you want:
+
+```sh
+claude_ver=$(claude --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if test -z "$claude_ver" || test "$(printf '%s\n2.1.119\n' "$claude_ver" | sort -V | head -1)" != 2.1.119; then
+  echo "Claude Code $claude_ver does not expand \${VAR} in MCP headers (need >= 2.1.119); update Claude Code before adding this server." >&2
+  exit 1
+fi
+claude mcp add --transport http agent-relay-sessions \
+  https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \
+  --header 'Authorization: Bearer ${AGENT_RELAY_SESSIONS_TOKEN}'
+claude mcp list | grep -F agent-relay-sessions
+```
+
+Codex — `codex mcp add` records the **variable name**, not the value, and writes
+to user-level `~/.codex/config.toml`, so the server is enabled for **all** Codex
+projects (Codex has no project-scoped MCP). Confirm the person is OK with
+user-wide access before adding it:
+
+```sh
+codex mcp add agent-relay-sessions \
+  --url https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \
+  --bearer-token-env-var AGENT_RELAY_SESSIONS_TOKEN
+codex mcp list | grep -F agent-relay-sessions
+```
+
+Because MCPs load at startup, the running session must be **restarted** to pick
+up the server — and because both CLIs read the token from the environment at
+launch, the restarted process must **inherit** `AGENT_RELAY_SESSIONS_TOKEN`.
+That is why the variable belongs in the shell profile / launcher, not a transient
+shell-tool subprocess: an `export` in this agent's shell tool cannot reach the
+parent or a freshly launched session. After the restart, re-verify presence with
+`test -n "${AGENT_RELAY_SESSIONS_TOKEN:-}"` before using the tools, and do not
+report the tools as missing without first confirming the session started *after*
+the MCP was added and with the variable set.
+
+## 4. Confirm the handoff tools loaded
+
+In the session that started after the MCP was added, confirm the tools are
+present before using them. List this session's MCP tools and check for the
+agent-sessions set; the authoritative check is that the tools actually appear to
+this agent:
+
+```sh
+# Claude Code: the tools surface as mcp__agent-relay-sessions__*
+claude mcp list | grep -F agent-relay-sessions
+```
+
+Then call `list_relay_agents` through the MCP (an MCP tool call, not a shell
+command). A successful call that returns the workspace roster proves the MCP is
+loaded, the token is valid, and this session can see the shared workspace. If
+the call errors with auth, the token is wrong or for another workspace — have
+the person re-mint it from the correct workspace's dashboard.
+
+## 5. Prove one live round trip
+
+The real proof is agent-to-agent, so it needs a counterpart. Pick the path that
+matches what is available:
+
+**A teammate's agent is online (full round trip).** Ask the person for the
+teammate's relay address (e.g. `@manav`), then:
+
+1. `list_relay_agents` — confirm the teammate's address is listed.
+2. **Prove the reverse read path first:** call `get_shared_session_context` on
+   the teammate's session and confirm it returns their **real** content (prompts/
+   events + a dashboard citation link). If it errors or is empty, their uploader
+   is unhealthy — stop and have them fix it; do not declare GREEN, because this
+   side cannot actually read their work yet.
+3. `send_relay_message` — send a short, uniquely-marked message to that address.
+4. The teammate's agent reads this session with `get_shared_session_context` and
+   continues; have them reply through the relay.
+5. GREEN requires **both directions**: this agent read the teammate's real
+   content (step 2) **and** the teammate's reply lands here. There is no
+   automatic ack — confirm by the reply/activity, not a push. Because Relay
+   injects an inbound message only when the session is idle between turns, **end
+   the turn** after sending and confirm the reply on the next turn; do not sleep
+   or poll inside one turn.
+
+**No teammate online yet (self-verify the read path).** Prove the machinery
+without a second person:
+
+1. `list_relay_agents` returns the roster — MCP + token + workspace are good.
+2. `search_shared_sessions` / `get_shared_session_context` return this person's
+   **own** recently uploaded session (real prompts/events plus a dashboard
+   citation link) — the uploader→read path works.
+3. Record that the two-party round trip still needs the teammate online, and
+   name it as the remaining step rather than claiming the handoff is proven.
+   Setup is not complete until the full round trip succeeds.
+
+Never paste the Bearer token or any session token into a `send_relay_message`
+body or any artifact.
+
+## 6. Report
+
+Separate verified facts from what still needs a human or a second machine:
+
+- app version, `signed_in`, the signed-in **workspace id and name**;
+- uploader `healthy`, this session's `agent@machine` address, direct delivery on;
+- agent-sessions MCP installed and its tools confirmed loaded in this session;
+- `list_relay_agents` roster seen; and either the full round-trip evidence (the
+  teammate's real content + reply) or the self-verified read path plus the named
+  remaining step (teammate online).
+
+Do not call the setup complete on a 2xx from `claude mcp add` alone, and do not
+count a roster listing as a proven handoff.
+
+## Recovery
+
+- **`not_a_relay_session` from `/setup/*`:** the caller is not inside a discovered
+  interactive session. Run it from this agent's own shell inside an **interactive**
+  Claude Code or Codex session — a non-interactive `codex exec` or `claude -p` run
+  is not admitted, and neither is an unrelated terminal. In tmux/SSH, confirm the
+  agent process and shell share the pane's process tree.
+- **No handoff tools in the session:** the MCP was added after the session
+  started, or at the wrong scope. Reinstall at project scope (section 3) and
+  **restart** the session; MCPs load only at startup.
+- **`list_relay_agents` auth error:** the token is wrong, expired, or from a
+  different workspace. Because the MCP config stores only a **reference** to
+  `AGENT_RELAY_SESSIONS_TOKEN`, fixing it means updating the **value in the
+  launch environment** (keychain / 0600 file) and **restarting** the agent so it
+  re-reads it — re-running `claude mcp add` / `codex mcp add` alone changes
+  nothing. Re-mint from the intended workspace's "Connect your agent" card if the
+  token itself is bad. On Claude, also confirm the client is ≥ 2.1.119 (older
+  clients send the `${VAR}` placeholder literally).
+- **Teammate's address missing from the roster:** they are not on the **same**
+  workspace, or their session is not on the relay. Have them register their
+  session and confirm the shared workspace id.
+- **Can't read the teammate's session:** their **uploader** is not healthy
+  (paused or a failed cycle). Have them check `/setup/status` shows
+  `uploader.healthy == true`, not "Sync paused/offline".
+- **Message arrives held, not live:** direct delivery is off for the recipient —
+  POST `{"enabled":true}` to `/setup/direct-delivery` on their machine (Codex
+  delivers directly by default). A managed Claude policy can block this; report
+  it rather than editing managed settings.
+- **Remove the MCP:** `claude mcp remove agent-relay-sessions` /
+  `codex mcp remove agent-relay-sessions`. This removes only the handoff tools;
+  it does not sign the desktop out or stop uploads.
+
+## Relationship to the other skills
+
+- **`setting-up-agent-relay-desktop`** — the layer below this one: install,
+  sign-in, agent-led defaults, self-registration. Use it when section 2 is not
+  yet satisfied.
+- **`relay-connect`** — a lighter, account-free, time-boxed way for two agents to
+  share one session via a hand-over link. Prefer it for an ad-hoc pairing;
+  prefer this skill for durable teammate-to-teammate handoff inside a shared
+  workspace.
diff --git a/web/content/setup-skills/signing-in-to-agent-relay-cloud.md b/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
new file mode 100644
index 00000000..caa0e273
--- /dev/null
+++ b/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
@@ -0,0 +1,111 @@
+# Sign In to Agent Relay Cloud
+
+Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
+or pre-existing Agent Relay account is required. Only the human approves the
+sign-in; never approve access on their behalf, ask for their password, or
+operate the approval page yourself.
+
+Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
+including its `/cloud` prefix. When a guide names a different Cloud base (for
+example a local development stack), use that exact base throughout and never
+fall back to production.
+
+## HTTP client
+
+Use `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their
+default User-Agent: the device-token endpoint answers them with HTTP 403 and no
+JSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth
+response while debugging; on success it contains tokens. Send JSON request
+bodies with `Content-Type: application/json`, set a 30-second request timeout,
+and check every response status before proceeding.
+
+## 1. Start the device grant
+
+`POST /api/v1/auth/device/start` with:
+
+```json
+{"client_name":"My agent setup"}
+```
+
+An agent-driven signup guide also passes its product as `signup_source`
+(`"teams"` or `"flows"`); keep the value the guide names. Omit it otherwise.
+
+Expect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,
+`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep
+`device_code` private. Open `verification_uri_complete` in the person's
+browser with the OS URL opener (for example macOS `open`, with the URL passed as
+a separate argument, never interpolated into shell code), or give them the link
+if no opener is available. Show the `user_code` so they can compare it. The page
+lets them sign in with Google, review the requesting device, and Approve or
+Deny. A signup marker in the returned URL creates the right account type;
+preserve it through sign-in. Do not call `/auth/device/approve` yourself.
+
+For a fresh signup, you can open
+`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`
+first, where `encoded-return-path` is the URL-encoded pathname plus query of
+`verification_uri_complete`. This opens Google immediately and returns to the
+same device approval with its code and signup marker intact.
+
+## 2. Poll for tokens
+
+While the browser is open, wait `interval` seconds between POSTs to
+`/api/v1/auth/device/token` with this JSON (substitute the private
+`device_code`):
+
+```json
+{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}
+```
+
+- `authorization_pending`: keep waiting; respect a returned interval.
+- `slow_down`: increase the interval by at least 5 seconds.
+- HTTP 429: respect `Retry-After` and increase the interval.
+- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.
+- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start
+  a new grant only if the person still wants to continue. Never poll past
+  expiry.
+
+HTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,
+`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in
+memory or a private file (directory 0700, file 0600) outside repositories.
+Never echo tokens, put them in chat or URLs, or dump full authentication
+responses. Use `Authorization: Bearer <access_token>` for subsequent Cloud
+requests. Reject an `api_url` pointing at another origin; keep using the Cloud
+base above.
+
+## 3. Refresh before expiry
+
+Before expiry, `POST /api/v1/auth/token/refresh` with
+`{"refreshToken":"<refresh_token>"}`. The response uses camelCase:
+`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,
+`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the
+refresh token rotates and must not be shared between machines. An
+invalid/expired refresh requires a new device login, not an endless retry.
+
+## 4. Read the account and workspace
+
+`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,
+`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups
+create a workspace automatically. Reuse it; do not create duplicate
+accounts/workspaces. If `currentWorkspace` is missing, or an existing account
+is in the wrong workspace, resolve that with the person before connecting or
+activating anything. Never silently replace an existing connection to another
+account.
+
+## 5. Hand the session to the official CLI
+
+When running a child process, pass these through its environment from your
+private session object (never interpolate their values into logged commands):
+
+```text
+CLOUD_API_URL=https://agentrelay.com/cloud
+CLOUD_API_ACCESS_TOKEN=<access_token>
+CLOUD_API_REFRESH_TOKEN=<refresh_token>
+CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
+CLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>
+```
+
+The official CLI consumes this session. Refresh the parent session before
+starting a long command; do not concurrently refresh it from parent and child
+processes. Do not overwrite an existing CLI auth file or copy a session to
+another machine. Delete temporary authentication files after the work is
+complete.
diff --git a/web/content/setup-skills/writing-relayflows.md b/web/content/setup-skills/writing-relayflows.md
new file mode 100644
index 00000000..2ebed493
--- /dev/null
+++ b/web/content/setup-skills/writing-relayflows.md
@@ -0,0 +1,539 @@
+# Writing Relayflows
+
+## Overview
+
+Relayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real — a journal write that fails fails the step, with no silent fallback.
+
+**Name collision warning.** This repo also has skills for an older, unrelated engine that is *also* casually called "Relayflow" (singular) — `@relayflows/core`'s `WorkflowBuilder`, a chained builder (`workflow('name').pattern('dag').agent(...).step(...).run()`). That's `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`'s territory. This skill is the **v2** engine: `@relayflows/surface`'s `flow()` function and the YAML/JSON dialect compiled by `@relayflows/sdk`. If you see `.pattern(`, `.agent(` as a chained builder call, or `ctx.workflow.run()`, you're in the other engine — stop and use one of those skills instead.
+
+## When to use this skill
+
+- Writing a new `.flow.ts` or `.flow.yaml`/`.flow.json` for the `flows` CLI (package `@relayflows/sdk`, binary name `flows`).
+- Deciding whether a step needs `run` (shell), `llm` (bare model call), or `agent` (harnessed coding agent in a workspace).
+- Choosing a verification gate that will actually run — a wrong choice here compiles fine and fails at `flows run` time, not authoring time.
+- Wiring up `cli`/`model` for an `agent` or `llm` step, in either language.
+- Debugging a `REFUSED [...]` message from `flows check` or `flows run`.
+- Deciding between running a flow locally, deploying it to listen for tickets, or scheduling it on a cron.
+
+## The ladder
+
+Three step verbs, one per rung (`@relayflows/sdk`'s `StepType = 'deterministic' | 'llm' | 'agent'`):
+
+1. **`run` / `deterministic`** — a shell command. No model. Implicit gate is `exit_code == 0`.
+2. **`llm` / `llm`** — a bare model call. Prompt in, verified output out. No workspace, no tool use.
+3. **`agent` / `agent`** — a harnessed coding agent in a workspace. Returns `{ summary, artifacts }`, not raw text.
+
+Plus resident verbs that aren't ladder rungs: `human` (durable approval), `dispatch` (a direct child flow declared in `use`), and `done` (typed finish). `dispatch` executes in `2.0.35` and newer; see **Human approval and direct child flows**. The generated **helper** namespace (`f.slack`, `f.github`, `f.linear`, `f.notion`, `f.jira`, and 30+ others — see **Helpers**) and YAML `on`/triggers are separate surfaces.
+
+Most flows only need `run` and `llm`. Climb to `agent` once a step needs hands on a real workspace.
+
+## Two ways to author the same thing
+
+**YAML/JSON** is data: `flows check` or CI can validate it without running anything. **TypeScript** calls the same primitives imperatively as ordinary async code. Both compile to the same journal.
+
+### TypeScript
+
+```ts
+import { flow } from '@relayflows/surface';
+
+export default flow('hello', { budget: { wallclock: '10m' } }, async (f) => {
+  const greeting = await f.run('echo "Hello from Relayflows"');
+  console.log(greeting.trim());
+
+  const answer = await f.agent('greeter', {
+    task: 'Reply with one short hello sentence. Do not use tools or modify files.',
+    cli: 'claude',
+    model: 'claude-sonnet-4-6',
+  });
+  console.log(answer.summary);
+
+  f.done('success');
+});
+```
+
+### YAML
+
+```yaml
+version: '0.1.0'
+name: hello
+steps:
+  - id: greeting
+    type: deterministic
+    command: 'echo "Hello from Relayflows"'
+  - id: greeter
+    type: agent
+    dependsOn: [greeting]
+    instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'
+    cli: claude
+    model: claude-sonnet-4-6
+```
+
+**Version note.** The contracts below were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations. Direct `use`/`f.dispatch` composition requires `2.0.35` or newer. `AgentOptions.permissions` landed in `2.0.17`; predicate `.gate()` and `artifact_exists` landed with [flows#449](https://github.com/AgentWorkforce/flows/pull/449); `f.human` was already executable in `2.0.22`.
+
+## The real `Ctx` contract (TypeScript)
+
+From the shipped `@relayflows/surface@2.0.35` `.d.ts` files (`dist/context.d.ts`, `dist/step.d.ts`, `dist/flow.d.ts`, `dist/completion.d.ts`):
+
+```ts
+export interface AgentResult {
+  summary: string;
+  artifacts: string[];
+}
+
+export interface PermissionsSpec {     // exported from the package root
+  fileGlobs?: string[];
+  networkAllowlist?: string[];
+  accessPreset?: 'readonly' | 'readwrite';
+}
+
+export interface AgentOptions {
+  task: string;
+  workspace?: string;
+  permissions?: PermissionsSpec;         // since 2.0.17 — declared and journaled, NOT enforced
+  cli?: string;
+  model?: string;
+  cwd?: string;                          // working dir for the CLI subprocess; defaults to the flow-runner's cwd
+  transport?: 'direct' | 'relay';        // see Agent-relay transport, below
+}
+
+export interface LlmOptions {
+  output: Record<string, unknown>;       // JSON Schema, checked before the journal accepts the result
+  cli?: string;
+  model?: string;
+}
+
+export interface DispatchResult {
+  name: string;
+  completionReason: 'success';
+  completionDetail?: string;
+}
+
+export interface Ctx extends Helpers {   // Helpers = f.slack, f.github, f.linear, f.notion, ... — see Helpers
+  readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;
+  run(command: string, options?: { timeout?: string | number }): Step<string>;
+  llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
+  llm(prompt: string, options: LlmOptions): Step<unknown>;
+  agent(name: string, options: AgentOptions): Step<AgentResult>;
+  human(question: string, options: { to: string }): Step<boolean>;
+  dispatch(flow: string, input: unknown): Step<DispatchResult>;
+  done(reason: FlowCompletionReason): void;
+  cloud: CloudHelper;
+  memory: MemoryHelper;
+}
+```
+
+Do not add fields to `AgentOptions`/`Ctx` that aren't in this list — they don't exist in the shipped SDK. In particular: **no flow-level named-agent selector on `f.agent`, no `recoveryMode`/`surfaces`/`output`** on the TypeScript call site. Those stay YAML/JSON step fields. `FlowHeader` (`dist/flow.d.ts`) allows `use`, `identity`, `memory`, `budget`, `tools`, `workspace` — no bare `agents` map key (TypeScript composes reusable flows via `use: string[]` instead — see **Named agents and flow composition**). An unknown *header* field throws a `TypeError` at authoring time, before anything is journaled; an unknown `AgentOptions` field is caught by `tsc`, not at runtime.
+
+**`permissions` is a real TypeScript option and it does not sandbox anything.** Since `2.0.17` it is on `AgentOptions`, validated by the SDK, lowered to `file_globs`/`network_allowlist`/`access_preset` and journaled with the step — and nothing reads it to gate a file or a network call. `flows check` warns `permissions_unenforced` on any declaration, including `{}`. Enforcement is [flows#442](https://github.com/AgentWorkforce/flows/issues/442). Declare it to record intent; do not rely on it to contain an agent.
+
+`run()`'s second argument is a real, current option: `{ timeout?: string | number }` — a duration string (`"15m"`) or milliseconds. Every real cookbook example that runs something slower than a few seconds sets this explicitly.
+
+### `f.done()`'s closed set is six values, not four
+
+```ts
+export const FLOW_COMPLETION_REASONS = ['success', 'step_failed', 'canceled', 'budget_exceeded', 'needs_human', 'declined'] as const;
+```
+
+An authored body can meaningfully call `f.done('success')`, `f.done('step_failed')`, `f.done('needs_human')` (parks the run — it's not a kernel cancellation), or `f.done('declined')` (a deliberate decision not to act — also not a cancellation). `'canceled'` and `'budget_exceeded'` exist in the same closed set but are the **kernel's** to record; a body calling them itself is calling the wrong verdict for what actually happened. The verdict for a human declining a durable approval is `f.done('declined')`, not `f.done('canceled')` — a human declining is a decision, not the kernel calling off the run.
+
+`Step<T>` (`dist/step.d.ts`) is a `PromiseLike<T>` with one extra method, `.gate(...)` — see **Verification gates**. Every awaited step must actually be awaited — an unawaited or manually-`.then()`-chained step is refused (`unawaited_step` / a manual `.then()` is not an await), not silently dropped.
+
+## Verification gates
+
+Verification is control flow, not decoration — a gate decides whether a step actually completed, not just whether the process exited cleanly.
+
+### YAML/JSON (`@relayflows/sdk`'s `VerificationSpec`)
+
+```ts
+export type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate | NamedDataGate;
+// NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate
+//              | ArtifactExistsGate
+```
+
+- `exit_code` — implicit default for `deterministic` steps. Not configurable; writing it explicitly is allowed and compiles to the same thing as omitting it.
+- `output_contains` — step output (stdout tail, or the LLM value stringified) contains `value`.
+- `json_schema` — step output validates against a JSON Schema (`boolean | Record<string, unknown>`). Used for structured LLM/agent output; `output?: JsonOutputSchema` on an `llm`/`agent` step is sugar that compiles to this.
+- `subprocess_gate` — runs `command` under `/bin/sh`, judged on its exit code. The gate that actually works for "check a file the agent wrote": `{ type: 'subprocess_gate', command: 'test -s review.md' }`. If you also need to inspect the step's own output (via `from_output`), the SDK's generated wrapper reads its internal `FLOWS_INPUT` env var, extracts the value, and passes it to *your* command as `$INPUT` — `FLOWS_INPUT` itself is never visible to the author's command, only `$INPUT` is: `{ type: 'subprocess_gate', command: 'echo "$INPUT" | grep -q PASSED', from_output: ['summary'] }`.
+- `regex_match` — the step's output (or a value at `in_output_at`) matches `pattern`, evaluated by a non-backtracking RE2 engine (only `i`, `m`, `s` flags).
+- `artifact_exists` — passes when the step's journaled `artifacts` list contains `path` (working-directory-relative POSIX). It reads the journal, not the disk, so it sees exactly what the worker measured at `step.completed`; a path the worker never journaled reads as missing even when the file is there.
+- `word_count_bounds`, `references_input` — narrower named gates; see `packages/sdk/src/named-gates.ts` in the flows repo for the exact contract.
+
+```yaml
+- id: classify
+  type: llm
+  prompt: 'Classify this ticket as bug, feature, or question: "the export button does nothing"'
+  cli: claude
+  model: claude-sonnet-4-6
+  verification:
+    type: output_contains
+    value: bug
+```
+
+### TypeScript (`Step<T>.gate(...)`) — read this before you write one
+
+`Step<T>` has **two** overloads, and **one `.gate()` per step** — a second throws `unsupported_gate`:
+
+```ts
+gate(config: NamedGate): Step<T>;
+// NamedGate = ReferencesInputNamedGate | SubprocessNamedGate | WordCountBoundsNamedGate
+//           | RegexMatchNamedGate | ArtifactExistsNamedGate
+// — the surface-visible subset of NamedDataGate above. Data, not code: `flows check` can prove it.
+
+gate(predicate: (value: T) => boolean, because?: string): Step<T>;
+// Runs since flows#449. The executor calls the closure once, on the journaled value, and
+// journals the VERDICT as a lowered `<step>.gate` step — so resume and replay read the
+// recorded verdict and never re-run the function. A false verdict fails the run as
+// `gate_failed`, carrying `because`.
+```
+
+The predicate form was refused with `unsupported_gate` through `2.0.16`; on `2.0.22` it runs. **Prefer the config-object form anyway** — `flows check` cannot prove a predicate (docs/SURFACE.md §6), so a named gate is the only kind a preflight can tell you about before you spend a run:
+
+```ts
+const outdated = await f.run('npm outdated --json 2>/dev/null || true')
+  .gate({ type: 'subprocess_gate', command: 'test -n "$INPUT"' });   // provable by `flows check`
+
+const review = await f.agent('review', { task: '…', cli: 'claude' })
+  .gate({ type: 'subprocess_gate', command: 'test -s review.md' });  // checks a file the agent wrote, ignores $INPUT
+```
+
+(Verified for real: `.gate({ type: 'subprocess_gate', command: 'test -n "$INPUT" && echo "$INPUT" | grep -q pkg' })` against a step outputting `{"pkg":"left-pad"}` passes — `$INPUT`, not `$FLOWS_INPUT`, is what the author's command sees. `FLOWS_INPUT` is an env var the SDK's own generated wrapper reads internally to extract the value before invoking your command; it is never visible to `command` itself.)
+
+An agent step rarely fails by crashing; it fails by returning something plausible and wrong, which a plain retry-on-error never catches. Validate every `agent`/`llm` result, either directly with a supported gate or in a following deterministic verifier.
+
+**Where to put that check depends on what you want a red result to do.** A config-object or predicate gate directly on the agent/LLM step ends the run when it fails; use it when that failure should be terminal. For repairable failures, the following deterministic verifier must explicitly read the preceding output or workspace, produce its own verification result, and record it for repair. Output-dependent gates inspect the step they guard: moving the same gate unchanged would inspect the verifier's output, not the agent's. Use the record/repair/re-record/assert pattern in `relay-80-100-workflow`, gating the final verification result after repair.
+
+## Helpers: journaled effects, not just Slack
+
+`Ctx extends Helpers`, and `Helpers` is generated from 40+ provider adapters shipped in `@relayflows/surface` — `slack`, `github`, `linear`, `jira`, `notion`, `salesforce`, `postgres`, `s3`, `redis`, `daytona`, `gmail`, `google-calendar`, `hubspot`, and more (`dist/helpers/index.d.ts` lists them all). A helper call — `f.slack.post(channel, text)`, `f.github.comment(...)` — compiles to a journaled effect: the receipt the helper returns *is* the journal record, so a retried step that already posted doesn't double-post; the second attempt is deduped by `(step_id, idempotency_key, surface_path)`.
+
+Two things every helper call needs:
+
+- **A relayfile mount for that provider**, locally — `flows check` refuses `helper_slack.credential_missing` (or the equivalent for another provider) without one. Cloud provides a mount for every connected provider automatically.
+- **A declared intent** on the flow header: `tools: { slack: true }` in TypeScript, or the equivalent in YAML. Forgetting this is a separate, earlier failure than the mount check.
+
+For local development without standing up a real provider mount, prefix the run with the provider's mock env var — `RELAYFLOWS_SLACK_MOCK=1 flows run ... --local-agent` records the effect (a real file under the daemon's data dir) instead of sending it. This does not exercise live delivery, and should be called out as such wherever you cite it as verification.
+
+**`tools` means two different things depending on where you write it — do not confuse them:**
+
+- `FlowHeader.tools` (TypeScript) / `FlowSpec` top-level `tools` you're declaring intent on: `Partial<Record<keyof Helpers, boolean>> & { relayfile?: string[]; mcp?: string[] }` — e.g. `{ slack: true }`. This is "which helpers this flow uses."
+- `FlowSpec.tools` in the compiled YAML/JSON spec is instead `{ fs?: string | string[] }` — path-scoped **filesystem** grants, mirroring `workspace` for shell/deterministic steps. Not the same field, despite the identical name.
+- `flows.json` (the project config file) has **no** `tools` field at all — see **`flows.json`**, below. Putting a `tools` key there is refused as `config_invalid`; this is an easy, first-try mistake (made once, personally, writing this refresh).
+
+## `cli` / `model`: what a step actually runs on
+
+Both YAML and TypeScript agent/llm steps can set `cli` and `model` directly. Resolution order for `cli`, identical regardless of authoring language because both compile to the same `StepSpec`:
+
+1. **step** — `step.cli` (or TS's `options.cli`)
+2. **named** — the flow's `agents[step.agent]` entry, if the step selects one via `agent: <name>` (YAML/JSON only — TypeScript composes reusable flows via `use:` instead, not a per-step named-agent selector; see **Named agents and flow composition**)
+3. **flow** — `FlowSpec.cli` (YAML) — there is no equivalent flow-level `cli` field on the TypeScript `FlowHeader`
+4. **project** — nearest `flows.json`'s `cli`, found by walking up from the flow file's directory
+
+No resolution found at any level → `REFUSED [cli_unresolved]`, before anything is journaled, e.g.:
+
+```
+$ flows check hello.flow.yaml   # agent step, no cli anywhere
+REFUSED [cli_unresolved] Step "greeter" has no CLI at step, flow, or project level. No flows.json was found from "..." to the filesystem root.
+```
+
+`model` has **no** flow or project default — only step or named-agent. Omitting it just runs whatever model the resolved CLI defaults to.
+
+### `flows.json`
+
+Nearest-wins project config, walking from the flow file's directory to the filesystem root. The shipped SDK type (`@relayflows/sdk`'s `FlowsJson`) is exactly:
+
+```ts
+interface FlowsJson {
+  cli?: string;
+  executors?: string[];
+  models?: string[];
+  mcp?: Record<string, McpServerConfig>;
+  deploy?: { bucket: string };
+}
+```
+
+- `cli` — the project-wide CLI default (resolution rung 4 above).
+- `executors` — trigger executors this project has registered. A trigger whose `executor` isn't in this list is `no_executor`; a flow that declares `.on(...)` triggers but is invoked directly (not via a webhook) still needs its provider named here — e.g. `{ "executors": ["github"] }` for a flow with `.on(github.pull_request(...))` handlers, even when you never hit that code path.
+- `models` — **an allowlist, not a default.** Any model declared on any step or named agent anywhere in the flow must appear here, or `flows check`/`flows run` refuses `model_unknown` / `llm_cli_unresolved`. Setting `models` does not select a model for anything.
+- `mcp` — project-owned MCP server connections.
+- `deploy` — a file-bucket target for `flows deploy <flow>@sha256:<digest> --to <bucket-uri>`.
+
+**Verified for real:**
+
+```
+$ flows run hello.flow.ts --local-agent --input '{}'   # step declares model "claude-opus-5", flows.json has no models[]
+REFUSED [invalid_spec] llm_cli_unresolved: Step "llm-1" declares model "claude-opus-5" for CLI "claude",
+but it is not listed in project model registry "…/flows.json"; add the exact model only after verifying
+that project is allowed to use it.
+
+$ flows run pr-reviewer.flow.ts --local-agent --input '{...}'   # flow declares .on(github....) handlers, no executors[]
+REFUSED [no_executor] webhook trigger "github" is not registered in flows.json
+```
+
+Any other top-level key — `tools`, `budget`, `identity`, `agents` — is refused as `config_invalid`. Those are `FlowHeader`/`FlowSpec` fields on the *flow itself*, not on the project config.
+
+## Named agents and flow composition
+
+**YAML/JSON**: a named-agent map declares each `{ cli, model }` pair once; a step's `agent:` selector resolves to it at compile time, and `flows check` flags a named agent nobody selects, or one a step overrides without using.
+
+```yaml
+agents:
+  planner: { cli: claude, model: claude-opus-5 }
+  implementer: { cli: codex, model: gpt-5.6-codex }
+steps:
+  - id: plan
+    type: agent
+    agent: planner
+    instruction: '…'
+```
+
+**TypeScript** has no equivalent `agents:` map key on `FlowHeader` — the closest idiom is a plain object spread reused across calls:
+
+```ts
+const planner = { cli: 'claude', model: 'claude-opus-5' };
+await f.agent('plan', { ...planner, task: '…' });
+```
+
+What TypeScript *does* have is `FlowHeader.use?: string[]`: relative `.flow.ts` paths to direct child flows the body may call with `f.dispatch`. This is composition of complete flows, not a named-agent map. It executes in `2.0.35` and newer; see **Human approval and direct child flows**.
+
+## Parallel agents
+
+Running several agent (or any) steps concurrently is first-class, documented authoring — not a workaround:
+
+> "…`Promise.resolve`, `Promise.all`, `Promise.allSettled`, `Promise.any` and `Promise.race` over authored steps" are "ordinary, supported authoring." — `docs/SURFACE.md`, the authored operation lifecycle
+
+```ts
+const LENSES = ['security', 'correctness', 'performance'] as const;
+
+await Promise.all(
+  LENSES.map((lens) =>
+    f.agent(`${lens}-reviewer`, {
+      task: `Review this diff for ${lens} issues ONLY. Write findings to review/${lens}.json.`,
+      cli: 'claude',
+    }).gate({ type: 'subprocess_gate', command: `test -s review/${lens}.json` }),
+  ),
+);
+
+const consensus = await f.agent('consensus', {
+  task: 'Read review/*.json. Resolve disagreement between lenses. Write review/consensus.json.',
+}).gate({ type: 'subprocess_gate', command: 'test -s review/consensus.json' });
+```
+
+This is the exact shape `examples/pr-review-pipeline` in `AgentWorkforce/flows` (and the cookbook's would-be equivalent) uses: fan out, each lane writes its own file, a reconciliation step reads them all. **Disclosure worth knowing before you rely on it**: the flows package replaces the global `Promise.all` intrinsic, process-wide, for the lifetime of any authored flow execution, so the kernel can prove every concurrent step was actually awaited (rather than inferring group membership from callback identity). It delegates to the real intrinsic and restores it when the last concurrent flow closes — but any other code sharing that process sees the replacement during that window.
+
+## Agent-relay transport: dispatch, not live chat
+
+`AgentOptions.transport?: 'direct' | 'relay'` (default `'direct'`, a local subprocess). Setting `transport: 'relay'` dispatches the step to Agent Relay's own task infrastructure instead — per the shipped type's own doc comment: *"posts to agent-relay so the agent registers as a first-class workspace participant that DMs can steer."*
+
+What this actually is, per `docs/AGENT-RELAY-TRANSPORT.md`: the step calls `POST /v1/actions/task.run/invoke` against relaycast, then waits for a durable final receipt — spawn readiness and invocation acceptance do **not** complete the step, only a terminal receipt does. It needs a pre-provisioned `RELAY_AGENT_TOKEN` (a workspace API key cannot substitute) and the Relay provider running with `AGENT_RELAY_TASK_PROVIDER=1`. The dispatched worker submits its result via an injected `agent_result` tool.
+
+Don't describe this as "agents talking to each other" — there's no documented pattern in this skill's scope for two flow steps to hold a live back-and-forth over Relay channels while both are running. What's real: the step's agent becomes a genuine Agent Relay workspace participant while it runs (so a human, or another agent with the right access, can DM it and potentially steer it — per the type's own wording), and the flow still only sees a request-and-durable-receipt shape, not an open channel. Multi-agent *coordination* inside a flow today means sequential handoff (one step's return value feeds the next) or parallel fan-out (**Parallel agents**, above) — not live messaging.
+
+## Human approval and direct child flows
+
+`f.human` parks a root run on a durable approval. `f.dispatch` executes a statically declared direct child in the same durable tree on `2.0.35` and newer. Both must be awaited.
+
+`f.human` parks the run durably on a kernel `wait.human`, keyed `human-<n>` in the order the body asked. A person answers, and `flows resume` continues the body from that line:
+
+```ts
+const ok = await f.human(`Ship this?\n${plan.summary}`, { to: 'khaliq' });
+if (!ok) return f.done('declined');   // a person's "no" is declined, never canceled
+```
+
+```
+$ flows answer <run-id> human-1 yes --by khaliq --note 'reviewed the diff'
+$ flows resume <run-id>
+```
+
+`to` names who is asked and is recorded with the question — **it is not a delivery address**; nothing notifies that person for you. The kernel closes a wait once, so the first answer wins, and it records `attribution: "client_asserted"` because the daemon socket, not the kernel, authenticated whoever `--by` names. The answer step takes a `.gate(config)` like any other step. One caveat: `f.human` needs a durable root run to park in — under a runner that has none it refuses with `unsupported_verb`, so run it with `flows run`.
+
+For a composed local run, declare each direct child in the parent's static `use` header, then dispatch by the child's declared `flow(...)` name—not by its file path:
+
+```ts
+// release.flow.ts
+import { flow } from '@relayflows/surface';
+
+export default flow('release', { use: ['./implement.flow.ts'] }, async (f) => {
+  await f.run("printf '%s' prepare");
+  const child = await f.dispatch('implement', { issue: 123 });
+  await f.run("printf '%s' publish");
+  f.done(child.completionReason);
+});
+```
+
+```ts
+// implement.flow.ts
+import { flow } from '@relayflows/surface';
+
+export default flow('implement', async (f, input: { issue: number }) => {
+  await f.run(`printf '%s' ${input.issue}`);
+  f.done('success');
+});
+```
+
+`use` resolves relative `.flow.ts` files before a body runs. Missing or repeated files, duplicate direct-child names, cycles, and undeclared or transitive-only dispatch targets are refused. The child's steps receive qualified IDs such as `dispatch-2--run-1`; the dispatch receipt joins child leaves back to the parent's next step. Parent and child share one root budget and worker-capacity pool, and resume reuses journaled identities rather than repeating completed effects. A successful dispatch returns `{ name, completionReason: 'success', completionDetail? }`; any other child verdict fails the dispatch.
+
+Authority narrows: a child cannot declare a second budget, require a helper/MCP capability its parent did not grant, or call `f.human`. Static cycles are refused and runtime child depth is capped at three. This is direct authored composition, not arbitrary public-flow invocation.
+
+To put the **whole local tree** on one Cloud dashboard page, run `flows run --cloud-mirror release.flow.ts --input '{}'` (or affirmatively set `FLOWS_CLOUD_MIRROR=1`). The root, qualified child steps, dispatch receipts, dependency edges, transcripts, source, and output are projected into one connected graph; the local journal remains authoritative. Mirroring uploads that data and is opt-in. A mirror failure cannot fail the local run. The default observer link is separate and does not add the run to Cloud history.
+
+Do not confuse this with **hosted execution**. `flows run --cloud [--sync-code] release.flow.ts --input '{}'` still rejects `use` dependencies with `unsupported_source`: Cloud accepts one self-contained `.flow.ts` source. Use `--cloud-mirror` for the connected child-flow dashboard today; do not promise that Cloud can itself execute a multi-file `use` tree.
+
+**The same "types accept it, the executor doesn't" trap applies to `workspace` on an agent step under `--local-agent`.** Neither an annotated (`'acme/api: readonly'`) nor a bare (`'acme/api'`) value works — both fail identically:
+
+```
+REFUSED [invalid_spec] unsupported_workspace_permission: The local agent worker accepts
+stream-only steps. Remove workspace or attach a worker that holds its revision pins.
+```
+
+It isn't the `: readonly`/`: readwrite` annotation syntax that's rejected — it's that the local-agent worker doesn't hold workspace revision pins at all. Omit `workspace` entirely for a step you intend to run with `--local-agent`; it's a real, working field only against a worker that supports it (Cloud's). Against a worker that does hold pins, the suffix is separately refused, and the remedy the SDK's own message names is `f.agent`'s `permissions` option — which records the scope and does not enforce it.
+
+## Running it: `flows check` / `run` / `deploy` / `schedule`
+
+```
+flows check [--json] [--watch] <flow.ts|flow.yaml|spec.json>
+flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.yaml|spec.json>
+flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>
+flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <run-id>
+flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]
+flows deployments [--json]
+flows undeploy [--json] <deployment-id>
+flows schedule <flow.ts> --cron "<expr>" --tz <tz> --input <inline-json-or-file>
+```
+
+`check` is a pure compile-and-preflight — no daemon, no socket, no data dir. It's the fast, safe way to validate a flow before ever running it, and it does accept `.flow.ts` despite older `--help` text implying only YAML/JSON.
+
+**`--local-agent` is not optional decoration.** Without it, `agent`/`llm` steps have no worker to dispatch to and the run parks indefinitely rather than executing. Every local run in this skill's examples, and every real run in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook), passes it.
+
+A `.flow.ts` run via `flows run` requires `--input <inline-json-or-file>` even when the flow body ignores its input argument.
+
+**`--data-dir` gotcha, learned the hard way.** If a flow does its own git hygiene on the directory you invoke it from — `pr-reviewer`'s and similar examples' `git clean -fdq -e .workforce` when there's nothing to push — that cleanup deletes *anything else untracked in that directory*, including the daemon's own default `.relayflowd/` state if you didn't move it. The symptom is a bizarre `SQLite journal failed: unable to open database file` on the *next* run in the same checkout, because the previous run's own cleanup step deleted the very journal directory the daemon needed. Fix: put the daemon's data outside the checkout:
+
+```bash
+flows run pr-reviewer.flow.ts --local-agent --data-dir /somewhere/outside/the/repo --input '{...}'
+```
+
+**Before `flows deploy` will do anything, two things have to already be true — a correct command still fails without them:**
+
+1. **You (or whoever's driving this) are logged in.** `agent-relay cloud login` once; check with `agent-relay cloud whoami`. There's no separate `flows`-specific login — it shares the `agent-relay` Cloud session.
+2. **The workspace has a GitHub App installation covering `--repo`, and the `--on` provider is actually a connected integration** — not just declared in the command. `flows deploy` looks up the workspace's GitHub installation before it will activate a listener; with none, it refuses `flow_repository_not_connected` rather than deploying a broken one (`prepare-flow-deploy.ts` in `AgentWorkforce/cloud`). Check what's connected with `agent-relay cloud integration connections --workspace <id>` — a provider showing `degraded` instead of `ready` is not deploy-safe, even though the CLI won't tell you that until you try. This is a separate concern from your own local git push access (a personal git/`gh` credential thing, needed only for testing a flow's own `git push`/`gh pr create` steps locally) — don't conflate the two when debugging a refusal.
+
+**`flows deploy`** creates a persistent listener: each matching ticket (`--on github:labels=agent`, `linear:team=ENG`, `jira:project=OPS`, `shortcut:workspace=…`, `slack:channel=#eng`) launches one Cloud run. `flows deployments` lists what's listening; `flows undeploy <id>` stops it — verified for real this session (deployed `software-factory` against a real repo with `--on linear:team=…`, got back `{"status":"listening", ...}`, then cleanly undeployed).
+
+**`flows schedule`** puts a flow on a cron instead of a ticket trigger — newer (shipped after the `2.0.16` release line) and not yet reflected everywhere in older examples that instead show `flows run --cloud` for the same use case.
+
+**Now fixed, was broken through `2.0.16`** ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), closed): the one-shot `flows run --cloud [--sync-code] <flow.ts> --input <json>` form used to misroute authored TypeScript flows into the declarative-spec loader (`invalid_input: Cannot read or compile the declarative flow`) or refuse with a bare `http_error: HTTP 400`. Root cause: Cloud pinned an older `@relayflows/surface` than the CLI authored against, and refused the version mismatch with those opaque errors instead of naming it. Fixed in `2.0.17` (CLI side) — verified for real: `flows run --cloud --wait <flow.ts> --input '{}'` now submits successfully and returns a real run ID instead of refusing immediately. If you still hit a bare `HTTP 400`/`invalid_input` on this path, you're likely on a CLI older than `2.0.17` — update first before assuming something else is wrong. (Cloud-side reporting of the exact version mismatch, when one still exists, was tracked as a separate follow-up PR at the time of writing — the CLI's own refusal is fixed either way.)
+
+### Watching a local run: observer link vs `--cloud-mirror`
+
+New in **`2.0.32`**. A local run has two ways to be watched, and they are not the same thing:
+
+- **The observer link is the default.** Every `flows run` mints a read-only `ot_live_` link scoped to that run's own `wf-<runId>` channel and prints `Observer: <url>`. It is free, needs only a workspace key, and carries a step projection. `--no-observer-link` suppresses it.
+- **`--cloud-mirror` additionally puts the run on the Cloud dashboard** — the richer hosted view: the flow source, **every agent step's transcript**, the run graph, the run's own log, and the run sitting in the same history as your hosted ones. `FLOWS_CLOUD_MIRROR=1` turns it on for a whole shell.
+
+```bash
+flows run review.flow.ts --local-agent --input '{}'                  # observer link only
+flows run --cloud-mirror review.flow.ts --local-agent --input '{}'   # ...and the dashboard
+```
+
+The run prints both, and the dashboard line names Cloud's run id as well as the page:
+
+```
+Observer:  https://agentrelay.com/observer?key=ot_live_...
+Dashboard: https://.../dashboard/workflow/<cloud-run-id>/runner  ·  flows status --cloud --watch <cloud-run-id>
+```
+
+**That second id matters and is easy to get wrong.** The report's own `runId` is the *journal's* ULID (`01M3B9...`), while the two hosted verbs that take an id — `flows status --cloud <run-id>` and `flows logs <run-id>` — want Cloud's UUID. Do not pass a journal id to either. Under `--json` both ride in the report as `cloudRunId` and `dashboardUrl`, beside `observerUrl`.
+
+`flows runs` is the odd one out and the way *out* of this problem: it takes no id at all (`flows runs [--limit <n>] [--json]`) and lists the runs the credential can see, newest first, with each one's Cloud UUID — so it is how you find the id the other two want when you no longer have the terminal that printed it.
+
+**Why it is opt-in, not on by default.** Because it is the richer view, it is also the one that *stores* all of that: source, step metadata, agent transcripts, and the CLI's own stderr. Transcripts are whatever the agent printed, including file contents and command output. Everything goes through the same redactor `flows status` uses — but redaction is pattern matching, and pattern matching has a false-negative rate. So the trigger is an explicit request and never the mere presence of a Cloud login. Only an affirmative counts for the env var (`1`/`true`/`on`/`yes`); `0`, empty, and anything nobody meant as a switch all leave the run local.
+
+**What it buys you, concretely:** the three read verbs start answering for *local* runs, which until `2.0.32` only worked for runs Cloud had launched.
+
+```
+$ flows status --cloud <cloud-run-id>
+RUN 27ab5702-...  local-mirror-agent-confirmation  completed  spend 13,088 in / 61 out / $0.01836
+  ✓ ask-claude  agent  1 attempt  3.3s  claude-haiku-4-5-20251001 · 1 turn · $0.01836
+  ✓ ask-codex   agent  1 attempt  7.9s
+$ flows logs <cloud-run-id> --step ask-claude    # that step's transcript, out of Cloud storage
+```
+
+Three behaviours worth knowing before you rely on it:
+
+- **It cannot fail a run.** Every push collapses to a boolean; each poll and the whole finish are bounded. A Cloud outage costs the run its dashboard page and nothing else. If the mirror is refused you get one line naming which switch asked for it, and the run's exit code is untouched.
+- **The dashboard says the run was local.** The row is `dispatchType: "local"`, and the run page shows **Ran on: Your machine** instead of a sandbox tile. Cancel is refused for it — Cloud mirrors a local run, it does not control it, so stop it where it is running.
+- **A `--cloud-mirror` resume is a second dashboard row, linked to the first.** Cloud refuses to move a terminal run back to `running` (its own hosted resume mints a fresh id too), so the resumed attempt carries `resumedFromRunId` and the run page links the two — the parked "Needs review" row shows what continued it. The mapping lives in `<data-dir>/cloud-runs/`: the Cloud run id and the deployment, no credential, mode 0600, ageing out at 30 days.
+
+**Requires a Cloud login** (`agent-relay cloud login`, or `FLOWS_CLOUD_TOKEN`) — the same credential every other hosted verb uses. Without one, `--cloud-mirror` prints one line saying the run stays local and the run proceeds normally. A local run that joins no workspace is not a defect (RFC-0001 settled decision 7: the journal is the record, the workspace is one view onto it).
+
+### Exit codes and refusal shapes
+
+Every refusal before a journal write is exit **2**, printed as `REFUSED [<kind>] <message>`. The `<kind>` differs by *how* the flow was checked, not just *what* was wrong:
+
+- `flows check` on a YAML/JSON spec, or the declarative-compiler path in general → the preflight's own kind directly: `cli_unresolved`, `model_unknown`, `cli_missing`, `cli_unauthenticated`, `no_executor`, `config_invalid`, etc.
+- `flows run` on a **TypeScript** `.flow.ts` whose authored `f.agent`/`f.llm` call can't resolve a CLI or model at runtime → wrapped and printed as `REFUSED [invalid_spec] <message>` with the specific reason (`llm_cli_unresolved`, etc.) inside the message text, not as the printed `[kind]` itself.
+
+Both are real, both are exit 2 — the same underlying problem can print a different `[kind]` depending on whether you hit it via `flows check` on YAML or `flows run` on TypeScript.
+
+## Common mistakes
+
+- **Forgetting `version` in a YAML/JSON `FlowSpec`.** Required, not optional.
+- **Attaching two `.gate()` calls to one step.** `unsupported_gate`: a step takes one. Also note a predicate gate is invisible to `flows check` — prefer a config object when preflight should be able to prove it.
+- **Putting `tools`, `budget`, or any other `FlowHeader` field into `flows.json`.** `flows.json` only accepts `cli`, `executors`, `models`, `mcp`, `deploy` — anything else is `config_invalid`.
+- **Assuming `flows.json`'s `models` sets a default model.** It only validates models already declared elsewhere; it never selects one.
+- **Declaring `.on(...)` trigger handlers without registering the provider in `flows.json`'s `executors`.** Even a flow you only ever run directly (never via a real webhook) needs this, or it's refused `no_executor` before your input is even read.
+- **Calling `f.done('canceled')` for a human's "no."** That's `f.done('declined')` — `canceled` is the kernel's verdict, not an authored body's.
+- **Running an agent/llm-bearing flow without `--local-agent`.** The run parks with nothing attached to do the work.
+- **Letting a git-hygiene flow's cleanup step delete your daemon's own data dir.** Pass `--data-dir` outside the checkout for any flow that runs `git clean`/`git checkout --force` on its own working tree.
+- **Not awaiting a step, or manually `.then()`-chaining one.** Refused (`unawaited_step`) rather than silently ignored.
+- **Running a `.flow.ts` without `--input`.** Required even for flows that don't use their input argument.
+- **Assuming `flows run --cloud` for a one-shot TypeScript flow run is still broken.** It was through `2.0.16` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), now closed) — fixed in `2.0.17`. If you're on an older CLI, update rather than reach for a workaround; `flows deploy` remains the right choice for a persistent listener regardless.
+
+## What this skill does NOT cover
+
+- **Triggers/webhooks** (`.on(github.pull_request(...), ...)`), **memory retrieval**, and the full **helper** catalog's per-provider quirks (`f.mcp`, provider-specific settings) — each is its own surface; see the [Relayflows product docs](https://agentrelay.com/docs/relayflows) and the [flows-cookbook](https://github.com/AgentWorkforce/flows-cookbook) for real, run-verified examples of each.
+- **Named-agent map equivalent in TypeScript beyond `use:`** — `use` composes complete child flows, not named agent configurations.
+- **YAML-only agent step fields with no TypeScript equivalent**: `recoveryMode`, `surfaces`, `output`, the `agent:` named-agent selector, and enforced `workspace` (TypeScript's `workspace` string is accepted by the type but rejected by the local-agent worker — see **Human approval and direct child flows**). `permissions` is **not** on this list — it is a TypeScript option too (see **The real `Ctx` contract**).
+- **Hosted multi-file child-flow execution** — `flows run --cloud` refuses `use` dependencies even with `--sync-code`; `--cloud-mirror` is the supported route for a local child-flow tree on the Cloud dashboard.
+- The **older `@relayflows/core` `WorkflowBuilder`** engine — see `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` in this repo.
+
+## Quick reference
+
+| Verb / field | Language | Notes |
+|---|---|---|
+| `f.run(command, {timeout?})` / `type: deterministic` | both | shell command, implicit `exit_code` gate |
+| `f.llm(...)` / `type: llm` | both | bare model call, no workspace |
+| `f.agent(name, opts)` / `type: agent` | both | harnessed coding agent, returns `{summary, artifacts}` |
+| `f.human(question, {to})` | TS only | parks the run on a durable `wait.human`; `flows answer <run> human-<n> yes\|no` then `flows resume` |
+| `use: ['./child.flow.ts']` / `f.dispatch(name, input)` | TS only | `2.0.35`+ direct child in one durable tree; dispatch by declared name |
+| `f.done(reason)` | TS / kernel | one of `success \| step_failed \| needs_human \| declined` from an authored body; `canceled \| budget_exceeded` are kernel-only |
+| `.gate(config)` / `.gate(predicate, because)` | TS | one per step; both run since flows#449, but only a config object is provable by `flows check` |
+| `options.transport: 'relay'` | TS/YAML `agent` step | dispatch to Agent Relay's task infra; request+receipt, not live chat |
+| `Promise.all([...steps])` | TS | first-class supported concurrent fan-out |
+| `flows.json`: `cli, executors, models, mcp, deploy` | project config | exact accepted key set — nothing else |
+| `flows check <file>` | CLI | pure validate + preflight, no daemon |
+| `flows run <file> --local-agent [--input ...]` | CLI | actually executes; `.flow.ts` needs `--input`, agent/llm steps need `--local-agent` |
+| `flows deploy <flow.ts> --repo ... --on ...` | CLI | persistent trigger-based listener; needs `agent-relay cloud login` plus a connected GitHub App + `--on` provider first, or `flow_repository_not_connected` |
+| `flows run --cloud <flow.ts> --input ...` | CLI | fixed in `2.0.17` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461)); update if you still see `http_error`/`invalid_input` |
+| `flows run --cloud-mirror <file> --local-agent` | CLI | `2.0.32`+; local run also on the Cloud dashboard, transcripts included. Opt-in; `FLOWS_CLOUD_MIRROR=1` for a shell. `--json` gains `cloudRunId`/`dashboardUrl` |
+| `flows run --cloud` with `use` | CLI | unsupported: one self-contained `.flow.ts` source only, even with `--sync-code` |
+| `flows status --cloud <run-id>` / `flows logs <run-id>` | CLI | take Cloud's **UUID**, not the journal ULID. Answer for mirrored local runs since `2.0.32` |
+| `flows runs [--limit <n>]` | CLI | takes **no id** — lists runs newest-first, which is how you find the UUID the two above want |
+| `flows schedule <flow.ts> --cron ...` | CLI | cron-based cloud run |
+
+## Verified against
+
+**The `Ctx` and child-flow contracts were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations.** Earlier gate, helper, and agent-option findings below were established on `2.0.22`; the original `--cloud-mirror` verification was on `2.0.32`.
+
+A three-level root → child → grandchild fixture was run locally from published `2.0.35` packages, then mirrored to the production Cloud dashboard. The [mirrored run](https://agentrelay.com/cloud/dashboard/workflow/0d502725-e4c2-4cfd-aed2-ed0dd49bd6ac/runner) completed with `completionReason: success`; its Cloud graph contained seven succeeded work/dispatch nodes, seven runtime dependency edges, both child labels, and no warnings. A separate `flows run --cloud --sync-code` attempt refused the same tree before admission with `unsupported_source`, which is why this skill does not promise hosted child-flow execution. This checks the graph API used by the dashboard, not an authenticated browser screenshot.
+
+**The `--cloud-mirror` section was verified on `2.0.32`, against production, with the published artifact.** `relayflows@2.0.32` was installed from npm into a scratch project — not run from a source tree — and two real local runs were mirrored to `agentrelay.com`:
+
+- a two-step deterministic flow, read back with `flows status --cloud`, `flows logs` (the `runner.log` round-trip) and `flows runs` (the run appearing in history beside hosted ones);
+- a two-agent flow, one `cli: claude` step and one `cli: codex` step, spending a real `$0.01836` — whose **per-step transcripts were fetched back out of Cloud storage** and rendered in each provider's own frame vocabulary. That is the claim worth having evidence for: an echo-only flow exercises none of the transcript path.
+
+Two things that verification established and that are easy to assume otherwise. **Flows drives exactly two agent CLIs**: `adapters/index.ts` registers `claude` and `codex`, and anything else resolves to `relayflows-wrapper-v1`, which requires the executable to answer `--relayflows-adapter-v1` with a flows-specific token. A real `devin` CLI on `PATH` rejects that flag outright (`error: unexpected argument`), so it cannot be used as a `cli:` for an agent step no matter what is installed — adding one is a new `adapters/<name>.ts` plus a registry entry. And the **observer projection has no retry**: `run-projection.ts` sets `failed = true` on the first error and every later publish is a no-op, so a transient `429 workspace_busy` — observed for real during this verification, while another run was launching in the same workspace — permanently loses the observer view for that run. The dashboard mirror survived the same window because it classifies `429` as transient and retries on its next poll. If an observer link opens an empty channel, that asymmetry is the first thing to check.
+
+The earlier `2.0.22` refresh settled several contradictions against the published package: `AgentOptions.permissions` exists on the TypeScript call site (added in `2.0.17`, validated and journaled, not enforced — preflight warns `permissions_unenforced`); `run(command, options?)` takes a second `{timeout}` argument; `f.done` takes six `FLOW_COMPLETION_REASONS`; there is no `budget.maxWallclockMs`; predicate `.gate()` and `artifact_exists` ship; and `f.human` executes. Its then-true finding that `f.dispatch` was unsupported was superseded by `2.0.35`. Older real-run recipes are in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook); check their dates when comparing behavior.
+
+The `flows.json` schema refusal, the `--data-dir` git-hygiene interaction, and the `flows run --cloud` bug were reproduced while building that cookbook past `v2.0.16` (2026-09-17). The `2.0.22` refresh also checked the `workspace: readonly` annotation and the `subprocess_gate` env var name against the real CLI. Child-flow claims above instead rest on the published `2.0.35` run and its production Cloud graph.
diff --git a/web/lib/agent-signup-progress.ts b/web/lib/agent-signup-progress.ts
index 1ac6e08c..c01d9f9a 100644
--- a/web/lib/agent-signup-progress.ts
+++ b/web/lib/agent-signup-progress.ts
@@ -42,10 +42,10 @@ export function trackedSignupPrompt(product: AgentSignupProduct, origin: string,
 export const signupSteps = {
   teams: [
     { title: 'Sign in', detail: 'Your agent opens Google. You approve access.' },
-    { title: 'Install the app', detail: 'Download, verify, and install Agent Relay on your Mac.' },
+    { title: 'Install the app', detail: 'Download, verify, and install the Agent Relay desktop app.' },
     { title: 'Connect your workspace', detail: 'Link the app to your account and workspace.' },
-    { title: 'Choose what to share', detail: 'Your agent asks which sessions you want to share.' },
-    { title: 'Check everything works', detail: 'Verify the connection and open your workspace.' },
+    { title: 'Choose what to share', detail: 'New sessions are shared; your agent asks before changing an existing choice.' },
+    { title: 'Check everything works', detail: 'Verify the app, then one live session handoff with a teammate.' },
   ],
   flows: [
     { title: 'Sign in', detail: 'Your agent opens Google. You approve access.' },
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index f1c4202c..585c6801 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -1,3 +1,5 @@
+import { SETUP_SKILLS, SETUP_SKILLS_SOURCE } from './generated/setup-skills';
+
 export type AgentSignupProduct = 'teams' | 'flows';
 
 export function isAgentSignupProduct(value: string): value is AgentSignupProduct {
@@ -10,10 +12,11 @@ export function agentSignupPrompt(product: AgentSignupProduct, origin: string):
   return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch and follow ${origin}/signup/agent/${product} over HTTP for the exact APIs and setup steps. Do NOT use computer use, browser automation, or screen control. Use the documented APIs and CLI commands; leave sign-in and approval pages to me. For desktop installation, download the prebuilt binary from the guide—never clone, build, or compile the app.`;
 }
 
-/** Bundled strings: these instructions must also work on Workers without a filesystem. */
+/** Bundled strings: the skills are vendored into a generated module, so this also works on Workers without a filesystem. */
 export function agentSignupInstructions(product: AgentSignupProduct, site: string, cloud: string): string {
   const title = product === 'teams' ? 'Teams' : 'Flows';
-  const shared = `# Agent Relay ${title}: agent-driven signup
+  const parts = signupParts[product];
+  const header = `# Agent Relay ${title}: agent-driven signup
 
 You are setting up Agent Relay on behalf of the user who gave you this URL.
 ${agentSignupInteractionPolicy}
@@ -28,7 +31,7 @@ code). If no opener is available, give the link to the user. Do not launch a
 browser-control tool. Verify approval by polling the API, never by inspecting
 the browser. If an operation has no documented API or CLI, report the blocker
 and ask the user for that specific action; never fall back to computer use.
-For desktop installation, download the prebuilt binary from this guide. Never
+For desktop installation, download the prebuilt binary the skill names. Never
 clone the desktop repository, install build dependencies, run a build, compile
 from source, or generate a DMG. A missing binary is a blocker, not a build task.
 The user handles Google sign-in, device approval, and any provider or operating
@@ -36,33 +39,34 @@ system consent. Never approve access on their behalf or ask for their password.
 
 Site: ${site}
 Cloud API base: ${cloud}
-All API paths below are relative to that Cloud base, including its /cloud prefix.
 Use this exact environment throughout; never fall back from local development
-to production. The Teams desktop app currently requires macOS 13 or later.
-Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
-
-## API map — use these interfaces, not the UI
-
-Use an HTTP client such as fetch or curl. Send JSON request bodies with
-Content-Type: application/json. The sections below specify exact bodies,
-response fields, authentication, polling and error handling.
-
-- Sign-in: POST ${cloud}/api/v1/auth/device/start, then poll POST
-  ${cloud}/api/v1/auth/device/token. Only the user approves the returned URL.
-- Identity/workspace: GET ${cloud}/api/v1/auth/whoami with the access token.
-- Refresh: POST ${cloud}/api/v1/auth/token/refresh before token expiry.
-- Progress: GET/PATCH the exact Progress API URL in the user's prompt;
-  PATCH uses the separate Progress token, not the account access token.
-${product === 'flows' ? '- Web input: POST the Progress API URL to request a choice, then GET it with the Progress token to read the answer. The original browser tab submits the choice with PUT.' : ''}
-${product === 'teams' ? `- Desktop install/connect/share/status: the bundled agent-relay-probe CLI
-  in sections 2–4. These are local machine operations, not dashboard clicks;
-  there is no public HTTP endpoint that installs an app on the user's Mac.` : `- Flow catalog: GET ${site}/api/v1/flows/catalog and /<id>.
-- Tool consent links: POST ${cloud}/api/v1/integrations/connect-link;
-  poll GET ${cloud}/api/v1/workspaces/<workspaceId>/integrations/<provider>/status.
-- Coding-agent credentials: the official cloud connect CLI in section 3;
-  GET ${cloud}/api/v1/cloud-agents inspects existing connections.
-- Activation: POST ${cloud}/api/v1/flows/deploy with the body in section 4.
-- Verification: GET ${cloud}/api/v1/flows/listeners/<agentId>.`}
+to production.
+
+## How this guide is built
+
+This header holds only what is specific to signup. The setup steps are the
+canonical Agent Relay skills from https://github.com/AgentWorkforce/skills,
+included below verbatim at commit ${SETUP_SKILLS_SOURCE.commit}:
+
+${parts.map((part, index) => `- Part ${index + 1}: ${part.label} (${part.skill})`).join('\n')}
+
+Follow the parts in order${product === 'flows' ? ' (Part 3 is a reference, read only for a custom flow)' : ''}. Where a part says to ask the human, ask the user
+${product === 'flows' ? 'through the web-input protocol below, not in chat' : 'in your conversation with them'}.
+Where a part offers to install itself as a skill or to use another agent,
+continue with the text here instead. A part that requires another skill finds
+it as another part of this guide; do not stop to install skills.
+${product === 'teams' ? `
+Part 1 creates the account with signup_source "teams"; this marker admits a new
+Teams signup, so do it before Part 2. Pass Part 1's currentWorkspace.id as the
+workspace in Part 2's /setup/sign-in payload. The app signs in on its own, so
+the user may approve one more device link there unless it reuses a login.
+Before Part 2, read Part 3's "The only human steps" and ask the user for those
+inputs up front, so they can mint the token while the desktop installs.
+Setup is complete only in Part 3's finished state: a proven live round trip.` : `
+Part 1 creates the account with signup_source "flows". Part 2 uses its access
+token and its user.id and currentWorkspace.id. Part 3 is writing-relayflows,
+the authoring guide Part 2's custom-flow path defers to; skip it for a
+prebuilt flow.`}${site.startsWith('http:') ? localDevelopmentNote(product, site) : ''}
 
 ## Live progress (when the user's prompt includes a progress session)
 
@@ -95,18 +99,24 @@ PATCH before each numbered progress step below. A move to the next step marks
 the previous step done; do not skip steps or report success before checking it.
 Set state: waiting when you need the user to approve access or choose an option.
 Set state: working at the same step when you resume, and state: failed if work
-cannot continue. After completing step 5's verification, PATCH step: 5,
-state: complete. Only report complete after the actual checks succeed.
+cannot continue. Only report complete after the actual checks succeed.
 
 ${product === 'teams' ? `Progress steps for Teams:
-1. Sign in: before device authorization (section 1).
-2. Install the app: before download and installation (section 2).
-3. Connect the workspace: before cloud install (section 3).
-4. Choose what to share: before asking for/selecting sessions in section 3.
-   Report waiting while the user chooses. Respect an explicit choice to share none.
-5. Check everything works: before status, upload, and app verification (section 4).` : `Progress steps for Flows correspond to sections 1 through 5 below:
-1. Sign in. 2. Choose the flow/repository. 3. Connect tools.
-4. Activate the flow. 5. Verify the listening state.`}
+1. Sign in: before Part 1.
+2. Install the app: before Part 2's install (its sections 1 and 2).
+3. Connect the workspace: before Part 2's sign-in (its section 3).
+4. Choose what to share: before Part 2's defaults (its section 4). Report
+   waiting while the user decides about an existing sharing mode.
+5. Check everything works: before Part 2's final verification, continuing
+   through all of Part 3. Keep step 5 working or waiting until Part 3 proves a
+   live round trip; only then PATCH step: 5, state: complete. A self-verified
+   read path without a teammate is not completion.` : `Progress steps for Flows:
+1. Sign in: before Part 1.
+2. Choose the flow/repository: before Part 2's section 1.
+3. Connect tools: before Part 2's section 2.
+4. Activate the flow: before Part 2's section 3.
+5. Verify the listening state: before Part 2's section 4. After its checks
+   succeed, PATCH step: 5, state: complete.`}
 
 On HTTP 409, GET current progress and reconcile; never overwrite newer progress
 or regress a step. If a PATCH response is lost, GET before retrying. If a step is
@@ -116,15 +126,57 @@ Retry-After. Retry transient network/5xx failures with bounded backoff. On 404,
 stop reporting (the session expired or the token is invalid) and tell the user;
 do not recreate or switch their session silently. A progress service outage
 must not roll back working setup or cause duplicate installation/activation.
+${product === 'flows' ? flowsWebInput : ''}`;
+  return header + parts
+    .map((part, index) => `\n---\n\n# Part ${index + 1}: ${part.label}\n\n${forEnvironment(SETUP_SKILLS[part.skill], site, cloud).trim()}\n`)
+    .join('');
+}
+
+const signupParts: Record<AgentSignupProduct, readonly { label: string; skill: string }[]> = {
+  teams: [
+    { label: 'Cloud account', skill: 'signing-in-to-agent-relay-cloud' },
+    { label: 'Desktop', skill: 'setting-up-agent-relay-desktop' },
+    { label: 'Sessions', skill: 'setting-up-agent-relay-sessions' },
+  ],
+  flows: [
+    { label: 'Cloud account', skill: 'signing-in-to-agent-relay-cloud' },
+    { label: 'Flows', skill: 'setting-up-agent-relay-flows' },
+    { label: 'Custom flow authoring', skill: 'writing-relayflows' },
+  ],
+};
+
+const PRODUCTION_SITE = 'https://agentrelay.com';
+
+/** The skills name production; a local stack substitutes its own exact origins. */
+function forEnvironment(skill: string | undefined, site: string, cloud: string): string {
+  if (skill === undefined) throw new Error('A signup part names a skill that is not vendored');
+  if (site === PRODUCTION_SITE && cloud === `${PRODUCTION_SITE}/cloud`) return skill;
+  return skill.replaceAll(`${PRODUCTION_SITE}/cloud`, cloud).replaceAll(PRODUCTION_SITE, site);
+}
+
+function localDevelopmentNote(product: AgentSignupProduct, site: string): string {
+  return `
+
+This is a local development stack. The skills' production URLs have been
+replaced with the origins above.${product === 'teams' ? ` For the desktop, use only the prebuilt
+Agent Relay Dev app served by the local stack, in place of the release download:
+${site}/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg and the same URL
+plus .sha256 (arm64 or x64). Its bundle id is com.agentrelay.desktop.dev and its
+socket pointer is ~/.agentworkforce/desktop/relay-socket.dev. If the DMG or its
+checksum is unavailable, stop and report the missing prebuilt artifact.
+Do not build it, run the development launcher to produce it, or switch to a
+production download.` : ''}`;
+}
 
-${product === 'flows' ? `## Web input — ask on the signup page, never in chat
+const flowsWebInput = `
+## Web input — ask on the signup page, never in chat
 
 When a repository, workflow, trigger, approver, or confirmation is missing,
 use the Progress API to show the question in the user's original signup tab.
 Do not ask the user to answer in your chat. Do not operate the page yourself.
 Only request non-secret choices; never ask for passwords, OAuth codes, API keys,
 or sensitive personal data through this endpoint. Sign-in and provider consent stay on
-their own approval pages, opened for the user as described below.
+their own approval pages, opened for the user as described above.
 
 First PATCH the current progress step to state: waiting using its latest
 revision. Then POST the exact Progress API URL with Authorization: Bearer
@@ -137,7 +189,7 @@ revision. Then POST the exact Progress API URL with Authorization: Bearer
 For a choice list use type: select and options, for example:
 
 ~~~json
-{"key":"workflow","label":"Which workflow should we activate?","type":"select","options":["software-factory","code-review"]}
+{"key":"flow_kind","label":"A prebuilt flow from the catalog, or a custom flow?","type":"select","options":["prebuilt","custom"]}
 ~~~
 
 Keys are stable lowercase identifiers (up to 40 characters); labels are at
@@ -170,338 +222,4 @@ silently switch to chat questions or fabricate a choice.
 The bearer token is shared only with the agent and the original browser tab;
 keep it out of URLs and logs. Its authorization does not grant Cloud account
 access. PUT is for the browser to submit a choice, not an agent shortcut.
-` : ''}
-
-## 1. Sign up and obtain an API session
-
-Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
-or pre-existing Agent Relay account is required.
-
-POST /api/v1/auth/device/start with Content-Type: application/json:
-
-~~~json
-{"client_name":"My agent — ${title} setup","signup_source":"${product}"}
-~~~
-
-Expect HTTP 201 with device_code, user_code, verification_uri_complete,
-verification_uri, interval (seconds), and expires_in (seconds). Keep device_code
-private. Open verification_uri_complete in the user's browser and show the
-user_code so they can compare it. The page lets them sign in with Google,
-review the requesting device, and Approve or Deny. The signup marker in the
-returned URL creates the right account type; preserve it through sign-in.
-Do not call /auth/device/approve yourself.
-
-For a fresh signup, you can open ${cloud}/api/auth/google/start?next=<encoded-return-path>
-first, where encoded-return-path is the URL-encoded pathname plus query of
-verification_uri_complete. This opens Google immediately and returns to the
-same device approval with its code and signup marker intact.
-
-While the browser is open, wait interval seconds between POSTs to
-/api/v1/auth/device/token with this JSON (substitute the private device_code):
-
-~~~json
-{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}
-~~~
-
-- authorization_pending: keep waiting; respect a returned interval.
-- slow_down: increase the interval by at least 5 seconds.
-- HTTP 429: respect Retry-After and increase the interval.
-- HTTP 5xx or request timeout: retry with backoff, bounded by expires_in.
-- access_denied: stop. expired_token or invalid_grant: explain and start a new
-  grant only if the user still wants to continue. Never poll past expiry.
-
-HTTP 200 returns access_token, refresh_token, access_token_expires_at,
-refresh_token_expires_at, api_url and token_type. Keep credentials in memory
-or a private file (directory 0700, file 0600) outside repositories. Never echo
-tokens, put them in chat or URLs, or dump full authentication responses.
-Use Authorization: Bearer <access_token> for subsequent Cloud requests.
-Reject an api_url pointing at another origin; keep using the Cloud base above.
-Set a 30-second request timeout and check every response status before proceeding.
-
-Before expiry, POST /api/v1/auth/token/refresh with {"refreshToken":"<refresh_token>"}.
-The response uses camelCase: accessToken, refreshToken, accessTokenExpiresAt,
-refreshTokenExpiresAt, apiUrl. Replace both stored tokens atomically. Serialize
-refreshes: the refresh token rotates and must not be shared between machines.
-An invalid/expired refresh requires a new device login, not an endless retry.
-
-GET /api/v1/auth/whoami. Require authenticated: true and read user.id,
-user.email, currentWorkspace.id, and currentOrganization.id. New signups create
-a workspace automatically. Reuse it; do not create duplicate accounts/workspaces.
-If currentWorkspace is missing, or an existing account is in the wrong workspace,
-resolve that with the user before connecting or activating anything. Never
-silently replace an existing connection to another account.
-
-## Credential handoff to the supported CLI
-
-When running a child process, pass these through its environment from your
-private session object (never interpolate their values into logged commands):
-
-~~~text
-CLOUD_API_URL=${cloud}
-CLOUD_API_ACCESS_TOKEN=<access_token>
-CLOUD_API_REFRESH_TOKEN=<refresh_token>
-CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
-CLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>
-~~~
-
-The official CLI consumes this session. The bundled desktop probe uses
-CLOUD_API_ACCESS_TOKEN to exchange for its own scoped History session, so it
-does not need a second Google login. Refresh the parent session before starting
-a long command; do not concurrently refresh it from parent and child processes.
-Do not overwrite an existing CLI auth file or copy a session to another machine.
-`;
-  return shared + (product === 'teams' ? teamsInstructions(site) : flowsInstructions(site, cloud));
-}
-
-function teamsInstructions(site: string): string {
-  const local = new URL(site).protocol === 'http:';
-  const name = local ? 'Agent Relay Dev' : 'Agent Relay';
-  const download = local
-    ? `${site}/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg`
-    : 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/AgentRelay-macOS-<arch>.dmg';
-  return `
-## 2. Download and install the prebuilt desktop binary
-
-Run sw_vers -productVersion and uname -m on the user's Mac. arm64 means Apple
-silicon; x86_64 means the x64 download. If this agent runs in a remote sandbox,
-it needs authorized terminal access to the user's Mac before installation; installing into
-the sandbox does not connect their computer. Report an unsupported OS honestly.
-
-Download ${download} and the same URL plus .sha256. Replace <arch> with arm64
-or x64. Use a private temporary directory, follow HTTPS release redirects, and
-fail on HTTP errors. Verify SHA-256 before mounting. For local development,
-use only the prebuilt DMG already served by the local stack. If the DMG or its
-checksum is unavailable for this architecture, stop and report the missing
-prebuilt artifact. Do not build it, run the development launcher to produce it,
-or switch to a production download.
-
-Use hdiutil attach -nobrowse with a private mount point, then ditto the mounted
-${name}.app into ~/Applications/${name}.app (create ~/Applications if needed).
-Detach the image and clean up the temporary download after copying. Check for
-an already installed app in /Applications and ~/Applications first: reuse the
-correct app instead of overwriting a running or newer installation. Preserve
-macOS signing/quarantine checks. If macOS requires consent, let the user approve
-the normal Open / Privacy & Security prompt; do not strip quarantine or disable
-Gatekeeper. A checksum mismatch is a hard stop.
-The desktop app supports https://agentrelay.com and the local development stack;
-other preview hosts require a separately configured app. Do not connect a
-production app to a preview URL.
-
-## 3. Connect the app using its bundled CLI
-
-Set PROBE to the absolute path of the installed app's
-Contents/Helpers/agent-relay-probe. Use the bundled executable, not an unrelated
-binary on PATH. Run it with --help and verify support for cloud install --json
-and --selected-sessions-only. Read installs --json first, keeping local paths
-and account details private. Reuse a matching account/workspace install.
-
-Run this with the private credential environment from step 1. Substitute the
-actual user.id and currentWorkspace.id returned by whoami:
-
-~~~sh
-"$PROBE" cloud install --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --selected-sessions-only --json
-~~~
-
-This exchanges credentials, catalogs local sessions, and starts the background
-collector. Consume the NDJSON events until the process exits successfully;
-do not declare success when the process merely starts. If it requests another
-approval, verify the environment and credential expiry before retrying.
-
-Selected sessions is the default: signing up is not consent to upload all past
-conversations. When the user has selected sessions to share, list the catalog
-and pass their exact session keys to sessions include. Each JSON row has source
-and session_id; construct the key as SOURCE:SESSION_ID (for example codex:abc123).
-The list response does not contain a precomputed key. Never pass a bare session_id:
-
-~~~sh
-"$PROBE" sessions list --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --limit 500 --json
-"$PROBE" sessions include --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --session '<selected-key>' --json
-~~~
-
-Repeat --session for multiple keys. Do not choose sessions for the user.
-Only when explicitly requested, use --new-sessions-only or --include-existing
-instead of --selected-sessions-only during installation. Do not start duplicate
-collectors or silently stop an existing uploader for another environment.
-
-## 4. Verify and open the app
-
-~~~sh
-"$PROBE" status --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --json
-~~~
-
-Require running: true, paused: false, and the expected site_url, account_id, and
-workspace_id. These are the CLI's JSON field names. Check delivery and last_cycle
-for failures. If sessions were selected,
-poll sessions list with a bounded wait until those sessions report uploaded;
-do not equate a running collector with uploaded content. If none were selected,
-report that the app is connected and no sessions have been shared yet.
-
-Use this as the initial handoff to the installed ${name}.app:
-${local ? 'agentrelay-dev' : 'agentrelay'}://connect?site=<encoded-site>&account=<encoded-user.id>&workspace=<encoded-currentWorkspace.id>
-URL-encode the three values; the link contains identifiers only, never tokens.
-The app discovers the probe's saved connection. If it is already attached to a
-different account/workspace, the link will report a conflict, not switch accounts.
-Ask the user to explicitly log out/switch in Account before retrying; do not
-disconnect an existing workspace automatically. The probe's JSON status verifies
-the collector, not whether the app accepted the handoff. Do not inspect the app's
-Account view yourself. Ask the user to confirm that the visible app account and
-workspace match the target after handoff. Until confirmed, report the app
-attachment as unverified and keep progress waiting at step 5; do not mark setup
-complete. Open ${site}/cloud/dashboard/sessions for the team history. Report
-the installed app, account/workspace, sharing choice, and verification outcome.
-Delete temporary authentication files after use; retain the app-managed scoped
-credentials so background collection continues. The user can pause, select
-sessions, or disconnect in the app.
-`;
-}
-
-function flowsInstructions(site: string, cloud: string): string {
-  return `
-## 2. Choose the flow and repository
-
-Request missing product choices through the web-input protocol above:
-repository, desired workflow/trigger, and approver. Ask for the approver's
-GitHub username in plain language (for example, "octocat" or "@octocat"),
-not an internal provider-address format or their Google email. Normalize the
-answer to github:@handle when constructing the deploy API request. Human-gate
-replies are matched to that provider identity. Infer choices from the user's request and current
-repository where clear.
-Do not invent a repository or enable automation on an unrelated project.
-
-GET ${site}/api/v1/flows/catalog and select a matching entry from flows.
-GET ${site}/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
-kind before doing anything executable: only an entry with kind: flow (or a
-legacy entry with kind omitted) is deployable through the direct-source API
-below. An entry with kind: extension is discoverable metadata, not a standalone
-listener. Do not download or deploy its source, even when it declares trigger
-and input fields. Inspect baseFlowId and extension.activation instead. If the
-extension is blocked, report the unmet dependencies and that it can only be
-added to its base flow after a supported extension activation path is available;
-never substitute a standalone flow deployment.
-
-For a deployable flow, use the catalog's
-supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
-inputs.allowedAgents. Name a model per harness in inputs.models when the house
-default is wrong (for example {"claude": "claude-sonnet-4"}); omit it to fund
-the house default for each declared agent. Download source.rawUrl, verify its bytes against
-source.sha256, and use that source text unchanged for a recommended flow.
-The source is TypeScript, not the source URL. Do not guess a template or hash.
-For custom flows use ${site}/docs/relayflows/markdown/build.md and
-${site}/docs/relayflows/markdown/cloud.md for the authoring contract.
-
-## 3. Connect the required tools and coding agents
-
-Use bearer-authenticated POST /api/v1/integrations/connect-link:
-
-~~~json
-{"provider":"github","workspaceId":"<currentWorkspace.id>"}
-~~~
-
-Open the returned connectUrl for the user to approve. Keep token/sessionToken
-private. Connect only the repository and tools the chosen flow requires.
-For GitHub the user must grant repository access. Repeat with the chosen trigger
-provider if different. Reuse existing ready connections rather than relinking.
-Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
-until oauth.connected is true (poll with backoff and a bounded timeout); a
-returned connect link or a closed popup alone does not prove the connection.
-For the GitHub-triggered Software Garden flow, activation separately checks
-that the connected GitHub App covers the selected repository. Its trigger
-does not require background data indexing, so do not block solely because
-the broader status.ready is false from queued syncs.
-If a different flow declares Relayfile data that requires synced records,
-verify that readiness separately before activating it.
-
-Do not connect a Claude or Codex subscription yet. The first three runs use
-Cloud's own model key, so no provider login is needed to activate. If the chosen
-flow declares more than one coding agent in inputs.agents, included Cloud runs
-can fund only one of them per run — connect your own subscription for at least
-one declared agent before activating a multi-agent flow. After the included
-runs, activation and launches will ask for your own subscription; only then use
-the official Relay CLI with the private credential environment from step 1 and
-a PTY:
-
-This promotion depends on Cloud's internal house-key proxy and account
-enrollment. If local activation returns flow_credentials_unavailable or
-flow_model_not_connected before the three promotional runs, treat it as an
-internal configuration or eligibility issue. Do not ask the user to connect
-Claude/Codex, provide an API key, or choose an inactive draft as a workaround.
-Report the blocker through the Progress API and have an internal developer
-verify the proxy, promotion flag, provider readiness, and enrollment. Never
-copy a house key into the agent environment or expose it in this guide.
-
-~~~sh
-npx --yes agent-relay@latest cloud connect anthropic --api-url '${cloud}'
-~~~
-
-Use anthropic for Claude or openai for Codex, according to the selected flow.
-The command drives provider login; open its authorization URL for the user,
-and keep the process alive until it confirms the credential is connected.
-Google approval does not grant GitHub or model-provider access: those services
-may require their own consent. Never fabricate credentials or claim consent
-happened. GET /api/v1/cloud-agents lets you inspect the account's credential
-state without reconnecting.
-
-## 4. Activate through the same API as web onboarding
-
-POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
-session. This is the direct-source listener API used by flows deploy, not the
-browser onboarding handoff: source is TypeScript text, repository is singular,
-and sources contains provider/settings objects. The catalog supplies the source
-reference and defaults; it is not itself a deploy request. The current endpoint
-does not accept a flowId/repositories-only catalog activation request or fetch
-the source for you. For multiple repositories, submit one deployment per
-repository with a distinct name and handoffId.
-
-For the catalog's Software Garden entry, construct this body, substituting the
-workspace, verified source, repository, GitHub approver and a new UUID:
-
-~~~json
-{
-  "workspaceId": "<currentWorkspace.id>",
-  "name": "Platform Garden",
-  "workflow": "software-factory",
-  "source": "<verified TypeScript source text>",
-  "handoffId": "<one UUID generated for this setup>",
-  "inputs": {"approver": "github:@octocat", "agents": ["claude"]},
-  "mode": "activate",
-  "repository": {"owner": "acme", "name": "api"},
-  "sources": [{"provider": "github", "settings": {"repository": "acme/api"}}]
-}
-~~~
-
-For another deployable kind: flow catalog entry use its id as workflow, allowed agents, and
-defaultTrigger for sources, then apply the user's trigger settings. Scope a
-GitHub issue trigger with settings.repository set to the chosen owner/name;
-for GitLab use settings.project. Cloud does not derive this filter from the
-deployment repository. An empty filter can trigger on other repositories in
-the workspace. Only use a different trigger scope when explicitly requested.
-Give each repository its own trigger filter for multi-repository setup. Do not send
-the example acme repository or octocat approver unchanged. The workflow field
-is a label, not a source lookup; keep the verified source in the request.
-For GitLab set repository.host to gitlab and use the namespace path
-as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
-failure, GET /api/v1/flows/listeners and check whether the flow already exists;
-do not create a new ID/name on every retry. Activation subscribes to matching
-future events and can run work; confirm the intended repository and trigger
-with the user if they have not specified them.
-
-HTTP 201 must contain agentId and status: listening. A draft is not completion.
-For a 409 workspace_mismatch, verify the active workspace; for connection
-preflight failures, fix the indicated connection before retrying. If the user
-wants to save incomplete work, use mode: draft explicitly and report that it
-is inactive. Never mask activation failures by silently falling back to draft.
-
-## 5. Verify
-
-GET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and
-verify its repository and sources match the request. Open
-${site}/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,
-workspace, repository, trigger, and verified listening state. This proves
-activation; only an actual completed run proves execution. Do not create a
-real issue or launch paid work merely to make the onboarding check turn green.
-Delete temporary authentication files after the work is complete.
-
-The desktop app is optional for Flows. If the user also wants local session
-sharing, follow ${site}/signup/agent/teams using the same signed-in account.
 `;
-}
diff --git a/web/lib/flow-local.ts b/web/lib/flow-local.ts
index 850f84e8..047f3a92 100644
--- a/web/lib/flow-local.ts
+++ b/web/lib/flow-local.ts
@@ -472,7 +472,7 @@ export function localKitFiles(draft: FactoryDraft): Record<string, string> {
     'software-factory.flow.mts': factorySource({ ...draft, step: 3 }, 'local'),
     'flow-input.json': JSON.stringify(localInput(draft), null, 2) + '\n',
     [LOCAL_PREFLIGHT]: LOCAL_PREFLIGHT_SCRIPT,
-    'START-HERE.txt': `RUN YOUR SOFTWARE FACTORY LOCALLY
+    'START-HERE.txt': `RUN YOUR SOFTWARE GARDEN LOCALLY
 
 Requirements
 - Node.js 22.18+ (for native TypeScript), npm, and Git.
diff --git a/web/lib/flow-onboarding.ts b/web/lib/flow-onboarding.ts
index 8d315221..781d6e40 100644
--- a/web/lib/flow-onboarding.ts
+++ b/web/lib/flow-onboarding.ts
@@ -95,7 +95,7 @@ export function cloudConnectionsHref(draft: FactoryDraft, handoffId: string, jou
   // id from shared browser storage. Carrying it here lets Cloud measure whether
   // that continuity actually held and merge the two people when it did not.
   const analytics = { ...(journeyId ? { journeyId } : {}), ...(distinctId ? { distinctId } : {}) };
-  const payload = { version: 1, handoffId, ...(Object.keys(analytics).length ? { analytics } : {}), name: 'Software factory', source: factorySource({ ...draft, step: 3 }),
+  const payload = { version: 1, handoffId, ...(Object.keys(analytics).length ? { analytics } : {}), name: 'Software Garden', source: factorySource({ ...draft, step: 3 }),
     workflow: draft.workflow, preview: flowPreview(draft), sources: draft.sources, sourceSettings: draft.sourceSettings,
     agents: draft.agents, otherAgent: draft.otherAgent, otherAgentSelected: otherAgentIsSelected(draft), task: draft.task };
   const base = process.env.NEXT_PUBLIC_CLOUD_URL || 'https://agentrelay.com/cloud';
diff --git a/web/lib/flow-workflows.ts b/web/lib/flow-workflows.ts
index f8c0ea55..e07feeaf 100644
--- a/web/lib/flow-workflows.ts
+++ b/web/lib/flow-workflows.ts
@@ -1,6 +1,8 @@
 import { resolveGeneratedAgentSettings, type AgentRole, type FlowAgentSettings } from './flow-agent-settings';
 import { isCodingAgent } from './flow-agents';
 
+// TODO: match these step lists to the step names the cloud /flows/deploy wizard
+// reports once it is aligned with the agent-led guide (same surfaces).
 export const WORKFLOWS = [
   { id: 'traditional', label: 'Traditional', description: 'Build and check the change, challenge it, and keep the final say.', steps: ['Implement', 'Run checks', 'Open PR', 'Adversarial review', 'Human gate'] },
   { id: 'prototype', label: 'Prototype and build', description: 'Explore three approaches, then build from the best of each.', steps: ['3 implementations', 'Compare', 'Build', 'Run checks', 'Open PR', 'Review', 'Human gate'] },
diff --git a/web/lib/generated/setup-skills.ts b/web/lib/generated/setup-skills.ts
new file mode 100644
index 00000000..9b84b94c
--- /dev/null
+++ b/web/lib/generated/setup-skills.ts
@@ -0,0 +1,11 @@
+// Generated by web/scripts/sync-setup-skills.mjs from the pinned
+// AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.
+export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"23a0754950654d765c417c188af52d130864b664"} as const;
+
+export const SETUP_SKILLS: Readonly<Record<string, string>> = {
+  "signing-in-to-agent-relay-cloud": "# Sign In to Agent Relay Cloud\n\nUse the existing OAuth device flow. No API key, invitation, dashboard wizard,\nor pre-existing Agent Relay account is required. Only the human approves the\nsign-in; never approve access on their behalf, ask for their password, or\noperate the approval page yourself.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix. When a guide names a different Cloud base (for\nexample a local development stack), use that exact base throughout and never\nfall back to production.\n\n## HTTP client\n\nUse `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their\ndefault User-Agent: the device-token endpoint answers them with HTTP 403 and no\nJSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth\nresponse while debugging; on success it contains tokens. Send JSON request\nbodies with `Content-Type: application/json`, set a 30-second request timeout,\nand check every response status before proceeding.\n\n## 1. Start the device grant\n\n`POST /api/v1/auth/device/start` with:\n\n```json\n{\"client_name\":\"My agent setup\"}\n```\n\nAn agent-driven signup guide also passes its product as `signup_source`\n(`\"teams\"` or `\"flows\"`); keep the value the guide names. Omit it otherwise.\n\nExpect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,\n`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep\n`device_code` private. Open `verification_uri_complete` in the person's\nbrowser with the OS URL opener (for example macOS `open`, with the URL passed as\na separate argument, never interpolated into shell code), or give them the link\nif no opener is available. Show the `user_code` so they can compare it. The page\nlets them sign in with Google, review the requesting device, and Approve or\nDeny. A signup marker in the returned URL creates the right account type;\npreserve it through sign-in. Do not call `/auth/device/approve` yourself.\n\nFor a fresh signup, you can open\n`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`\nfirst, where `encoded-return-path` is the URL-encoded pathname plus query of\n`verification_uri_complete`. This opens Google immediately and returns to the\nsame device approval with its code and signup marker intact.\n\n## 2. Poll for tokens\n\nWhile the browser is open, wait `interval` seconds between POSTs to\n`/api/v1/auth/device/token` with this JSON (substitute the private\n`device_code`):\n\n```json\n{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"<device_code>\"}\n```\n\n- `authorization_pending`: keep waiting; respect a returned interval.\n- `slow_down`: increase the interval by at least 5 seconds.\n- HTTP 429: respect `Retry-After` and increase the interval.\n- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.\n- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start\n  a new grant only if the person still wants to continue. Never poll past\n  expiry.\n\nHTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,\n`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in\nmemory or a private file (directory 0700, file 0600) outside repositories.\nNever echo tokens, put them in chat or URLs, or dump full authentication\nresponses. Use `Authorization: Bearer <access_token>` for subsequent Cloud\nrequests. Reject an `api_url` pointing at another origin; keep using the Cloud\nbase above.\n\n## 3. Refresh before expiry\n\nBefore expiry, `POST /api/v1/auth/token/refresh` with\n`{\"refreshToken\":\"<refresh_token>\"}`. The response uses camelCase:\n`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,\n`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the\nrefresh token rotates and must not be shared between machines. An\ninvalid/expired refresh requires a new device login, not an endless retry.\n\n## 4. Read the account and workspace\n\n`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,\n`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups\ncreate a workspace automatically. Reuse it; do not create duplicate\naccounts/workspaces. If `currentWorkspace` is missing, or an existing account\nis in the wrong workspace, resolve that with the person before connecting or\nactivating anything. Never silently replace an existing connection to another\naccount.\n\n## 5. Hand the session to the official CLI\n\nWhen running a child process, pass these through its environment from your\nprivate session object (never interpolate their values into logged commands):\n\n```text\nCLOUD_API_URL=https://agentrelay.com/cloud\nCLOUD_API_ACCESS_TOKEN=<access_token>\nCLOUD_API_REFRESH_TOKEN=<refresh_token>\nCLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>\nCLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>\n```\n\nThe official CLI consumes this session. Refresh the parent session before\nstarting a long command; do not concurrently refresh it from parent and child\nprocesses. Do not overwrite an existing CLI auth file or copy a session to\nanother machine. Delete temporary authentication files after the work is\ncomplete.\n",
+  "setting-up-agent-relay-desktop": "# Set Up Agent Relay Desktop\n\nComplete the setup through the private session socket. Do not ask the human to\nclick through the desktop app. The only normal human step is approving one\ndevice-login link when no reusable `agent-relay` CLI login exists.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the current release is installed and running;\n- sign-in is complete;\n- sharing mode is `new` (new sessions upload automatically), unless an existing\n  install already uses another mode and the human chose to keep it (section 4);\n- auto-activate is on, with every existing live session and every future session on the relay;\n- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);\n- this Codex or Claude session is registered and accepts direct delivery;\n- the requested webhook and integration subscriptions work;\n- the human receives the session's `agent@machine` address and verification evidence.\n\nNever put a Cloud token, workspace key, agent token, or webhook secret in a\nRelay message. The webhook secret is returned once to this local calling\nsession; keep it in a mode-0600 temporary file and delete the file after the\ntest.\n\n## Install this skill for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage, then place that unchanged `SKILL.md` where Codex actually loads global\nskills:\n\n```sh\nnpx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y\ncodex_skill=\"$HOME/.codex/skills/setting-up-agent-relay-desktop\"\nmkdir -p \"$codex_skill\"\ninstall -m 0644 \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\ncmp \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\n```\n\nDo not use prpm's `--as codex` conversion for this package. It currently writes\nunder `~/.agents/skills`, which Codex does not load as its global skill folder,\nand its conversion drops explanatory paragraphs from this Markdown workflow.\nConfirm both final paths explicitly before continuing.\n\n## 1. Detect the host and current session\n\nRun setup commands from this agent's own shell tool. Do not run them from an\nunrelated terminal: the app identifies the caller from kernel credentials and\nthe Codex/Claude process ancestry.\n\n```sh\nuname -s\nuname -m\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\nif test \"$(uname -s)\" = Linux; then\n  if command -v dpkg-query >/dev/null; then\n    printf 'linux_install=deb\\n'\n  else\n    printf 'linux_install=per-user-tarball\\n'\n  fi\nfi\ncommand -v systemctl >/dev/null && systemctl --user is-system-running || true\n```\n\nOn Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other\nsystemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball\npath; do not try to install the `.deb`. The app scans same-user process trees\nand TTYs; it does not require the service itself to share the tmux session.\n\n`systemctl --user is-system-running` may report `degraded` because an unrelated\nuser unit failed. That is not a Relay failure when\n`systemctl --user is-active agent-relay.service` reports `active` and the Relay\nsocket passes its status check.\n\nFind an existing socket without printing private files:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test -n \"${XDG_RUNTIME_DIR:-}\"; then\n  relay_socket=\"$XDG_RUNTIME_DIR/agent-relay/relay.sock\"\nfi\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"/run/user/$(id -u)/agent-relay/relay.sock\"\nfi\nc=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Darwin && test -S \"$c\"; then   # pointer file missing: use the app's own socket\n  relay_socket=$c\nfi\ntest -S \"${relay_socket:-/nonexistent}\" && printf 'socket=%s\\n' \"$relay_socket\"\n```\n\nIf the socket exists, inspect it before installing anything:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout\n(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's\n`relay socket-request` can give up sooner with \"Probe could not finish. Check\nyour connection and run setup again\"; on these paths that is the same latency,\nnot a setup problem. Retry the call once before reporting a blocker, and do not\nstart a second install or sign-in because of it.\n\nPreserve a working newer install. When the socket is absent, check for an\ninstalled-but-stopped copy before downloading: use `dpkg-query -W agent-relay`\nwhen `dpkg-query` exists and `systemctl --user status agent-relay.service` on\nLinux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry\nstatus first.\nUpdate an older install only when it lacks the setup contract or reports an\nolder version. A `404` from `/setup/status` means the installed build is too\nold for agent-driven setup and should be updated.\n\n## 2. Install or update with checksum verification\n\nUse a private temporary directory. Never skip the published SHA-256 check.\n\n### Ubuntu LTS, headless `.deb` (preferred)\n\nSelect the release architecture and install:\n\nThis path needs passwordless sudo or one human-approved sudo prompt for the\npackage install and `loginctl enable-linger`. Explain that prerequisite before\nstarting; never capture or relay a sudo password.\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb\" -o \"$relay_tmp/AgentRelay.deb\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb.sha256\" -o \"$relay_tmp/AgentRelay.deb.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#\" AgentRelay.deb.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nsudo apt-get install -y \"$relay_tmp/AgentRelay.deb\"\nsudo loginctl enable-linger \"$USER\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n```\n\nThe unit runs the bundled core headless: no display, X server, or GTK\nwindow is needed. This session's own GitHub subscriptions (section 6) go\nthrough the Desktop and need no CLI. The separate Agent Relay CLI is needed\nonly to subscribe a fleet-spawned or named agent; record whether it is present\nand at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app\ndiscovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:\n\n```sh\nrelay_cli=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay\" \\\n  \"$HOME/.npm-global/bin/agent-relay\" \\\n  \"$HOME/.agentworkforce/relay/bin/agent-relay\"\ndo\n  if test -x \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n    relay_cli=$candidate\n    break\n  fi\ndone\nif test -z \"$relay_cli\"; then\n  for relay_root in \\\n    \"$HOME/.local/share/mise/installs/node\" \\\n    \"$HOME/.nvm/versions/node\"\n  do\n    test -d \"$relay_root\" || continue\n    candidate=$(find -L \"$relay_root\" -mindepth 3 -maxdepth 3 \\\n      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)\n    if test -n \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n      relay_cli=$candidate\n      break\n    fi\n  done\nfi\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" integration subscribe --help >/dev/null\nelse\n  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\\n'\nfi\n```\n\nOn Linux without `dpkg`, use this per-user tarball installation under a\nversioned user directory. It is also the fallback on Ubuntu when `.deb`\ninstallation is unavailable and the human approves a per-user install. The\narchive contains a unit whose `/usr/bin` path is correct for packages, so\nrewrite only that `ExecStart` in the user copy:\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz\" -o \"$relay_tmp/AgentRelay.tar.gz\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256\" -o \"$relay_tmp/AgentRelay.tar.gz.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#\" AgentRelay.tar.gz.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmkdir \"$relay_tmp/extracted\"\ntar -xzf \"$relay_tmp/AgentRelay.tar.gz\" -C \"$relay_tmp/extracted\"\nrelay_tree=\"$relay_tmp/extracted/AgentRelay-linux-$relay_arch\"\ntest -x \"$relay_tree/usr/bin/agent-relay\"\nrelay_version=$(sed -n 's/^__version__ = \"\\([0-9A-Za-z._-]*\\)\"$/\\1/p' \\\n  \"$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py\")\ncase \"$relay_version\" in\n  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\\n' >&2; exit 1 ;;\nesac\nrelay_unit=\"$HOME/.config/systemd/user/agent-relay.service\"\nrelay_installed_version=\nif test -S \"${relay_socket:-/nonexistent}\"; then\n  relay_installed_version=$(curl -fsS --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)\nfi\nif test -z \"$relay_installed_version\" && test -r \"$relay_unit\"; then\n  relay_installed_version=$(sed -n \\\n    's#^ExecStart=.*/\\.local/lib/agent-relay/\\([^/ ]*\\)/.*#\\1#p' \\\n    \"$relay_unit\")\nfi\ncase \"$relay_installed_version\" in\n  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;\nesac\nif test -n \"$relay_installed_version\" && \\\n   test \"$relay_installed_version\" != \"$relay_version\" && \\\n   test \"$(printf '%s\\n%s\\n' \"$relay_version\" \"$relay_installed_version\" | sort -V | tail -n 1)\" = \"$relay_installed_version\"; then\n  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\\n' \\\n    \"$relay_installed_version\" \"$relay_version\" >&2\n  exit 1\nfi\nrelay_prefix=\"$HOME/.local/lib/agent-relay/$relay_version\"\nmkdir -p \"$relay_prefix\"\ncp -a \"$relay_tree/usr\" \"$relay_prefix/\"\nmkdir -p \"$(dirname \"$relay_unit\")\"\nsed \"s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#\" \\\n  \"$relay_tree/usr/lib/systemd/user/agent-relay.service\" >\"$relay_unit.tmp\"\nchmod 0644 \"$relay_unit.tmp\"\nmv \"$relay_unit.tmp\" \"$relay_unit\"\ngrep -F \"ExecStart=$relay_prefix/usr/\" \"$relay_unit\" | grep -q -- ' --headless$'\nif ! loginctl show-user \"$USER\" -p Linger | grep -qx 'Linger=yes'; then\n  sudo loginctl enable-linger \"$USER\"\nfi\nsystemd-analyze --user verify \"$relay_unit\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n# List the app in the desktop's app launcher (no-op on a headless server).\n# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the\n# entry the first time it is opened.\nif test -x \"$relay_prefix/usr/bin/agent-relay-desktop\"; then\n  \"$relay_prefix/usr/bin/agent-relay-desktop\" --install-launcher || true\nfi\n```\n\nThe unit's `ExecStart` names the archive's own path under `/usr/`, either the\nlauncher or the bundled `agent-relay-probe`; the rewrite moves whichever it is\nunder `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its\nfull path, never the bare `agent-relay`, which is also the CLI's name.\n\nDo not improvise Alpine or RHEL distribution packages. On a compatible\nsystemd host without `dpkg`, use only the verified per-user tarball path above;\nnon-systemd hosts remain unsupported by this Linux workflow.\n\n### macOS DMG\n\n```sh\ncase \"$(uname -m)\" in\n  arm64) relay_arch=arm64 ;;\n  x86_64) relay_arch=x64 ;;\n  *) printf 'Unsupported Mac architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg\" -o \"$relay_tmp/AgentRelay.dmg\"\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg.sha256\" -o \"$relay_tmp/AgentRelay.dmg.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#\" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmount_point=$(hdiutil attach -nobrowse -readonly \"$relay_tmp/AgentRelay.dmg\" | awk '/\\/Volumes\\// {sub(/^.*\\/Volumes\\//,\"/Volumes/\"); print; exit}')\nincoming_id=$(defaults read \"$mount_point/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\nif test \"$incoming_id\" != com.agentrelay.desktop; then\n  hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\\n' \"$incoming_id\" >&2\n  exit 1\nfi\nif test -d \"/Applications/Agent Relay.app\"; then\n  existing_id=$(defaults read \"/Applications/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\n  if test \"$existing_id\" != com.agentrelay.desktop; then\n    hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\\n' \"$existing_id\" >&2\n    exit 1\n  fi\nfi\nosascript -e 'tell application \"Agent Relay\" to quit' 2>/dev/null || true\nditto \"$mount_point/Agent Relay.app\" \"/Applications/Agent Relay.app\"\nhdiutil detach \"$mount_point\"\nopen -a \"Agent Relay\"\n```\n\nIf `/Applications` needs administrator access, use `sudo ditto` only after the\nhuman has authorized installation. Do not remove or overwrite another app with\nan unexpected bundle identity.\n\nAfter either install, wait up to 30 seconds for the pointer:\n\n```sh\napp_sock=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nfor _ in $(seq 1 30); do\n  test -r \"$HOME/.agentworkforce/desktop/relay-socket\" && break\n  test \"$(uname -s)\" = Darwin && test -S \"$app_sock\" && break   # the app is already listening\n  sleep 1\ndone\nrelay_socket=$(sed -n '1p' \"$HOME/.agentworkforce/desktop/relay-socket\" 2>/dev/null)\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Darwin && test -S \"$app_sock\"; then\n  relay_socket=$app_sock\nfi\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock\"\nfi\ntest -S \"$relay_socket\"\ncurl -fsS --unix-socket \"$relay_socket\" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'\n```\n\n## 3. Sign in by device approval\n\nBefore choosing a workspace, check what the human already has. These commands\nonly read state. The CLI checks run only when section 2 found a `relay_cli`;\nnever call the `.deb`'s `/usr/bin/agent-relay` launcher for them:\n\n```sh\ncurl -sS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'\nif test -n \"${relay_cli:-}\"; then\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nSign in to the workspace they already use. Pick a different or new workspace\nonly when the human explicitly asks for it.\n\nFor a multi-server rollout, obtain the existing enterprise workspace UUID from\nthe human and pass it explicitly on every server. Do not guess it and do not\nuse `{}` when the target workspace is known: that could select a default/free\nworkspace and split the fleet. Use `{}` only for an individual setup where the\nhuman has confirmed that the reusable login's current workspace is intended.\n\n```sh\nrelay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'\nsign_in_payload=$(jq -nc --arg workspace \"$relay_workspace_uuid\" '{workspace:$workspace}')\nsign_in=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nIf sign-in reports that older upload schedules could not be inspected, first\ninspect the user's legacy cron, launchd, and user-service upload schedules.\nAfter completing that safety check, retry the original request with the\nacknowledgement added; never use it merely to suppress the error:\n\n```sh\nsign_in_payload=$(printf '%s\\n' \"$sign_in_payload\" | \\\n  jq '. + {acknowledge_uninspected_schedules:true}')\nsign_in=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nPrint a device link and code only when the response actually contains a code:\n\n```sh\nuser_code=$(printf '%s\\n' \"$sign_in\" | jq -r '.data.user_code // empty')\nif test -n \"$user_code\"; then\n  verification_url_complete=$(printf '%s\\n' \"$sign_in\" | \\\n    jq -r '.data.verification_url_complete // empty')\n  if test -n \"$verification_url_complete\"; then\n    printf 'Open %s and approve code %s\\n' \"$verification_url_complete\" \"$user_code\"\n  else\n    verification_url=$(printf '%s\\n' \"$sign_in\" | \\\n      jq -r '.data.verification_url // empty')\n    printf 'Open %s and enter code %s\\n' \"$verification_url\" \"$user_code\"\n  fi\nfi\n```\n\nIf the response is `signed_in` with `reused_login:true`, the app reused an\neligible same-origin CLI or desktop login and intentionally issued no device\ncode. Confirm the returned workspace id and name with the human rather than\nwaiting for a code, then continue only if it is the intended workspace.\n\nFor `pending_approval`, the human can approve from any phone or browser. Do not\ncreate another code while this one is pending. A `preparing` response is also\nnormal: poll `/setup/status` at the reported interval. Preparing local history\ncan take about a minute when the app reuses an existing `agent-relay` CLI login.\nPoll both states until sign-in finishes. The reason for a failure is in\n`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so\nprint it, and map the known messages to their fix instead of dumping raw state:\n\n```sh\nwhile :; do\n  state=$(curl -sS --unix-socket \"$relay_socket\" http://relay/setup/status)\n  phase=$(printf '%s' \"$state\" | jq -r '.data.sign_in // .error.code')\n  case \"$phase\" in\n    signed_in)\n      printf '%s\\n' \"$state\" | jq \\\n        '{sign_in: .data.sign_in, workspace: .data.workspace}'\n      break\n      ;;\n    preparing|pending_approval) ;;\n    denied|expired|error)\n      msg=$(printf '%s' \"$state\" | jq -r '.data.sign_in_message // .error.message // \"no message reported\"')\n      printf 'Sign-in %s: %s\\n' \"$phase\" \"$msg\" >&2\n      case \"$msg\" in\n        *\"older managed history uploader\"*)\n          printf 'See \"Sign-in blocked by a legacy uploader\" under Recovery.\\n' >&2 ;;\n        *\"older upload schedules\"*)\n          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\\n' >&2 ;;\n        *) printf '%s\\n' \"$state\" | jq '.data' >&2 ;;\n      esac\n      exit 1\n      ;;\n  esac\n  sleep \"$(printf '%s' \"$sign_in\" | jq -r '.data.interval // 5')\"\ndone\n```\n\n## 4. Apply the agent-led defaults and register this session\n\nRead the current sharing mode before changing it. `/setup/status` reports it as\n`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is\nuploading yet). The probe reports the same field, `sharing_mode`, in\n`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -r '.data.sharing_mode'\n```\n\nOn a fresh install, or when it already reports `new`, use `new`. When an\nexisting install reports `all` (which also uploads past sessions, so it is\nbroader than this skill's default) or `selected`, tell the human the current\nmode and ask whether to keep it or change it to `new`. Never change it silently.\nSet `relay_sharing_mode` below to the human's answer.\n\nThen set and verify all three agent-led defaults even when the app's `/setup/*`\nbootstrap already applied them. Sharing mode `new` uploads every new session;\nauto-activation puts every existing live session and every future session on\nthe relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:\n\n```sh\nrelay_sharing_mode=new   # or the existing mode the human chose to keep\ndirect_delivery=$(curl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' http://relay/setup/direct-delivery)\nprintf '%s\\n' \"$direct_delivery\" | jq\nif ! printf '%s\\n' \"$direct_delivery\" | jq -e '.ok and .data.direct_delivery'; then\n  if printf '%s\\n' \"$direct_delivery\" | jq -e '.error.code == \"managed_policy\"' >/dev/null; then\n    printf 'Organization-managed Claude settings forbid direct delivery.\\n' >&2\n  fi\n  exit 1\nfi\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d \"$(jq -nc --arg mode \"$relay_sharing_mode\" '{mode:$mode}')\" \\\n  http://relay/setup/sharing | jq\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' \\\n  http://relay/setup/auto-activate | jq\nregister=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/register)\nprintf '%s\\n' \"$register\" | jq\nregistration_status=$(curl -sS --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status)\nprintf '%s\\n' \"$registration_status\" | \\\n  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'\nprintf '%s\\n' \"$registration_status\" | jq -e \\\n  '.ok and (.data.session.id | type == \"string\" and length > 0) and\n   .data.session.registered == true and .data.session.direct_delivery == true'\n```\n\nDirect delivery is checked first so a managed-policy refusal stops setup\nbefore auto-activation or upload settings are changed. Report that refusal\nclearly; never claim the three-default setup completed.\n\nSharing mode and auto-activate are different settings: the former\ncontrols upload eligibility and the latter controls Relay registration. The\nsetup flow requires both.\n\n`POST /register` discovers the nearest live Codex or Claude ancestor. A session\ninside tmux over SSH is valid. Never pass a session id or token in the body.\nThe default name includes a 128-bit session-derived suffix, so dozens of\nsessions in the same checkout receive distinct `name@direct` addresses. Save\nand report the address from `/setup/status` for each session; never reuse one\nsession's address for another. `/register` may omit the session id or\ndirect-delivery state, so its response alone is not verification. Require the\nstatus response to show this session's non-empty id, `registered:true`, and\n`session.direct_delivery:true` as above. An app fix is expected to add those\nfields to `/register`, but the status check remains authoritative.\n\n## 5. Create and test the webhook\n\nPerform this section only when the human requested a webhook (or explicitly\nasked for the full end-to-end setup). Otherwise skip it; webhook creation is a\npersistent external mutation, not an install prerequisite.\n\nCapture the one-time secret without echoing it:\n\n```sh\numask 077\nhook_file=$(mktemp)\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/webhooks >\"$hook_file\"\njq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' \"$hook_file\"\n```\n\nWhen `created:true`, send a unique marker. Initialize every temporary path so\ncleanup can name and delete exact files without `-f` or globs:\n\n```sh\nhook_config=\nmarker=\nwebhook_post_ok=false\nwebhook_post_status=0\nif test \"$(jq -r '.data.created // false' \"$hook_file\")\" = true && \\\n   test \"$(jq -r '.data.secret // empty' \"$hook_file\")\" != ''; then\n  hook_url=$(jq -r '.data.url' \"$hook_file\")\n  hook_secret=$(jq -r '.data.secret' \"$hook_file\")\n  hook_config=$(mktemp)\n  chmod 600 \"$hook_config\"\n  printf 'header = \"Authorization: Bearer %s\"\\n' \"$hook_secret\" >\"$hook_config\"\n  marker=\"agent-relay-webhook-test-$(date +%s)\"\n  if curl -fsS --config \"$hook_config\" -X POST \"$hook_url\" \\\n      -H 'Content-Type: application/json' \\\n      -d \"{\\\"text\\\":\\\"$marker\\\",\\\"source\\\":\\\"agent-driven-setup\\\"}\"; then\n    webhook_post_ok=true\n  else\n    webhook_post_status=$?\n  fi\nelse\n  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\\n' >&2\nfi\nif test -n \"$hook_config\" && test -e \"$hook_config\"; then\n  rm -- \"$hook_config\"\nfi\nif test -e \"$hook_file\"; then\n  rm -- \"$hook_file\"\nfi\nunset hook_secret\nif test \"$webhook_post_ok\" = true; then\n  printf 'Webhook test sent; end this turn and wait for marker: %s\\n' \"$marker\"\nelif test -n \"$marker\"; then\n  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\\n' \\\n    \"$webhook_post_status\" >&2\n  exit \"$webhook_post_status\"\nfi\n```\n\nDo not claim success merely because the POST returned 2xx, and do not sleep or\npoll for the injected message during the same turn. Relay injects only after\nthe session becomes idle between turns. After the POST and exact-file cleanup,\nend the current turn by saying that setup is waiting for the exact marker. On\nthe next turn, confirm that the injected body contains that marker and its\nAgent Relay header contains a full message id; record that id in the final\nevidence. If a polling consumer is part of the setup, also observe that same id\nthere before declaring the webhook test complete. If the webhook already\nexisted, its secret is correctly returned as null; do not revoke or recreate it\nwithout human authorization. Ask for the existing secret or report that the\ndelivery test could not be repeated.\n\n## 6. Subscribe requested integrations\n\nRequire the provider and repository from the human. A GitHub pull request needs\none resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's\nreviews, review comments, conversation comments and check runs to that glob by\nthe PR they reference, so no other glob is needed: nothing is written under\n`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or\n`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This\nworks on every released Desktop and is the path to use today. If a review or\ncomment then never arrives, read it back in relayfile at its own path (the\ntable in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event\nnever reached relayfile\n([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),\nnot that the subscription is wrong.\n\nFirst find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions\n(below) and it is the client for the one-command form once that ships:\n\n```sh\nrelay_probe=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay-probe\" \\\n  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n  \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"\ndo\n  if test -x \"$candidate\"; then relay_probe=$candidate; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\nprintf 'relay_probe=%s\\n' \"${relay_probe:-none}\"\n```\n\nA running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the\nother candidates are the copies bundled by the `.deb`, the macOS app, and the\nper-user tarball. Then subscribe through the socket. On macOS use the probe\nclient when there is one: the system `curl` hides a Codex session's identity\nthere and is refused `not_a_relay_session`, so a Codex session with no probe\nstops instead. `curl` is correct for Claude Code and on Linux:\n\n```sh\n# One client for every socket request in this section and in undo: the probe\n# on macOS (system curl hides a Codex session there), curl elsewhere.\nrelay_req() {  # METHOD PATH [JSON body]\n  if test \"$(uname -s)\" = Darwin && test -n \"${relay_probe:-}\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\\n' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' -d \"$3\" \"http://relay$2\"\n  else\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n\n# This PR's subscriptions, in whichever form they were made. Fails, rather than\n# answering \"none\", when the status cannot be read: both callers stop then.\npr_url='https://github.com/OWNER/REPO/pull/NUMBER'\npr_resources() {\n  relay_status=$(relay_req GET /setup/status) || return 1\n  # -s reads the whole body as one list, so an empty body is an error too.\n  printf '%s\\n' \"$relay_status\" | jq -rs --arg url \"$pr_url\" \\\n    --arg short 'OWNER/REPO#NUMBER' \\\n    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \\\n    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '\n    if length == 1 and .[0].ok == true\n       and (.[0].data.integrations | type) == \"array\" then\n      .[0].data.integrations[] | select(.provider == \"github\") | .resource\n      | select(. == $url or . == $short or startswith($url + \"/\")\n               or startswith($pulls) or startswith($issues))\n    else\n      error(\"Agent Relay status is unreadable; no subscription was changed.\")\n    end'\n}\n\nheld=$(pr_resources) || exit 1\nif printf '%s\\n' \"$held\" | grep -Fqx -e \"$pr_url\" -e 'OWNER/REPO#NUMBER'; then\n  # The one-command subscription is a single complete request: nothing to add.\n  printf 'Already subscribed:\\n%s\\n' \"$held\"\nelif test -z \"$held\" && test -n \"${relay_probe:-}\" && \\\n     \"$relay_probe\" relay --help 2>&1 | grep -q '^  subscribe'; then\n  # The one-command form (below), only for a PR with no subscription yet and\n  # only when the installed probe has it.\n  \"$relay_probe\" relay subscribe \"$pr_url\" | jq\nelse\n  relay_req POST /integrations/subscribe \\\n    \"$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \\\n      '{provider:\"github\",resource:$resource}')\" | jq\nfi\nrelay_req GET /setup/status | jq -c '.data.integrations'\n```\n\nRequire `.ok` and `.data.subscribed` to be `true`, and the entry in the status\nlist to be `ready: true`. A repeated request returns HTTP 409\n`conflict` (\"already subscribed\"). That is success only for a binding made on\nor after 2026-09-19. Earlier bindings predate PR-identity matching\n(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews\nand comments. If the binding may be older, or you cannot tell, recreate it\nonce: `relay_req DELETE /integrations/subscribe` with the same body, then\nsubscribe again. Verified on\nDesktop 2026.10.6 with both the probe client and `curl`.\n\n**One-command form (not yet released).** `relay-desktop#216` adds\n`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`\n(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription\nthat the Desktop correlates with the PR's reviews, comments, and checks. It is\nabsent from Desktop 2026.10.6, where it fails with `unrecognized subcommand\n'subscribe'`, so do not lead with it. Use it only when the installed probe\nadvertises it. The block above makes that choice, and first checks the\nsession's existing subscriptions. A pull request already subscribed with the\none-command form is left alone. A pull request already holding\nthe number glob answers 409 `conflict` on a repeat; recreate that binding once\nif it may predate 2026-09-19 (see above). Extra `reviews`, `status` or\n`issues/NUMBER/comments` globs from an earlier version of this skill never\ndeliver; unsubscribe them.\n\nOnce released, re-test it before relying on its details; the behavior described\nin that PR (a repeat answering `\"already_subscribed\":true`, `--remove` to end it,\nand a numeric subscription covering reviews, comments and checks) has not been verified here.\n\nRefusals and what they mean:\n\n- `not_a_relay_session`, \"Register this session before subscribing it\": run\n  section 4's `POST /register` first.\n- `not_a_relay_session`, \"already managed by this computer's relay\" from\n  `/register`: this session was started by the Agent Relay fleet broker, not\n  the Desktop. Use the workspace CLI below instead.\n- `refused` or `busy`: an earlier subscription is still being made or cleaned\n  up; repeat the command shortly.\n\nA fleet-spawned session, or an operator subscribing a named agent, uses the\n`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in\n`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let\nthe worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail\nwith `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`\nis set:\n\n```sh\npull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'\nrelay_cli_major=\nif test -n \"${relay_cli:-}\"; then\n  relay_cli_major=$(\"$relay_cli\" --version 2>/dev/null | sed -n 's/^[^0-9]*\\([0-9][0-9]*\\)\\..*/\\1/p' | sed -n '1p')\nfi\nif test -n \"$relay_cli_major\" && test \"$relay_cli_major\" -ge 13; then\n  \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelif test -n \"$relay_cli_major\"; then\n  # 12.x and older: keep the ambient agent token from displacing the key.\n  env -u RELAY_AGENT_TOKEN \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelse\n  # No usable installed CLI: run the fixed release without installing it.\n  npx -y agent-relay@13 integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nfi\n```\n\nUse the `relay_cli` found in section 2, never a bare `agent-relay`: on a\n`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may\nresolve to it or to a different, older CLI than the one whose version was\nchecked.\n\nThe CLI path follows `orchestrating-agent-relay`, which subscribes the same\nsingle `pulls/NUMBER/**` glob. Never put the workspace key in argv.\n\nMake the subscribe step a required post-create step in the agent's PR\nworkflow: whenever it authors a PR, it subscribes its own live session\nimmediately, without waiting for an operator to name the PR. This is the\nauthored-PR pattern from `orchestrating-agent-relay`; it covers every future PR\nthe agent authors without subscribing unrelated repository traffic. The\nDesktop removes the subscription itself after the PR closes or merges.\nFor real GitHub verification, use a harmless event the human authorized\non that PR (for example, a test conversation comment and a requested bot\nreview). After causing the event, do not wait or poll within the active turn:\nend the turn saying which event marker is expected. Confirm the injected event\nand record its full message id on the next turn after Relay has delivered it.\nDo not create a comment, review, or rerun without authorization. A successful\nsubscribe response alone does not prove end-to-end delivery.\n\n## 7. Coexist with a REST-polling MCP\n\nDo not disable an existing polling consumer. Desktop injection acknowledges\nonly this registered agent's delivery queue and does not advance a separate\nworkspace consumer's cursor. A polling MCP should use its own identity/cursor,\nnot this session agent's `/v1/deliveries` token.\n\nInjected text contains both the full Relaycast message id and a short `ref`.\nWhen polling and injection can surface the same workspace message, deduplicate\non the full message id before acting. During verification, leave the poller\nrunning and observe the test message there. Then end the current turn so Relay\ncan inject it, and on the next turn confirm the same full id arrived while the\nagent acted only once.\n\n## 8. Final verification and report\n\nRead status again:\n\n```sh\ncurl -sS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'\n```\n\nRequire all three defaults before declaring setup complete:\n\n```sh\ncurl -fsS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -e --arg mode \"${relay_sharing_mode:-new}\" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'\n```\n\nReport the exact version, `signed_in`, signed-in workspace id and name, sharing\nmode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,\nuploader health, session address, direct-delivery state, webhook test marker,\nsubscriptions, real GitHub event evidence, and polling-coexistence result.\nSeparate verified facts from steps that still require a human or external\nevent.\n\n## Recovery and undo\n\n- **Socket missing or slow:** check `systemctl --user status agent-relay.service`\n  on Linux or `open -a \"Agent Relay\"` on macOS. Confirm the pointer names a\n  socket. Never delete a live socket; restart the owning service/app. A reply\n  that takes up to about 30 seconds is the known latency in section 1\n  (relay-desktop#333), not a fault: allow 60 seconds and retry once.\n- **`not_a_relay_session`:** the command is not a descendant of a supported\n  live Codex/Claude session, or the session id/process start no longer matches.\n  Run it through this agent's shell tool. In tmux, confirm the agent process and\n  shell share the pane's process tree.\n- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message \"An older\n  managed history uploader is active. Stop it explicitly before enabling this\n  probe.\"): the probe counts any of these legacy `ai-hist push` registrations as\n  active, even when idle: the file\n  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded\n  launchd label `com.ai-hist.push`, or a crontab line containing\n  `# ai-hist push (managed)`. Check each, then with the human's approval unload\n  and move aside (do not delete) what exists. Create the backup directory first,\n  use a unique no-clobber destination, and confirm the move before retrying:\n\n  ```sh\n  # bootout exits non-zero when the label was never loaded; that is fine, so\n  # judge success by whether the label is still loaded, not by its exit code.\n  launchctl bootout \"gui/$(id -u)/com.ai-hist.push\" 2>/dev/null || true\n  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then\n    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2\n    exit 1\n  fi\n  plist=\"$HOME/Library/LaunchAgents/com.ai-hist.push.plist\"\n  if test -e \"$plist\"; then\n    backup_dir=\"$HOME/.agentworkforce/backup\"\n    mkdir -p \"$backup_dir\"\n    mv -n \"$plist\" \"$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)\"\n    test ! -e \"$plist\" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }\n  fi\n  ```\n\n  If instead the marked cron line is the cause, back up the full crontab first\n  and remove only that line, so the change can be reversed with\n  `crontab <backup-file>`:\n\n  ```sh\n  mkdir -p \"$HOME/.agentworkforce/backup\"\n  cron_backup=\"$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)\"\n  crontab -l > \"$cron_backup\" && test -s \"$cron_backup\" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }\n  grep -vF '# ai-hist push (managed)' \"$cron_backup\" | crontab -\n  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }\n  ```\n\n  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run\n  `/setup/sign-in` with the same payload.\n- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the\n  request. Restart after `expired` or `denied` to obtain a new code.\n- **Older schedules could not be inspected:** inspect the user's legacy cron,\n  launchd, or user-service upload schedules first. Only after that inspection,\n  retry `/setup/sign-in` with the original payload plus\n  `\"acknowledge_uninspected_schedules\":true`. This flag records a completed\n  safety check; never send it merely to silence an error.\n- **`not_allowed` from `/register`:** enable the app's self-registration\n  setting. Do not bypass it with workspace credentials.\n- **Managed Claude policy:** if direct delivery reports `managed_policy`, the\n  organization controls `crossSessionInbound`; report the policy block rather\n  than modifying managed settings.\n- **Undo registration:** `curl -sS --unix-socket \"$relay_socket\" -X DELETE http://relay/register | jq`.\n- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,\n  `relay_req`, and `pr_resources` defined, remove every subscription the\n  session holds for the pull request, in whichever form it was made. On macOS\n  `relay_req` uses the probe, and a Codex session without one stops instead of\n  sending a `curl` request that cannot be identified:\n\n  ```sh\n  held=$(pr_resources) || exit 1\n  printf '%s\\n' \"$held\" | while IFS= read -r resource; do\n    test -n \"$resource\" || continue\n    relay_req DELETE /integrations/subscribe \\\n      \"$(jq -nc --arg resource \"$resource\" '{provider:\"github\",resource:$resource}')\" | jq\n  done\n  relay_req GET /setup/status | jq -c '.data.integrations'\n  ```\n\n  Require the final list to hold none of that pull request's resources.\n- **Undo a webhook:** `curl -sS --unix-socket \"$relay_socket\" -X DELETE http://relay/webhooks | jq`.\n- **Undo direct delivery:** POST `{\"enabled\":false}` to\n  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed\n  organization policy still wins.\n- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to\n  `/setup/sharing`. Ask before changing it when the earlier value is unknown.\n- **Auto-activate accidentally enabled:** POST `{\"enabled\":false}` to\n  `/setup/auto-activate`. This does not remove existing registrations.\n- **Uninstall:** stop/disable the user service before removing the Linux\n  package, or quit the Mac app before removing it. Do not delete app data or\n  revoke webhooks unless the human explicitly asks for data removal.\n",
+  "setting-up-agent-relay-sessions": "# Set Up Agent Relay Session Handoff\n\nDrive the whole onboarding from this agent's own shell and MCP tools. Do **not**\nhand the person the six-step Markdown guide and ask them to click through the\napp and the dashboard.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the desktop app is installed, signed in to the **intended workspace**, the\n  uploader is healthy, and this session is registered with direct delivery on;\n- the **agent-sessions cloud MCP** is installed in this project and loaded by\n  this session, so the handoff tools (`list_relay_agents`, `send_relay_message`,\n  `read_relay_conversation`, `check_relay_inbox`, `get_shared_session`,\n  `get_shared_session_context`, `search_shared_sessions`) are available;\n- a live round trip is proven when a teammate is online: this agent messages the\n  teammate's agent, **reads the teammate's real session back** with\n  `get_shared_session_context`, and the teammate reads this session and replies.\n  When no teammate is online yet, the fallback is the roster plus this person's\n  own uploaded session reading back cleanly — reported as self-verified, not as a\n  proven two-way handoff.\n\n## Requires\n\nThis skill builds on `setting-up-agent-relay-desktop` (verified install, sign-in,\nregistration, agent-led defaults). If that skill is **not installed** in this\nagent, stop, tell the person, and have them install the companions together,\nthen restart the agent. Do not improvise the install or sign-in from memory.\n\n- prpm: `npx prpm install collections/agent-relay-setup --as claude --global -y`\n- skills.sh: `npx skills add https://github.com/AgentWorkforce/skills --skill setting-up-agent-relay-desktop --skill setting-up-agent-relay-sessions`\n- Codex: do not use prpm's `--as codex` (it drops paragraphs and writes under `~/.agents/skills`, which Codex does not load as its global skill folder). Mirror both installed `SKILL.md` files into `~/.codex/skills/<name>/` with the loop in **Install this skill (and its dependency)** below.\n\n## The only human steps\n\nEverything else is automatable; be honest that these are not. **Ask for all of\nthem up front, before touching anything** — the token in particular is needed\nonly at section 3, but minting it and exporting it into the launching\nenvironment takes the person a few minutes, so have them start it while the\ndesktop install and sign-in run:\n\n1. **Approve one Google device-login link** — only when no reusable `agent-relay`\n   CLI/desktop login exists. A reused login needs zero clicks.\n2. **Provide one Bearer token** minted in the dashboard's **\"Connect your agent\"**\n   card. No setup route returns this token by design. **Do not have the person\n   paste it into this conversation** — the uploader shares this session's prompts\n   with teammates, so a pasted secret would become teammate-readable. Instead the\n   person puts it into the **environment that launches their agent** (or an OS\n   keychain / a mode-0600 file) via a shell *they* run, and this agent references\n   it only by variable name — never by value. See **Token handling** below.\n3. **Same workspace, both sides.** The teammate (or workspace admin) must have\n   invited this person's email to the **shared** workspace — two agents can only\n   reach each other inside one workspace. Confirm the workspace id matches on\n   both machines; do not guess it.\n\nOne structural note so expectations are right: there is **no automatic ack** to\nthe sender when a handoff is picked up, and **no partial session sharing** — a\nsession is on-or-off on the relay. Confirm a handoff by activity, not a push.\n\n## How this composes with `setting-up-agent-relay-desktop`\n\nThis skill is a thin layer on a working desktop. The desktop skill owns install,\nsign-in, defaults and self-registration; this one owns only the agent-sessions\ncloud MCP and the live handoff. Section 2 checks the desktop prerequisite and,\nif it is not met, invokes `/setting-up-agent-relay-desktop` to completion and\nreturns here. Keep the `/setup/*` details in that one skill so a contract change\nupdates it once.\n\n## Install this skill (and its dependency) for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage **and** the desktop skill it depends on, then mirror both unchanged\n`SKILL.md` files where Codex loads global skills:\n\n```sh\nfor pkg in setting-up-agent-relay-sessions setting-up-agent-relay-desktop; do\n  npx prpm install \"@agent-relay/$pkg\" --as claude --global -y\n  codex_skill=\"$HOME/.codex/skills/$pkg\"\n  mkdir -p \"$codex_skill\"\n  install -m 0644 \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\n  cmp \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\ndone\n```\n\nWith skills.sh instead, use the command under **Requires**; it installs into each agent's skills folder directly, so the manual Codex mirror below is only for the prpm route.\n\nDo not use prpm's `--as codex` conversion for these packages: it writes under\n`~/.agents/skills`, which Codex does not load as its global skill folder, and it\ndrops explanatory paragraphs from the Markdown workflow. Confirm both final\npaths explicitly before continuing.\n\n## Why ordering matters\n\nMCPs load at agent **startup**. The agent-sessions MCP must be installed\n**before** the session that will use it starts. A session already running when\nthe MCP was added has no handoff tools and must be **restarted**. Install the\nMCP (section 3) before relying on the tools (sections 4–5); if this very session\npredates the MCP, say so and restart it rather than reporting missing tools as a\nfailure.\n\n## Token handling\n\nThe token must never land in the agent conversation, in a Relay message, in\nprocess argv, or in the repo. Three places leak it, and this skill avoids all\nthree:\n\n- **The chat** — this session is uploaded and teammate-readable, so a token\n  pasted to the agent leaks to the workspace. The person sets it themselves (see\n  below); the agent only ever sees the variable **name**.\n- **Process argv** — a token interpolated into `claude mcp add --header\n  \"... Bearer $TOKEN\"` is visible to `ps` and gets written literally into\n  `~/.claude.json`. Pass the unexpanded placeholder `${AGENT_RELAY_SESSIONS_TOKEN}`\n  instead; Claude Code expands `${VAR}` in MCP headers from the environment at\n  launch, so the stored config holds only a reference and argv holds only the\n  literal `${…}`. **This expansion exists only in Claude Code ≥ 2.1.119** — an\n  older client sends the placeholder literally and auth fails, so check the\n  version first (section 3) and update Claude rather than inlining the token.\n- **The launching environment** — both CLIs read the token from an environment\n  variable (`${VAR}` for Claude, `--bearer-token-env-var` for Codex), so the\n  variable must exist in the environment that **launches the agent**, not in a\n  transient shell-tool subprocess (which cannot alter its parent or a later\n  process).\n\nUse the single variable name `AGENT_RELAY_SESSIONS_TOKEN` throughout. Keep the\none-time entry separate from durable supply:\n\n- **One-time, into the current shell** (non-echoing, run by the person, never\n  the agent): `read -rs AGENT_RELAY_SESSIONS_TOKEN && export AGENT_RELAY_SESSIONS_TOKEN`,\n  then launch the agent from *that* shell. Do **not** add this `read` to a shell\n  profile — every shell that sources the profile would block waiting for input.\n- **Durable across restarts:** store the token in the OS keychain or a mode-0600\n  file, and have the launcher export it **non-interactively**, e.g.\n  `export AGENT_RELAY_SESSIONS_TOKEN=\"$(security find-generic-password -s agent-relay-sessions -w)\"`\n  (macOS keychain) or from a 0600 file. Put that line in a dedicated launcher the\n  person starts the agent from — not an interactive prompt in the profile.\n\nThe agent never prints the value; verify presence only with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"`.\n\n## 0. Preflight: collect the human inputs first\n\nBefore section 1, tell the person what they need and ask for it in one message:\n\n1. the **shared workspace id** (or the teammate/admin who invited them);\n2. a **Bearer token** minted in the dashboard's \"Connect your agent\" card for\n   that workspace, stored by *them* as `AGENT_RELAY_SESSIONS_TOKEN` in the\n   environment that launches their agent (see **Token handling** — never pasted\n   into this chat);\n3. the **teammate's relay address** for the round trip, if one will be online.\n\nBefore sending that message, check what this machine already has. If an Agent\nRelay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not\nthe `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only\nchecks. Without one, section 2 reads the signed-in workspace from\n`/setup/status` instead. The CLI is optional for this skill: check with\n`command -v agent-relay` and `agent-relay --version`, and do not install or\nupgrade it just for these checks.\n\n```sh\nagent-relay cloud whoami       # signed in, and as whom\nagent-relay workspace active   # the active Cloud workspace (keys stay masked)\nagent-relay cloud workspaces   # every workspace this login can use, with ids\nagent-relay status             # workspace, cloud login and local broker\n```\n\nIf the active workspace is already the shared one, confirm it with the person\ninstead of asking them to look it up. Never switch to or create another\nworkspace unless they explicitly ask.\n\nCheck presence without printing the value:\n\n```sh\ntest -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\" && echo token=present || echo token=missing\n```\n\nA missing token does **not** block sections 1–3: the MCP config stores only a\n`${AGENT_RELAY_SESSIONS_TOKEN}` reference, never the value, so it can be added\nnow. Do the desktop work and add the MCP, then have the person restart the agent\n**once**, from an environment that exports the token, so that single restart both\nloads the MCP and supplies the credential. Sections 4–5 are gated on that\nrestart. If the person would rather not defer, they can export the token and\nrestart first, which then costs a second restart only if the MCP was added after.\n\n## 1. Confirm the host and this session\n\nRun every command from this agent's own shell tool, and only from a **genuine\ninteractive** Claude Code or Codex session. The app identifies the caller from\nkernel credentials and resolves its process ancestry against discovered live\nsessions, so a command from an unrelated terminal — or from a non-interactive\n`codex exec` / `claude -p` run — is rejected with `not_a_relay_session`. (This\nis verified: a plain SSH shell and a `codex exec` invocation are both refused;\nan interactive session is admitted.)\n\n```sh\nuname -s; uname -m\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\n```\n\nDefine the request helper once per shell. It finds the private setup socket\nwithout printing private files and uses the desktop's `agent-relay-probe` on\nmacOS (the system `curl` hides a Codex session's identity there and is refused\n`not_a_relay_session`), `curl` elsewhere, and stops with a message for a macOS\nCodex session that has no probe:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Linux; then\n  for c in \"${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock\" \"/run/user/$(id -u)/agent-relay/relay.sock\"; do\n    if test -S \"$c\"; then relay_socket=$c; break; fi\n  done\nfi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Darwin; then   # pointer file missing: use the app's own socket\n  c=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\n  if test -S \"$c\"; then relay_socket=$c; fi\nfi\nrelay_probe=\nfor c in \"$HOME/.local/bin/agent-relay-probe\" \\\n         /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n         \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"; do\n  if test -x \"$c\"; then relay_probe=$c; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then   # per-user tarball\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\n# relay_req METHOD PATH [JSON-BODY]\nrelay_req() {\n  if ! test -S \"${relay_socket:-/nonexistent}\"; then\n    echo 'No Agent Relay socket found; start Agent Relay (the desktop) and retry.' >&2\n    return 1\n  fi\n  if test \"$(uname -s)\" = Darwin && test -n \"$relay_probe\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    echo 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename\n    printf '%s' \"$3\" | curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' --data-binary @- \"http://relay$2\"\n  else\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add\n`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a\nfailure. The probe's `relay socket-request` can give up sooner with \"Probe\ncould not finish. Check your connection and run setup again\"; on these paths\nthat is the same latency, not a setup problem. Retry once before reporting a\nblocker, and do not rerun desktop setup because of it.\n\n## 2. Make sure the desktop is set up first\n\nSession handoff needs a signed-in, healthy desktop underneath it. If the socket\nis missing, or `/setup/status` returns `404`, or sign-in/uploader/registration\nare not in the finished state below, **invoke the `setting-up-agent-relay-desktop`\nskill** (`/setting-up-agent-relay-desktop`; if it is not installed, see **Requires**), let it run to completion, and then\nreturn to section 2's verification. Do not re-implement its install, sign-in, or\n`/setup/*` steps here — that skill is the single source of truth for them, and\nthis skill resumes once it reports a registered, signed-in session.\n\nVerify the desktop state this skill depends on:\n\n```sh\nrelay_req GET /setup/status | jq '{\n  version: .data.version,\n  sign_in: .data.sign_in,\n  workspace: .data.workspace,\n  sharing_mode: .data.sharing_mode,\n  uploader: .data.uploader,\n  direct_delivery: .data.direct_delivery,\n  session: .data.session,\n  defaults_error: .data.defaults_error\n}'\n```\n\nRequire all of these before continuing, and stop with a clear message if any\nfails. `/setup/status` reports sign-in as the string `sign_in` (match the desktop\nskill), and the flag that actually governs whether **this** session's handoff\nreplies arrive live is the session-level `session.direct_delivery`, not the\ntop-level default — require both:\n\n```sh\nrelay_req GET /setup/status | jq -e '\n  .ok\n  and .data.sign_in == \"signed_in\"\n  and (.data.workspace.id | type == \"string\" and length > 0)\n  and .data.uploader.healthy == true\n  and .data.direct_delivery == true\n  and (.data.session.id | type == \"string\" and length > 0)\n  and .data.session.registered == true\n  and .data.session.direct_delivery == true'\n```\n\nConfirm `workspace.id` is the **shared** workspace both sides agreed on. A\nhealthy uploader is the one non-obvious prerequisite: for a teammate's agent to\nread **this** person's session, this machine must have uploaded it. If\n`uploader.healthy` is false (paused, or a failed cycle), fix it before promising\nanyone can read this session — this is the single most common reason a live\nhandoff silently fails.\n\n`sharing_mode` decides which sessions upload at all. `new` and `all` include\nthis session. Under `selected`, only the sessions the person chose upload, so a\nteammate cannot read this one until the person selects it. Tell them that and\nask; do not change the sharing mode or select sessions on their behalf.\n\n## 3. Install the agent-sessions cloud MCP (before the session uses it)\n\nCheck whether the token is present in the environment **without printing it**\n(see **Token handling**). It is not required to *add* the MCP, since only a\nreference is stored, but it is required for the tools to authenticate after the\nrestart. If it is missing, add the MCP anyway, tell the person plainly that the\ntools will fail auth until they restart the agent from an environment that\nexports `AGENT_RELAY_SESSIONS_TOKEN`, and do not report setup complete:\n\n```sh\nif ! test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"; then\n  echo 'AGENT_RELAY_SESSIONS_TOKEN is not set here; the MCP will be added by reference, but the agent must be restarted from an environment that exports it.' >&2\nfi\n```\n\nDetect which agent CLI this session runs and install accordingly.\n\nClaude Code — pass the **unexpanded** placeholder so the token stays out of argv\nand out of `~/.claude.json`; Claude expands `${VAR}` in MCP headers from the\nenvironment at launch. This expansion requires **Claude Code ≥ 2.1.119**, so\nverify the version first and update rather than inlining the token on an older\nclient. Single-quote the header so the shell does not expand it here. Default\nscope is `local` (this project only), which is what you want:\n\n```sh\nclaude_ver=$(claude --version 2>/dev/null | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1)\nif test -z \"$claude_ver\" || test \"$(printf '%s\\n2.1.119\\n' \"$claude_ver\" | sort -V | head -1)\" != 2.1.119; then\n  echo \"Claude Code $claude_ver does not expand \\${VAR} in MCP headers (need >= 2.1.119); update Claude Code before adding this server.\" >&2\n  exit 1\nfi\nclaude mcp add --transport http agent-relay-sessions \\\n  https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --header 'Authorization: Bearer ${AGENT_RELAY_SESSIONS_TOKEN}'\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nCodex — `codex mcp add` records the **variable name**, not the value, and writes\nto user-level `~/.codex/config.toml`, so the server is enabled for **all** Codex\nprojects (Codex has no project-scoped MCP). Confirm the person is OK with\nuser-wide access before adding it:\n\n```sh\ncodex mcp add agent-relay-sessions \\\n  --url https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --bearer-token-env-var AGENT_RELAY_SESSIONS_TOKEN\ncodex mcp list | grep -F agent-relay-sessions\n```\n\nBecause MCPs load at startup, the running session must be **restarted** to pick\nup the server — and because both CLIs read the token from the environment at\nlaunch, the restarted process must **inherit** `AGENT_RELAY_SESSIONS_TOKEN`.\nThat is why the variable belongs in the shell profile / launcher, not a transient\nshell-tool subprocess: an `export` in this agent's shell tool cannot reach the\nparent or a freshly launched session. After the restart, re-verify presence with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"` before using the tools, and do not\nreport the tools as missing without first confirming the session started *after*\nthe MCP was added and with the variable set.\n\n## 4. Confirm the handoff tools loaded\n\nIn the session that started after the MCP was added, confirm the tools are\npresent before using them. List this session's MCP tools and check for the\nagent-sessions set; the authoritative check is that the tools actually appear to\nthis agent:\n\n```sh\n# Claude Code: the tools surface as mcp__agent-relay-sessions__*\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nThen call `list_relay_agents` through the MCP (an MCP tool call, not a shell\ncommand). A successful call that returns the workspace roster proves the MCP is\nloaded, the token is valid, and this session can see the shared workspace. If\nthe call errors with auth, the token is wrong or for another workspace — have\nthe person re-mint it from the correct workspace's dashboard.\n\n## 5. Prove one live round trip\n\nThe real proof is agent-to-agent, so it needs a counterpart. Pick the path that\nmatches what is available:\n\n**A teammate's agent is online (full round trip).** Ask the person for the\nteammate's relay address (e.g. `@manav`), then:\n\n1. `list_relay_agents` — confirm the teammate's address is listed.\n2. **Prove the reverse read path first:** call `get_shared_session_context` on\n   the teammate's session and confirm it returns their **real** content (prompts/\n   events + a dashboard citation link). If it errors or is empty, their uploader\n   is unhealthy — stop and have them fix it; do not declare GREEN, because this\n   side cannot actually read their work yet.\n3. `send_relay_message` — send a short, uniquely-marked message to that address.\n4. The teammate's agent reads this session with `get_shared_session_context` and\n   continues; have them reply through the relay.\n5. GREEN requires **both directions**: this agent read the teammate's real\n   content (step 2) **and** the teammate's reply lands here. There is no\n   automatic ack — confirm by the reply/activity, not a push. Because Relay\n   injects an inbound message only when the session is idle between turns, **end\n   the turn** after sending and confirm the reply on the next turn; do not sleep\n   or poll inside one turn.\n\n**No teammate online yet (self-verify the read path).** Prove the machinery\nwithout a second person:\n\n1. `list_relay_agents` returns the roster — MCP + token + workspace are good.\n2. `search_shared_sessions` / `get_shared_session_context` return this person's\n   **own** recently uploaded session (real prompts/events plus a dashboard\n   citation link) — the uploader→read path works.\n3. Record that the two-party round trip still needs the teammate online, and\n   name it as the remaining step rather than claiming the handoff is proven.\n   Setup is not complete until the full round trip succeeds.\n\nNever paste the Bearer token or any session token into a `send_relay_message`\nbody or any artifact.\n\n## 6. Report\n\nSeparate verified facts from what still needs a human or a second machine:\n\n- app version, `signed_in`, the signed-in **workspace id and name**;\n- uploader `healthy`, this session's `agent@machine` address, direct delivery on;\n- agent-sessions MCP installed and its tools confirmed loaded in this session;\n- `list_relay_agents` roster seen; and either the full round-trip evidence (the\n  teammate's real content + reply) or the self-verified read path plus the named\n  remaining step (teammate online).\n\nDo not call the setup complete on a 2xx from `claude mcp add` alone, and do not\ncount a roster listing as a proven handoff.\n\n## Recovery\n\n- **`not_a_relay_session` from `/setup/*`:** the caller is not inside a discovered\n  interactive session. Run it from this agent's own shell inside an **interactive**\n  Claude Code or Codex session — a non-interactive `codex exec` or `claude -p` run\n  is not admitted, and neither is an unrelated terminal. In tmux/SSH, confirm the\n  agent process and shell share the pane's process tree.\n- **No handoff tools in the session:** the MCP was added after the session\n  started, or at the wrong scope. Reinstall at project scope (section 3) and\n  **restart** the session; MCPs load only at startup.\n- **`list_relay_agents` auth error:** the token is wrong, expired, or from a\n  different workspace. Because the MCP config stores only a **reference** to\n  `AGENT_RELAY_SESSIONS_TOKEN`, fixing it means updating the **value in the\n  launch environment** (keychain / 0600 file) and **restarting** the agent so it\n  re-reads it — re-running `claude mcp add` / `codex mcp add` alone changes\n  nothing. Re-mint from the intended workspace's \"Connect your agent\" card if the\n  token itself is bad. On Claude, also confirm the client is ≥ 2.1.119 (older\n  clients send the `${VAR}` placeholder literally).\n- **Teammate's address missing from the roster:** they are not on the **same**\n  workspace, or their session is not on the relay. Have them register their\n  session and confirm the shared workspace id.\n- **Can't read the teammate's session:** their **uploader** is not healthy\n  (paused or a failed cycle). Have them check `/setup/status` shows\n  `uploader.healthy == true`, not \"Sync paused/offline\".\n- **Message arrives held, not live:** direct delivery is off for the recipient —\n  POST `{\"enabled\":true}` to `/setup/direct-delivery` on their machine (Codex\n  delivers directly by default). A managed Claude policy can block this; report\n  it rather than editing managed settings.\n- **Remove the MCP:** `claude mcp remove agent-relay-sessions` /\n  `codex mcp remove agent-relay-sessions`. This removes only the handoff tools;\n  it does not sign the desktop out or stop uploads.\n\n## Relationship to the other skills\n\n- **`setting-up-agent-relay-desktop`** — the layer below this one: install,\n  sign-in, agent-led defaults, self-registration. Use it when section 2 is not\n  yet satisfied.\n- **`relay-connect`** — a lighter, account-free, time-boxed way for two agents to\n  share one session via a hand-over link. Prefer it for an ad-hoc pairing;\n  prefer this skill for durable teammate-to-teammate handoff inside a shared\n  workspace.\n",
+  "setting-up-agent-relay-flows": "# Set Up Agent Relay Flows\n\nDrive the setup through the documented Cloud APIs and the official CLI. Do not\nuse computer use, browser automation, or the dashboard UI. The human approves\nsign-in, tool consent, and provider logins on their own approval pages; open\nthose links with the OS URL opener (or give them the link), then verify by\npolling the API, never by inspecting the browser.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix; the site is `https://agentrelay.com`. When a\nguide names a different site and Cloud base (for example a local development\nstack), use those exact origins throughout and never fall back to production.\nFlows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.\n\n## Requires\n\nA signed-in Cloud session: an access token and the `user.id` and\n`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`\nfirst, and send `Authorization: Bearer <access_token>` on every request below.\n\n## API map\n\n- Flow catalog: `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.\n- Tool consent links: `POST /api/v1/integrations/connect-link`; poll\n  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.\n- Coding-agent credentials: the official CLI's `cloud connect` (section 3);\n  `GET /api/v1/cloud-agents` inspects existing connections.\n- Activation: `POST /api/v1/flows/deploy` with the body in section 4.\n- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`\n  reports whether it is available.\n- Verification: `GET /api/v1/flows/listeners/<agentId>`.\n\n## 1. Prebuilt or custom?\n\nAsk the human first, unless their request already says: a **prebuilt** flow\nfrom the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**\nflow of their own? In an agent-driven signup, ask through that guide's\nweb-input protocol on the signup page, not in chat.\n\n- Prebuilt: continue with section 2.\n- Custom: follow **Custom flow: deploy journey** below. A custom flow is\n  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and\n  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is\n  no separate custom API.\n\n## 2. Choose the flow and repository\n\nAsk the human for missing product choices: repository, desired\nworkflow/trigger, and approver. In an agent-driven signup, ask through that\nguide's web-input protocol on the signup page, not in chat. Ask for the approver's\nGitHub username in plain language (for example, \"octocat\" or \"@octocat\"),\nnot an internal provider-address format or their Google email. Normalize the\nanswer to github:@handle when constructing the deploy API request. Human-gate\nreplies are matched to that provider identity. Infer choices from the user's request and current\nrepository where clear.\nDo not invent a repository or enable automation on an unrelated project.\n\nGET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.\nGET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's\nkind before doing anything executable: only an entry with kind: flow (or a\nlegacy entry with kind omitted) is deployable through the direct-source API\nbelow. An entry with kind: extension is discoverable metadata, not a standalone\nlistener. Do not download or deploy its source, even when it declares trigger\nand input fields. Inspect baseFlowId and extension.activation instead. If the\nextension is blocked, report the unmet dependencies and that it can only be\nadded to its base flow after a supported extension activation path is available;\nnever substitute a standalone flow deployment.\n\nFor a deployable flow, use the catalog's\nsupportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and\ninputs.allowedAgents. Name a model per harness in inputs.models when the house\ndefault is wrong (for example {\"claude\": \"claude-sonnet-4\"}); omit it to fund\nthe house default for each declared agent. Download source.rawUrl, verify its bytes against\nsource.sha256, and use that source text unchanged for a recommended flow.\nThe source is TypeScript, not the source URL. Do not guess a template or hash.\n\n## Custom flow: deploy journey\n\nThere is no journey API. A `journey_id` (for example in a\n`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it\nthrough unchanged where you received it, and never call an endpoint with it or\nwait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`\nas a prebuilt one; only where the source comes from differs.\n\n1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,\n   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that\n   skill for the flow's shape and checks; Flows are always v2. Cloud's\n   prompt generator is an optional shortcut: use it only when\n   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it\n   reports unavailable, refuses your session (403 `session_required`), or\n   fails, author with `writing-relayflows` instead; do not retry into it.\n2. Choose its repository, trigger and approver as in section 2.\n3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the\n   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent\n   only when the prompt generator produced one. `base` and `extensions` are\n   optional and only for a flow that names them.\n\nThe human-only steps are the same for both paths: Google sign-in and device\napproval, GitHub and trigger-app OAuth including the repository grants,\nmodel-provider login, and confirming the repository and trigger before\nactivation. Do every other step yourself through the APIs.\n\n## 3. Connect the required tools and coding agents\n\nUse bearer-authenticated POST /api/v1/integrations/connect-link:\n\n```json\n{\"provider\":\"github\",\"workspaceId\":\"<currentWorkspace.id>\"}\n```\n\nOpen the returned connectUrl for the user to approve. Keep token/sessionToken\nprivate. Connect only the repository and tools the chosen flow requires.\nFor GitHub the user must grant repository access. Repeat with the chosen trigger\nprovider if different. Reuse existing ready connections rather than relinking.\nCheck GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status\nuntil oauth.connected is true (poll with backoff and a bounded timeout); a\nreturned connect link or a closed popup alone does not prove the connection.\nFor the GitHub-triggered Software Garden flow, activation separately checks\nthat the connected GitHub App covers the selected repository. Its trigger\ndoes not require background data indexing, so do not block solely because\nthe broader status.ready is false from queued syncs.\nIf a different flow declares Relayfile data that requires synced records,\nverify that readiness separately before activating it.\n\nDo not connect a Claude or Codex subscription yet. The first three runs use\nCloud's own model key, so no provider login is needed to activate. If the chosen\nflow declares more than one coding agent in inputs.agents, included Cloud runs\ncan fund only one of them per run — connect your own subscription for at least\none declared agent before activating a multi-agent flow. After the included\nruns, activation and launches will ask for your own subscription; only then use\nthe official Relay CLI with the private credential environment from\n`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:\n\nThis promotion depends on Cloud's internal house-key proxy and account\nenrollment. If local activation returns flow_credentials_unavailable or\nflow_model_not_connected before the three promotional runs, treat it as an\ninternal configuration or eligibility issue. Do not ask the user to connect\nClaude/Codex, provide an API key, or choose an inactive draft as a workaround.\nReport the blocker (in a signup, through its Progress API) and have an internal developer\nverify the proxy, promotion flag, provider readiness, and enrollment. Never\ncopy a house key into the agent environment or expose it in this guide.\n\n```sh\nnpx --yes agent-relay@latest cloud connect anthropic --api-url 'https://agentrelay.com/cloud'\n```\n\nUse anthropic for Claude or openai for Codex, according to the selected flow.\nThe command drives provider login; open its authorization URL for the user,\nand keep the process alive until it confirms the credential is connected.\nGoogle approval does not grant GitHub or model-provider access: those services\nmay require their own consent. Never fabricate credentials or claim consent\nhappened. GET /api/v1/cloud-agents lets you inspect the account's credential\nstate without reconnecting.\n\n## 4. Activate through the same API as web onboarding\n\nPOST /api/v1/flows/deploy with Content-Type: application/json and the bearer\nsession. The token must be the device-flow session from\n`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with\n`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the\nbrowser onboarding handoff: source is TypeScript text, repository is singular,\nand sources contains provider/settings objects. The catalog supplies the source\nreference and defaults; it is not itself a deploy request. The current endpoint\ndoes not accept a flowId/repositories-only catalog activation request or fetch\nthe source for you. For multiple repositories, submit one deployment per\nrepository with a distinct name and handoffId.\n\nFor the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the\nworkspace, verified source, repository, GitHub approver and a new UUID:\n\n```json\n{\n  \"workspaceId\": \"<currentWorkspace.id>\",\n  \"name\": \"Software Garden\",\n  \"workflow\": \"software-factory\",\n  \"source\": \"<verified TypeScript source text>\",\n  \"handoffId\": \"<one UUID generated for this setup>\",\n  \"inputs\": {\"approver\": \"github:@octocat\", \"agents\": [\"claude\"]},\n  \"mode\": \"activate\",\n  \"repository\": {\"owner\": \"acme\", \"name\": \"api\"},\n  \"sources\": [{\"provider\": \"github\", \"settings\": {\"repository\": \"acme/api\"}}]\n}\n```\n\nFor another deployable kind: flow catalog entry use its id as workflow, allowed agents, and\ndefaultTrigger for sources, then apply the user's trigger settings. Scope a\nGitHub issue trigger with settings.repository set to the chosen owner/name;\nfor GitLab use settings.project. Cloud does not derive this filter from the\ndeployment repository. An empty filter can trigger on other repositories in\nthe workspace. Only use a different trigger scope when explicitly requested.\nGive each repository its own trigger filter for multi-repository setup. Do not send\nthe example acme repository or octocat approver unchanged. The workflow field\nis a label, not a source lookup; keep the verified source in the request.\nFor GitLab set repository.host to gitlab and use the namespace path\nas owner. Reuse the handoffId on retry. Before retrying an ambiguous network\nfailure, GET /api/v1/flows/listeners and check whether the flow already exists;\ndo not create a new ID/name on every retry. Activation subscribes to matching\nfuture events and can run work; confirm the intended repository and trigger\nwith the user if they have not specified them.\n\nHTTP 201 must contain agentId and status: listening. A draft is not completion.\nFor a 409 workspace_mismatch, verify the active workspace; for connection\npreflight failures, fix the indicated connection before retrying. If the user\nwants to save incomplete work, use mode: draft explicitly and report that it\nis inactive. Never mask activation failures by silently falling back to draft.\n\n## 5. Verify\n\nGET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and\nverify its repository and sources match the request. Open\nhttps://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,\nworkspace, repository, trigger, and verified listening state. This proves\nactivation; only an actual completed run proves execution. Do not create a\nreal issue or launch paid work merely to make the onboarding check turn green.\nDelete temporary authentication files after the work is complete.\n\nThe desktop app is optional for Flows. If the user also wants local session\nsharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`\nwith the same account (an agent-driven signup can follow\nhttps://agentrelay.com/signup/agent/teams).\n",
+  "writing-relayflows": "# Writing Relayflows\n\n## Overview\n\nRelayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real — a journal write that fails fails the step, with no silent fallback.\n\n**Name collision warning.** This repo also has skills for an older, unrelated engine that is *also* casually called \"Relayflow\" (singular) — `@relayflows/core`'s `WorkflowBuilder`, a chained builder (`workflow('name').pattern('dag').agent(...).step(...).run()`). That's `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`'s territory. This skill is the **v2** engine: `@relayflows/surface`'s `flow()` function and the YAML/JSON dialect compiled by `@relayflows/sdk`. If you see `.pattern(`, `.agent(` as a chained builder call, or `ctx.workflow.run()`, you're in the other engine — stop and use one of those skills instead.\n\n## When to use this skill\n\n- Writing a new `.flow.ts` or `.flow.yaml`/`.flow.json` for the `flows` CLI (package `@relayflows/sdk`, binary name `flows`).\n- Deciding whether a step needs `run` (shell), `llm` (bare model call), or `agent` (harnessed coding agent in a workspace).\n- Choosing a verification gate that will actually run — a wrong choice here compiles fine and fails at `flows run` time, not authoring time.\n- Wiring up `cli`/`model` for an `agent` or `llm` step, in either language.\n- Debugging a `REFUSED [...]` message from `flows check` or `flows run`.\n- Deciding between running a flow locally, deploying it to listen for tickets, or scheduling it on a cron.\n\n## The ladder\n\nThree step verbs, one per rung (`@relayflows/sdk`'s `StepType = 'deterministic' | 'llm' | 'agent'`):\n\n1. **`run` / `deterministic`** — a shell command. No model. Implicit gate is `exit_code == 0`.\n2. **`llm` / `llm`** — a bare model call. Prompt in, verified output out. No workspace, no tool use.\n3. **`agent` / `agent`** — a harnessed coding agent in a workspace. Returns `{ summary, artifacts }`, not raw text.\n\nPlus resident verbs that aren't ladder rungs: `human` (durable approval), `dispatch` (a direct child flow declared in `use`), and `done` (typed finish). `dispatch` executes in `2.0.35` and newer; see **Human approval and direct child flows**. The generated **helper** namespace (`f.slack`, `f.github`, `f.linear`, `f.notion`, `f.jira`, and 30+ others — see **Helpers**) and YAML `on`/triggers are separate surfaces.\n\nMost flows only need `run` and `llm`. Climb to `agent` once a step needs hands on a real workspace.\n\n## Two ways to author the same thing\n\n**YAML/JSON** is data: `flows check` or CI can validate it without running anything. **TypeScript** calls the same primitives imperatively as ordinary async code. Both compile to the same journal.\n\n### TypeScript\n\n```ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('hello', { budget: { wallclock: '10m' } }, async (f) => {\n  const greeting = await f.run('echo \"Hello from Relayflows\"');\n  console.log(greeting.trim());\n\n  const answer = await f.agent('greeter', {\n    task: 'Reply with one short hello sentence. Do not use tools or modify files.',\n    cli: 'claude',\n    model: 'claude-sonnet-4-6',\n  });\n  console.log(answer.summary);\n\n  f.done('success');\n});\n```\n\n### YAML\n\n```yaml\nversion: '0.1.0'\nname: hello\nsteps:\n  - id: greeting\n    type: deterministic\n    command: 'echo \"Hello from Relayflows\"'\n  - id: greeter\n    type: agent\n    dependsOn: [greeting]\n    instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'\n    cli: claude\n    model: claude-sonnet-4-6\n```\n\n**Version note.** The contracts below were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations. Direct `use`/`f.dispatch` composition requires `2.0.35` or newer. `AgentOptions.permissions` landed in `2.0.17`; predicate `.gate()` and `artifact_exists` landed with [flows#449](https://github.com/AgentWorkforce/flows/pull/449); `f.human` was already executable in `2.0.22`.\n\n## The real `Ctx` contract (TypeScript)\n\nFrom the shipped `@relayflows/surface@2.0.35` `.d.ts` files (`dist/context.d.ts`, `dist/step.d.ts`, `dist/flow.d.ts`, `dist/completion.d.ts`):\n\n```ts\nexport interface AgentResult {\n  summary: string;\n  artifacts: string[];\n}\n\nexport interface PermissionsSpec {     // exported from the package root\n  fileGlobs?: string[];\n  networkAllowlist?: string[];\n  accessPreset?: 'readonly' | 'readwrite';\n}\n\nexport interface AgentOptions {\n  task: string;\n  workspace?: string;\n  permissions?: PermissionsSpec;         // since 2.0.17 — declared and journaled, NOT enforced\n  cli?: string;\n  model?: string;\n  cwd?: string;                          // working dir for the CLI subprocess; defaults to the flow-runner's cwd\n  transport?: 'direct' | 'relay';        // see Agent-relay transport, below\n}\n\nexport interface LlmOptions {\n  output: Record<string, unknown>;       // JSON Schema, checked before the journal accepts the result\n  cli?: string;\n  model?: string;\n}\n\nexport interface DispatchResult {\n  name: string;\n  completionReason: 'success';\n  completionDetail?: string;\n}\n\nexport interface Ctx extends Helpers {   // Helpers = f.slack, f.github, f.linear, f.notion, ... — see Helpers\n  readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;\n  run(command: string, options?: { timeout?: string | number }): Step<string>;\n  llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;\n  llm(prompt: string, options: LlmOptions): Step<unknown>;\n  agent(name: string, options: AgentOptions): Step<AgentResult>;\n  human(question: string, options: { to: string }): Step<boolean>;\n  dispatch(flow: string, input: unknown): Step<DispatchResult>;\n  done(reason: FlowCompletionReason): void;\n  cloud: CloudHelper;\n  memory: MemoryHelper;\n}\n```\n\nDo not add fields to `AgentOptions`/`Ctx` that aren't in this list — they don't exist in the shipped SDK. In particular: **no flow-level named-agent selector on `f.agent`, no `recoveryMode`/`surfaces`/`output`** on the TypeScript call site. Those stay YAML/JSON step fields. `FlowHeader` (`dist/flow.d.ts`) allows `use`, `identity`, `memory`, `budget`, `tools`, `workspace` — no bare `agents` map key (TypeScript composes reusable flows via `use: string[]` instead — see **Named agents and flow composition**). An unknown *header* field throws a `TypeError` at authoring time, before anything is journaled; an unknown `AgentOptions` field is caught by `tsc`, not at runtime.\n\n**`permissions` is a real TypeScript option and it does not sandbox anything.** Since `2.0.17` it is on `AgentOptions`, validated by the SDK, lowered to `file_globs`/`network_allowlist`/`access_preset` and journaled with the step — and nothing reads it to gate a file or a network call. `flows check` warns `permissions_unenforced` on any declaration, including `{}`. Enforcement is [flows#442](https://github.com/AgentWorkforce/flows/issues/442). Declare it to record intent; do not rely on it to contain an agent.\n\n`run()`'s second argument is a real, current option: `{ timeout?: string | number }` — a duration string (`\"15m\"`) or milliseconds. Every real cookbook example that runs something slower than a few seconds sets this explicitly.\n\n### `f.done()`'s closed set is six values, not four\n\n```ts\nexport const FLOW_COMPLETION_REASONS = ['success', 'step_failed', 'canceled', 'budget_exceeded', 'needs_human', 'declined'] as const;\n```\n\nAn authored body can meaningfully call `f.done('success')`, `f.done('step_failed')`, `f.done('needs_human')` (parks the run — it's not a kernel cancellation), or `f.done('declined')` (a deliberate decision not to act — also not a cancellation). `'canceled'` and `'budget_exceeded'` exist in the same closed set but are the **kernel's** to record; a body calling them itself is calling the wrong verdict for what actually happened. The verdict for a human declining a durable approval is `f.done('declined')`, not `f.done('canceled')` — a human declining is a decision, not the kernel calling off the run.\n\n`Step<T>` (`dist/step.d.ts`) is a `PromiseLike<T>` with one extra method, `.gate(...)` — see **Verification gates**. Every awaited step must actually be awaited — an unawaited or manually-`.then()`-chained step is refused (`unawaited_step` / a manual `.then()` is not an await), not silently dropped.\n\n## Verification gates\n\nVerification is control flow, not decoration — a gate decides whether a step actually completed, not just whether the process exited cleanly.\n\n### YAML/JSON (`@relayflows/sdk`'s `VerificationSpec`)\n\n```ts\nexport type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate | NamedDataGate;\n// NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate\n//              | ArtifactExistsGate\n```\n\n- `exit_code` — implicit default for `deterministic` steps. Not configurable; writing it explicitly is allowed and compiles to the same thing as omitting it.\n- `output_contains` — step output (stdout tail, or the LLM value stringified) contains `value`.\n- `json_schema` — step output validates against a JSON Schema (`boolean | Record<string, unknown>`). Used for structured LLM/agent output; `output?: JsonOutputSchema` on an `llm`/`agent` step is sugar that compiles to this.\n- `subprocess_gate` — runs `command` under `/bin/sh`, judged on its exit code. The gate that actually works for \"check a file the agent wrote\": `{ type: 'subprocess_gate', command: 'test -s review.md' }`. If you also need to inspect the step's own output (via `from_output`), the SDK's generated wrapper reads its internal `FLOWS_INPUT` env var, extracts the value, and passes it to *your* command as `$INPUT` — `FLOWS_INPUT` itself is never visible to the author's command, only `$INPUT` is: `{ type: 'subprocess_gate', command: 'echo \"$INPUT\" | grep -q PASSED', from_output: ['summary'] }`.\n- `regex_match` — the step's output (or a value at `in_output_at`) matches `pattern`, evaluated by a non-backtracking RE2 engine (only `i`, `m`, `s` flags).\n- `artifact_exists` — passes when the step's journaled `artifacts` list contains `path` (working-directory-relative POSIX). It reads the journal, not the disk, so it sees exactly what the worker measured at `step.completed`; a path the worker never journaled reads as missing even when the file is there.\n- `word_count_bounds`, `references_input` — narrower named gates; see `packages/sdk/src/named-gates.ts` in the flows repo for the exact contract.\n\n```yaml\n- id: classify\n  type: llm\n  prompt: 'Classify this ticket as bug, feature, or question: \"the export button does nothing\"'\n  cli: claude\n  model: claude-sonnet-4-6\n  verification:\n    type: output_contains\n    value: bug\n```\n\n### TypeScript (`Step<T>.gate(...)`) — read this before you write one\n\n`Step<T>` has **two** overloads, and **one `.gate()` per step** — a second throws `unsupported_gate`:\n\n```ts\ngate(config: NamedGate): Step<T>;\n// NamedGate = ReferencesInputNamedGate | SubprocessNamedGate | WordCountBoundsNamedGate\n//           | RegexMatchNamedGate | ArtifactExistsNamedGate\n// — the surface-visible subset of NamedDataGate above. Data, not code: `flows check` can prove it.\n\ngate(predicate: (value: T) => boolean, because?: string): Step<T>;\n// Runs since flows#449. The executor calls the closure once, on the journaled value, and\n// journals the VERDICT as a lowered `<step>.gate` step — so resume and replay read the\n// recorded verdict and never re-run the function. A false verdict fails the run as\n// `gate_failed`, carrying `because`.\n```\n\nThe predicate form was refused with `unsupported_gate` through `2.0.16`; on `2.0.22` it runs. **Prefer the config-object form anyway** — `flows check` cannot prove a predicate (docs/SURFACE.md §6), so a named gate is the only kind a preflight can tell you about before you spend a run:\n\n```ts\nconst outdated = await f.run('npm outdated --json 2>/dev/null || true')\n  .gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\"' });   // provable by `flows check`\n\nconst review = await f.agent('review', { task: '…', cli: 'claude' })\n  .gate({ type: 'subprocess_gate', command: 'test -s review.md' });  // checks a file the agent wrote, ignores $INPUT\n```\n\n(Verified for real: `.gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\" && echo \"$INPUT\" | grep -q pkg' })` against a step outputting `{\"pkg\":\"left-pad\"}` passes — `$INPUT`, not `$FLOWS_INPUT`, is what the author's command sees. `FLOWS_INPUT` is an env var the SDK's own generated wrapper reads internally to extract the value before invoking your command; it is never visible to `command` itself.)\n\nAn agent step rarely fails by crashing; it fails by returning something plausible and wrong, which a plain retry-on-error never catches. Validate every `agent`/`llm` result, either directly with a supported gate or in a following deterministic verifier.\n\n**Where to put that check depends on what you want a red result to do.** A config-object or predicate gate directly on the agent/LLM step ends the run when it fails; use it when that failure should be terminal. For repairable failures, the following deterministic verifier must explicitly read the preceding output or workspace, produce its own verification result, and record it for repair. Output-dependent gates inspect the step they guard: moving the same gate unchanged would inspect the verifier's output, not the agent's. Use the record/repair/re-record/assert pattern in `relay-80-100-workflow`, gating the final verification result after repair.\n\n## Helpers: journaled effects, not just Slack\n\n`Ctx extends Helpers`, and `Helpers` is generated from 40+ provider adapters shipped in `@relayflows/surface` — `slack`, `github`, `linear`, `jira`, `notion`, `salesforce`, `postgres`, `s3`, `redis`, `daytona`, `gmail`, `google-calendar`, `hubspot`, and more (`dist/helpers/index.d.ts` lists them all). A helper call — `f.slack.post(channel, text)`, `f.github.comment(...)` — compiles to a journaled effect: the receipt the helper returns *is* the journal record, so a retried step that already posted doesn't double-post; the second attempt is deduped by `(step_id, idempotency_key, surface_path)`.\n\nTwo things every helper call needs:\n\n- **A relayfile mount for that provider**, locally — `flows check` refuses `helper_slack.credential_missing` (or the equivalent for another provider) without one. Cloud provides a mount for every connected provider automatically.\n- **A declared intent** on the flow header: `tools: { slack: true }` in TypeScript, or the equivalent in YAML. Forgetting this is a separate, earlier failure than the mount check.\n\nFor local development without standing up a real provider mount, prefix the run with the provider's mock env var — `RELAYFLOWS_SLACK_MOCK=1 flows run ... --local-agent` records the effect (a real file under the daemon's data dir) instead of sending it. This does not exercise live delivery, and should be called out as such wherever you cite it as verification.\n\n**`tools` means two different things depending on where you write it — do not confuse them:**\n\n- `FlowHeader.tools` (TypeScript) / `FlowSpec` top-level `tools` you're declaring intent on: `Partial<Record<keyof Helpers, boolean>> & { relayfile?: string[]; mcp?: string[] }` — e.g. `{ slack: true }`. This is \"which helpers this flow uses.\"\n- `FlowSpec.tools` in the compiled YAML/JSON spec is instead `{ fs?: string | string[] }` — path-scoped **filesystem** grants, mirroring `workspace` for shell/deterministic steps. Not the same field, despite the identical name.\n- `flows.json` (the project config file) has **no** `tools` field at all — see **`flows.json`**, below. Putting a `tools` key there is refused as `config_invalid`; this is an easy, first-try mistake (made once, personally, writing this refresh).\n\n## `cli` / `model`: what a step actually runs on\n\nBoth YAML and TypeScript agent/llm steps can set `cli` and `model` directly. Resolution order for `cli`, identical regardless of authoring language because both compile to the same `StepSpec`:\n\n1. **step** — `step.cli` (or TS's `options.cli`)\n2. **named** — the flow's `agents[step.agent]` entry, if the step selects one via `agent: <name>` (YAML/JSON only — TypeScript composes reusable flows via `use:` instead, not a per-step named-agent selector; see **Named agents and flow composition**)\n3. **flow** — `FlowSpec.cli` (YAML) — there is no equivalent flow-level `cli` field on the TypeScript `FlowHeader`\n4. **project** — nearest `flows.json`'s `cli`, found by walking up from the flow file's directory\n\nNo resolution found at any level → `REFUSED [cli_unresolved]`, before anything is journaled, e.g.:\n\n```\n$ flows check hello.flow.yaml   # agent step, no cli anywhere\nREFUSED [cli_unresolved] Step \"greeter\" has no CLI at step, flow, or project level. No flows.json was found from \"...\" to the filesystem root.\n```\n\n`model` has **no** flow or project default — only step or named-agent. Omitting it just runs whatever model the resolved CLI defaults to.\n\n### `flows.json`\n\nNearest-wins project config, walking from the flow file's directory to the filesystem root. The shipped SDK type (`@relayflows/sdk`'s `FlowsJson`) is exactly:\n\n```ts\ninterface FlowsJson {\n  cli?: string;\n  executors?: string[];\n  models?: string[];\n  mcp?: Record<string, McpServerConfig>;\n  deploy?: { bucket: string };\n}\n```\n\n- `cli` — the project-wide CLI default (resolution rung 4 above).\n- `executors` — trigger executors this project has registered. A trigger whose `executor` isn't in this list is `no_executor`; a flow that declares `.on(...)` triggers but is invoked directly (not via a webhook) still needs its provider named here — e.g. `{ \"executors\": [\"github\"] }` for a flow with `.on(github.pull_request(...))` handlers, even when you never hit that code path.\n- `models` — **an allowlist, not a default.** Any model declared on any step or named agent anywhere in the flow must appear here, or `flows check`/`flows run` refuses `model_unknown` / `llm_cli_unresolved`. Setting `models` does not select a model for anything.\n- `mcp` — project-owned MCP server connections.\n- `deploy` — a file-bucket target for `flows deploy <flow>@sha256:<digest> --to <bucket-uri>`.\n\n**Verified for real:**\n\n```\n$ flows run hello.flow.ts --local-agent --input '{}'   # step declares model \"claude-opus-5\", flows.json has no models[]\nREFUSED [invalid_spec] llm_cli_unresolved: Step \"llm-1\" declares model \"claude-opus-5\" for CLI \"claude\",\nbut it is not listed in project model registry \"…/flows.json\"; add the exact model only after verifying\nthat project is allowed to use it.\n\n$ flows run pr-reviewer.flow.ts --local-agent --input '{...}'   # flow declares .on(github....) handlers, no executors[]\nREFUSED [no_executor] webhook trigger \"github\" is not registered in flows.json\n```\n\nAny other top-level key — `tools`, `budget`, `identity`, `agents` — is refused as `config_invalid`. Those are `FlowHeader`/`FlowSpec` fields on the *flow itself*, not on the project config.\n\n## Named agents and flow composition\n\n**YAML/JSON**: a named-agent map declares each `{ cli, model }` pair once; a step's `agent:` selector resolves to it at compile time, and `flows check` flags a named agent nobody selects, or one a step overrides without using.\n\n```yaml\nagents:\n  planner: { cli: claude, model: claude-opus-5 }\n  implementer: { cli: codex, model: gpt-5.6-codex }\nsteps:\n  - id: plan\n    type: agent\n    agent: planner\n    instruction: '…'\n```\n\n**TypeScript** has no equivalent `agents:` map key on `FlowHeader` — the closest idiom is a plain object spread reused across calls:\n\n```ts\nconst planner = { cli: 'claude', model: 'claude-opus-5' };\nawait f.agent('plan', { ...planner, task: '…' });\n```\n\nWhat TypeScript *does* have is `FlowHeader.use?: string[]`: relative `.flow.ts` paths to direct child flows the body may call with `f.dispatch`. This is composition of complete flows, not a named-agent map. It executes in `2.0.35` and newer; see **Human approval and direct child flows**.\n\n## Parallel agents\n\nRunning several agent (or any) steps concurrently is first-class, documented authoring — not a workaround:\n\n> \"…`Promise.resolve`, `Promise.all`, `Promise.allSettled`, `Promise.any` and `Promise.race` over authored steps\" are \"ordinary, supported authoring.\" — `docs/SURFACE.md`, the authored operation lifecycle\n\n```ts\nconst LENSES = ['security', 'correctness', 'performance'] as const;\n\nawait Promise.all(\n  LENSES.map((lens) =>\n    f.agent(`${lens}-reviewer`, {\n      task: `Review this diff for ${lens} issues ONLY. Write findings to review/${lens}.json.`,\n      cli: 'claude',\n    }).gate({ type: 'subprocess_gate', command: `test -s review/${lens}.json` }),\n  ),\n);\n\nconst consensus = await f.agent('consensus', {\n  task: 'Read review/*.json. Resolve disagreement between lenses. Write review/consensus.json.',\n}).gate({ type: 'subprocess_gate', command: 'test -s review/consensus.json' });\n```\n\nThis is the exact shape `examples/pr-review-pipeline` in `AgentWorkforce/flows` (and the cookbook's would-be equivalent) uses: fan out, each lane writes its own file, a reconciliation step reads them all. **Disclosure worth knowing before you rely on it**: the flows package replaces the global `Promise.all` intrinsic, process-wide, for the lifetime of any authored flow execution, so the kernel can prove every concurrent step was actually awaited (rather than inferring group membership from callback identity). It delegates to the real intrinsic and restores it when the last concurrent flow closes — but any other code sharing that process sees the replacement during that window.\n\n## Agent-relay transport: dispatch, not live chat\n\n`AgentOptions.transport?: 'direct' | 'relay'` (default `'direct'`, a local subprocess). Setting `transport: 'relay'` dispatches the step to Agent Relay's own task infrastructure instead — per the shipped type's own doc comment: *\"posts to agent-relay so the agent registers as a first-class workspace participant that DMs can steer.\"*\n\nWhat this actually is, per `docs/AGENT-RELAY-TRANSPORT.md`: the step calls `POST /v1/actions/task.run/invoke` against relaycast, then waits for a durable final receipt — spawn readiness and invocation acceptance do **not** complete the step, only a terminal receipt does. It needs a pre-provisioned `RELAY_AGENT_TOKEN` (a workspace API key cannot substitute) and the Relay provider running with `AGENT_RELAY_TASK_PROVIDER=1`. The dispatched worker submits its result via an injected `agent_result` tool.\n\nDon't describe this as \"agents talking to each other\" — there's no documented pattern in this skill's scope for two flow steps to hold a live back-and-forth over Relay channels while both are running. What's real: the step's agent becomes a genuine Agent Relay workspace participant while it runs (so a human, or another agent with the right access, can DM it and potentially steer it — per the type's own wording), and the flow still only sees a request-and-durable-receipt shape, not an open channel. Multi-agent *coordination* inside a flow today means sequential handoff (one step's return value feeds the next) or parallel fan-out (**Parallel agents**, above) — not live messaging.\n\n## Human approval and direct child flows\n\n`f.human` parks a root run on a durable approval. `f.dispatch` executes a statically declared direct child in the same durable tree on `2.0.35` and newer. Both must be awaited.\n\n`f.human` parks the run durably on a kernel `wait.human`, keyed `human-<n>` in the order the body asked. A person answers, and `flows resume` continues the body from that line:\n\n```ts\nconst ok = await f.human(`Ship this?\\n${plan.summary}`, { to: 'khaliq' });\nif (!ok) return f.done('declined');   // a person's \"no\" is declined, never canceled\n```\n\n```\n$ flows answer <run-id> human-1 yes --by khaliq --note 'reviewed the diff'\n$ flows resume <run-id>\n```\n\n`to` names who is asked and is recorded with the question — **it is not a delivery address**; nothing notifies that person for you. The kernel closes a wait once, so the first answer wins, and it records `attribution: \"client_asserted\"` because the daemon socket, not the kernel, authenticated whoever `--by` names. The answer step takes a `.gate(config)` like any other step. One caveat: `f.human` needs a durable root run to park in — under a runner that has none it refuses with `unsupported_verb`, so run it with `flows run`.\n\nFor a composed local run, declare each direct child in the parent's static `use` header, then dispatch by the child's declared `flow(...)` name—not by its file path:\n\n```ts\n// release.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('release', { use: ['./implement.flow.ts'] }, async (f) => {\n  await f.run(\"printf '%s' prepare\");\n  const child = await f.dispatch('implement', { issue: 123 });\n  await f.run(\"printf '%s' publish\");\n  f.done(child.completionReason);\n});\n```\n\n```ts\n// implement.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('implement', async (f, input: { issue: number }) => {\n  await f.run(`printf '%s' ${input.issue}`);\n  f.done('success');\n});\n```\n\n`use` resolves relative `.flow.ts` files before a body runs. Missing or repeated files, duplicate direct-child names, cycles, and undeclared or transitive-only dispatch targets are refused. The child's steps receive qualified IDs such as `dispatch-2--run-1`; the dispatch receipt joins child leaves back to the parent's next step. Parent and child share one root budget and worker-capacity pool, and resume reuses journaled identities rather than repeating completed effects. A successful dispatch returns `{ name, completionReason: 'success', completionDetail? }`; any other child verdict fails the dispatch.\n\nAuthority narrows: a child cannot declare a second budget, require a helper/MCP capability its parent did not grant, or call `f.human`. Static cycles are refused and runtime child depth is capped at three. This is direct authored composition, not arbitrary public-flow invocation.\n\nTo put the **whole local tree** on one Cloud dashboard page, run `flows run --cloud-mirror release.flow.ts --input '{}'` (or affirmatively set `FLOWS_CLOUD_MIRROR=1`). The root, qualified child steps, dispatch receipts, dependency edges, transcripts, source, and output are projected into one connected graph; the local journal remains authoritative. Mirroring uploads that data and is opt-in. A mirror failure cannot fail the local run. The default observer link is separate and does not add the run to Cloud history.\n\nDo not confuse this with **hosted execution**. `flows run --cloud [--sync-code] release.flow.ts --input '{}'` still rejects `use` dependencies with `unsupported_source`: Cloud accepts one self-contained `.flow.ts` source. Use `--cloud-mirror` for the connected child-flow dashboard today; do not promise that Cloud can itself execute a multi-file `use` tree.\n\n**The same \"types accept it, the executor doesn't\" trap applies to `workspace` on an agent step under `--local-agent`.** Neither an annotated (`'acme/api: readonly'`) nor a bare (`'acme/api'`) value works — both fail identically:\n\n```\nREFUSED [invalid_spec] unsupported_workspace_permission: The local agent worker accepts\nstream-only steps. Remove workspace or attach a worker that holds its revision pins.\n```\n\nIt isn't the `: readonly`/`: readwrite` annotation syntax that's rejected — it's that the local-agent worker doesn't hold workspace revision pins at all. Omit `workspace` entirely for a step you intend to run with `--local-agent`; it's a real, working field only against a worker that supports it (Cloud's). Against a worker that does hold pins, the suffix is separately refused, and the remedy the SDK's own message names is `f.agent`'s `permissions` option — which records the scope and does not enforce it.\n\n## Running it: `flows check` / `run` / `deploy` / `schedule`\n\n```\nflows check [--json] [--watch] <flow.ts|flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>\nflows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <run-id>\nflows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]\nflows deployments [--json]\nflows undeploy [--json] <deployment-id>\nflows schedule <flow.ts> --cron \"<expr>\" --tz <tz> --input <inline-json-or-file>\n```\n\n`check` is a pure compile-and-preflight — no daemon, no socket, no data dir. It's the fast, safe way to validate a flow before ever running it, and it does accept `.flow.ts` despite older `--help` text implying only YAML/JSON.\n\n**`--local-agent` is not optional decoration.** Without it, `agent`/`llm` steps have no worker to dispatch to and the run parks indefinitely rather than executing. Every local run in this skill's examples, and every real run in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook), passes it.\n\nA `.flow.ts` run via `flows run` requires `--input <inline-json-or-file>` even when the flow body ignores its input argument.\n\n**`--data-dir` gotcha, learned the hard way.** If a flow does its own git hygiene on the directory you invoke it from — `pr-reviewer`'s and similar examples' `git clean -fdq -e .workforce` when there's nothing to push — that cleanup deletes *anything else untracked in that directory*, including the daemon's own default `.relayflowd/` state if you didn't move it. The symptom is a bizarre `SQLite journal failed: unable to open database file` on the *next* run in the same checkout, because the previous run's own cleanup step deleted the very journal directory the daemon needed. Fix: put the daemon's data outside the checkout:\n\n```bash\nflows run pr-reviewer.flow.ts --local-agent --data-dir /somewhere/outside/the/repo --input '{...}'\n```\n\n**Before `flows deploy` will do anything, two things have to already be true — a correct command still fails without them:**\n\n1. **You (or whoever's driving this) are logged in.** `agent-relay cloud login` once; check with `agent-relay cloud whoami`. There's no separate `flows`-specific login — it shares the `agent-relay` Cloud session.\n2. **The workspace has a GitHub App installation covering `--repo`, and the `--on` provider is actually a connected integration** — not just declared in the command. `flows deploy` looks up the workspace's GitHub installation before it will activate a listener; with none, it refuses `flow_repository_not_connected` rather than deploying a broken one (`prepare-flow-deploy.ts` in `AgentWorkforce/cloud`). Check what's connected with `agent-relay cloud integration connections --workspace <id>` — a provider showing `degraded` instead of `ready` is not deploy-safe, even though the CLI won't tell you that until you try. This is a separate concern from your own local git push access (a personal git/`gh` credential thing, needed only for testing a flow's own `git push`/`gh pr create` steps locally) — don't conflate the two when debugging a refusal.\n\n**`flows deploy`** creates a persistent listener: each matching ticket (`--on github:labels=agent`, `linear:team=ENG`, `jira:project=OPS`, `shortcut:workspace=…`, `slack:channel=#eng`) launches one Cloud run. `flows deployments` lists what's listening; `flows undeploy <id>` stops it — verified for real this session (deployed `software-factory` against a real repo with `--on linear:team=…`, got back `{\"status\":\"listening\", ...}`, then cleanly undeployed).\n\n**`flows schedule`** puts a flow on a cron instead of a ticket trigger — newer (shipped after the `2.0.16` release line) and not yet reflected everywhere in older examples that instead show `flows run --cloud` for the same use case.\n\n**Now fixed, was broken through `2.0.16`** ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), closed): the one-shot `flows run --cloud [--sync-code] <flow.ts> --input <json>` form used to misroute authored TypeScript flows into the declarative-spec loader (`invalid_input: Cannot read or compile the declarative flow`) or refuse with a bare `http_error: HTTP 400`. Root cause: Cloud pinned an older `@relayflows/surface` than the CLI authored against, and refused the version mismatch with those opaque errors instead of naming it. Fixed in `2.0.17` (CLI side) — verified for real: `flows run --cloud --wait <flow.ts> --input '{}'` now submits successfully and returns a real run ID instead of refusing immediately. If you still hit a bare `HTTP 400`/`invalid_input` on this path, you're likely on a CLI older than `2.0.17` — update first before assuming something else is wrong. (Cloud-side reporting of the exact version mismatch, when one still exists, was tracked as a separate follow-up PR at the time of writing — the CLI's own refusal is fixed either way.)\n\n### Watching a local run: observer link vs `--cloud-mirror`\n\nNew in **`2.0.32`**. A local run has two ways to be watched, and they are not the same thing:\n\n- **The observer link is the default.** Every `flows run` mints a read-only `ot_live_` link scoped to that run's own `wf-<runId>` channel and prints `Observer: <url>`. It is free, needs only a workspace key, and carries a step projection. `--no-observer-link` suppresses it.\n- **`--cloud-mirror` additionally puts the run on the Cloud dashboard** — the richer hosted view: the flow source, **every agent step's transcript**, the run graph, the run's own log, and the run sitting in the same history as your hosted ones. `FLOWS_CLOUD_MIRROR=1` turns it on for a whole shell.\n\n```bash\nflows run review.flow.ts --local-agent --input '{}'                  # observer link only\nflows run --cloud-mirror review.flow.ts --local-agent --input '{}'   # ...and the dashboard\n```\n\nThe run prints both, and the dashboard line names Cloud's run id as well as the page:\n\n```\nObserver:  https://agentrelay.com/observer?key=ot_live_...\nDashboard: https://.../dashboard/workflow/<cloud-run-id>/runner  ·  flows status --cloud --watch <cloud-run-id>\n```\n\n**That second id matters and is easy to get wrong.** The report's own `runId` is the *journal's* ULID (`01M3B9...`), while the two hosted verbs that take an id — `flows status --cloud <run-id>` and `flows logs <run-id>` — want Cloud's UUID. Do not pass a journal id to either. Under `--json` both ride in the report as `cloudRunId` and `dashboardUrl`, beside `observerUrl`.\n\n`flows runs` is the odd one out and the way *out* of this problem: it takes no id at all (`flows runs [--limit <n>] [--json]`) and lists the runs the credential can see, newest first, with each one's Cloud UUID — so it is how you find the id the other two want when you no longer have the terminal that printed it.\n\n**Why it is opt-in, not on by default.** Because it is the richer view, it is also the one that *stores* all of that: source, step metadata, agent transcripts, and the CLI's own stderr. Transcripts are whatever the agent printed, including file contents and command output. Everything goes through the same redactor `flows status` uses — but redaction is pattern matching, and pattern matching has a false-negative rate. So the trigger is an explicit request and never the mere presence of a Cloud login. Only an affirmative counts for the env var (`1`/`true`/`on`/`yes`); `0`, empty, and anything nobody meant as a switch all leave the run local.\n\n**What it buys you, concretely:** the three read verbs start answering for *local* runs, which until `2.0.32` only worked for runs Cloud had launched.\n\n```\n$ flows status --cloud <cloud-run-id>\nRUN 27ab5702-...  local-mirror-agent-confirmation  completed  spend 13,088 in / 61 out / $0.01836\n  ✓ ask-claude  agent  1 attempt  3.3s  claude-haiku-4-5-20251001 · 1 turn · $0.01836\n  ✓ ask-codex   agent  1 attempt  7.9s\n$ flows logs <cloud-run-id> --step ask-claude    # that step's transcript, out of Cloud storage\n```\n\nThree behaviours worth knowing before you rely on it:\n\n- **It cannot fail a run.** Every push collapses to a boolean; each poll and the whole finish are bounded. A Cloud outage costs the run its dashboard page and nothing else. If the mirror is refused you get one line naming which switch asked for it, and the run's exit code is untouched.\n- **The dashboard says the run was local.** The row is `dispatchType: \"local\"`, and the run page shows **Ran on: Your machine** instead of a sandbox tile. Cancel is refused for it — Cloud mirrors a local run, it does not control it, so stop it where it is running.\n- **A `--cloud-mirror` resume is a second dashboard row, linked to the first.** Cloud refuses to move a terminal run back to `running` (its own hosted resume mints a fresh id too), so the resumed attempt carries `resumedFromRunId` and the run page links the two — the parked \"Needs review\" row shows what continued it. The mapping lives in `<data-dir>/cloud-runs/`: the Cloud run id and the deployment, no credential, mode 0600, ageing out at 30 days.\n\n**Requires a Cloud login** (`agent-relay cloud login`, or `FLOWS_CLOUD_TOKEN`) — the same credential every other hosted verb uses. Without one, `--cloud-mirror` prints one line saying the run stays local and the run proceeds normally. A local run that joins no workspace is not a defect (RFC-0001 settled decision 7: the journal is the record, the workspace is one view onto it).\n\n### Exit codes and refusal shapes\n\nEvery refusal before a journal write is exit **2**, printed as `REFUSED [<kind>] <message>`. The `<kind>` differs by *how* the flow was checked, not just *what* was wrong:\n\n- `flows check` on a YAML/JSON spec, or the declarative-compiler path in general → the preflight's own kind directly: `cli_unresolved`, `model_unknown`, `cli_missing`, `cli_unauthenticated`, `no_executor`, `config_invalid`, etc.\n- `flows run` on a **TypeScript** `.flow.ts` whose authored `f.agent`/`f.llm` call can't resolve a CLI or model at runtime → wrapped and printed as `REFUSED [invalid_spec] <message>` with the specific reason (`llm_cli_unresolved`, etc.) inside the message text, not as the printed `[kind]` itself.\n\nBoth are real, both are exit 2 — the same underlying problem can print a different `[kind]` depending on whether you hit it via `flows check` on YAML or `flows run` on TypeScript.\n\n## Common mistakes\n\n- **Forgetting `version` in a YAML/JSON `FlowSpec`.** Required, not optional.\n- **Attaching two `.gate()` calls to one step.** `unsupported_gate`: a step takes one. Also note a predicate gate is invisible to `flows check` — prefer a config object when preflight should be able to prove it.\n- **Putting `tools`, `budget`, or any other `FlowHeader` field into `flows.json`.** `flows.json` only accepts `cli`, `executors`, `models`, `mcp`, `deploy` — anything else is `config_invalid`.\n- **Assuming `flows.json`'s `models` sets a default model.** It only validates models already declared elsewhere; it never selects one.\n- **Declaring `.on(...)` trigger handlers without registering the provider in `flows.json`'s `executors`.** Even a flow you only ever run directly (never via a real webhook) needs this, or it's refused `no_executor` before your input is even read.\n- **Calling `f.done('canceled')` for a human's \"no.\"** That's `f.done('declined')` — `canceled` is the kernel's verdict, not an authored body's.\n- **Running an agent/llm-bearing flow without `--local-agent`.** The run parks with nothing attached to do the work.\n- **Letting a git-hygiene flow's cleanup step delete your daemon's own data dir.** Pass `--data-dir` outside the checkout for any flow that runs `git clean`/`git checkout --force` on its own working tree.\n- **Not awaiting a step, or manually `.then()`-chaining one.** Refused (`unawaited_step`) rather than silently ignored.\n- **Running a `.flow.ts` without `--input`.** Required even for flows that don't use their input argument.\n- **Assuming `flows run --cloud` for a one-shot TypeScript flow run is still broken.** It was through `2.0.16` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), now closed) — fixed in `2.0.17`. If you're on an older CLI, update rather than reach for a workaround; `flows deploy` remains the right choice for a persistent listener regardless.\n\n## What this skill does NOT cover\n\n- **Triggers/webhooks** (`.on(github.pull_request(...), ...)`), **memory retrieval**, and the full **helper** catalog's per-provider quirks (`f.mcp`, provider-specific settings) — each is its own surface; see the [Relayflows product docs](https://agentrelay.com/docs/relayflows) and the [flows-cookbook](https://github.com/AgentWorkforce/flows-cookbook) for real, run-verified examples of each.\n- **Named-agent map equivalent in TypeScript beyond `use:`** — `use` composes complete child flows, not named agent configurations.\n- **YAML-only agent step fields with no TypeScript equivalent**: `recoveryMode`, `surfaces`, `output`, the `agent:` named-agent selector, and enforced `workspace` (TypeScript's `workspace` string is accepted by the type but rejected by the local-agent worker — see **Human approval and direct child flows**). `permissions` is **not** on this list — it is a TypeScript option too (see **The real `Ctx` contract**).\n- **Hosted multi-file child-flow execution** — `flows run --cloud` refuses `use` dependencies even with `--sync-code`; `--cloud-mirror` is the supported route for a local child-flow tree on the Cloud dashboard.\n- The **older `@relayflows/core` `WorkflowBuilder`** engine — see `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` in this repo.\n\n## Quick reference\n\n| Verb / field | Language | Notes |\n|---|---|---|\n| `f.run(command, {timeout?})` / `type: deterministic` | both | shell command, implicit `exit_code` gate |\n| `f.llm(...)` / `type: llm` | both | bare model call, no workspace |\n| `f.agent(name, opts)` / `type: agent` | both | harnessed coding agent, returns `{summary, artifacts}` |\n| `f.human(question, {to})` | TS only | parks the run on a durable `wait.human`; `flows answer <run> human-<n> yes\\|no` then `flows resume` |\n| `use: ['./child.flow.ts']` / `f.dispatch(name, input)` | TS only | `2.0.35`+ direct child in one durable tree; dispatch by declared name |\n| `f.done(reason)` | TS / kernel | one of `success \\| step_failed \\| needs_human \\| declined` from an authored body; `canceled \\| budget_exceeded` are kernel-only |\n| `.gate(config)` / `.gate(predicate, because)` | TS | one per step; both run since flows#449, but only a config object is provable by `flows check` |\n| `options.transport: 'relay'` | TS/YAML `agent` step | dispatch to Agent Relay's task infra; request+receipt, not live chat |\n| `Promise.all([...steps])` | TS | first-class supported concurrent fan-out |\n| `flows.json`: `cli, executors, models, mcp, deploy` | project config | exact accepted key set — nothing else |\n| `flows check <file>` | CLI | pure validate + preflight, no daemon |\n| `flows run <file> --local-agent [--input ...]` | CLI | actually executes; `.flow.ts` needs `--input`, agent/llm steps need `--local-agent` |\n| `flows deploy <flow.ts> --repo ... --on ...` | CLI | persistent trigger-based listener; needs `agent-relay cloud login` plus a connected GitHub App + `--on` provider first, or `flow_repository_not_connected` |\n| `flows run --cloud <flow.ts> --input ...` | CLI | fixed in `2.0.17` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461)); update if you still see `http_error`/`invalid_input` |\n| `flows run --cloud-mirror <file> --local-agent` | CLI | `2.0.32`+; local run also on the Cloud dashboard, transcripts included. Opt-in; `FLOWS_CLOUD_MIRROR=1` for a shell. `--json` gains `cloudRunId`/`dashboardUrl` |\n| `flows run --cloud` with `use` | CLI | unsupported: one self-contained `.flow.ts` source only, even with `--sync-code` |\n| `flows status --cloud <run-id>` / `flows logs <run-id>` | CLI | take Cloud's **UUID**, not the journal ULID. Answer for mirrored local runs since `2.0.32` |\n| `flows runs [--limit <n>]` | CLI | takes **no id** — lists runs newest-first, which is how you find the UUID the two above want |\n| `flows schedule <flow.ts> --cron ...` | CLI | cron-based cloud run |\n\n## Verified against\n\n**The `Ctx` and child-flow contracts were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations.** Earlier gate, helper, and agent-option findings below were established on `2.0.22`; the original `--cloud-mirror` verification was on `2.0.32`.\n\nA three-level root → child → grandchild fixture was run locally from published `2.0.35` packages, then mirrored to the production Cloud dashboard. The [mirrored run](https://agentrelay.com/cloud/dashboard/workflow/0d502725-e4c2-4cfd-aed2-ed0dd49bd6ac/runner) completed with `completionReason: success`; its Cloud graph contained seven succeeded work/dispatch nodes, seven runtime dependency edges, both child labels, and no warnings. A separate `flows run --cloud --sync-code` attempt refused the same tree before admission with `unsupported_source`, which is why this skill does not promise hosted child-flow execution. This checks the graph API used by the dashboard, not an authenticated browser screenshot.\n\n**The `--cloud-mirror` section was verified on `2.0.32`, against production, with the published artifact.** `relayflows@2.0.32` was installed from npm into a scratch project — not run from a source tree — and two real local runs were mirrored to `agentrelay.com`:\n\n- a two-step deterministic flow, read back with `flows status --cloud`, `flows logs` (the `runner.log` round-trip) and `flows runs` (the run appearing in history beside hosted ones);\n- a two-agent flow, one `cli: claude` step and one `cli: codex` step, spending a real `$0.01836` — whose **per-step transcripts were fetched back out of Cloud storage** and rendered in each provider's own frame vocabulary. That is the claim worth having evidence for: an echo-only flow exercises none of the transcript path.\n\nTwo things that verification established and that are easy to assume otherwise. **Flows drives exactly two agent CLIs**: `adapters/index.ts` registers `claude` and `codex`, and anything else resolves to `relayflows-wrapper-v1`, which requires the executable to answer `--relayflows-adapter-v1` with a flows-specific token. A real `devin` CLI on `PATH` rejects that flag outright (`error: unexpected argument`), so it cannot be used as a `cli:` for an agent step no matter what is installed — adding one is a new `adapters/<name>.ts` plus a registry entry. And the **observer projection has no retry**: `run-projection.ts` sets `failed = true` on the first error and every later publish is a no-op, so a transient `429 workspace_busy` — observed for real during this verification, while another run was launching in the same workspace — permanently loses the observer view for that run. The dashboard mirror survived the same window because it classifies `429` as transient and retries on its next poll. If an observer link opens an empty channel, that asymmetry is the first thing to check.\n\nThe earlier `2.0.22` refresh settled several contradictions against the published package: `AgentOptions.permissions` exists on the TypeScript call site (added in `2.0.17`, validated and journaled, not enforced — preflight warns `permissions_unenforced`); `run(command, options?)` takes a second `{timeout}` argument; `f.done` takes six `FLOW_COMPLETION_REASONS`; there is no `budget.maxWallclockMs`; predicate `.gate()` and `artifact_exists` ship; and `f.human` executes. Its then-true finding that `f.dispatch` was unsupported was superseded by `2.0.35`. Older real-run recipes are in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook); check their dates when comparing behavior.\n\nThe `flows.json` schema refusal, the `--data-dir` git-hygiene interaction, and the `flows run --cloud` bug were reproduced while building that cookbook past `v2.0.16` (2026-09-17). The `2.0.22` refresh also checked the `workspace: readonly` annotation and the `subprocess_gate` env var name against the real CLI. Child-flow claims above instead rest on the published `2.0.35` run and its production Cloud graph.\n"
+};
diff --git a/web/lib/test/agent-signup-progress.test.ts b/web/lib/test/agent-signup-progress.test.ts
index f507e6a0..729f16d2 100644
--- a/web/lib/test/agent-signup-progress.test.ts
+++ b/web/lib/test/agent-signup-progress.test.ts
@@ -14,7 +14,7 @@ describe('signup progress handoff', () => {
     expect(isSignupProgress({...progress, product: 'flows', inputRequest: { id, key: 'repository', label: 'Which repository?', type: 'text', status: 'answered' }})).toBe(false);
     expect(isSignupProgress({...progress, inputRequest: { id, key: 'repository', label: 'Which repository?', type: 'select', status: 'pending' }})).toBe(false);
     expect(isSignupProgress({...progress, inputRequest: { id, key: 'workflow', label: 'Which workflow?', type: 'select', options: [], status: 'pending' }})).toBe(false);
-    expect(isSignupProgress({...progress, product: 'flows', inputRequest: { id, key: 'workflow', label: 'Which workflow?', type: 'select', options: ['software-factory', 'code-review'], status: 'pending', step: 0 }})).toBe(true);
+    expect(isSignupProgress({...progress, product: 'flows', inputRequest: { id, key: 'flow_kind', label: 'Prebuilt or custom?', type: 'select', options: ['prebuilt', 'custom'], status: 'pending', step: 0 }})).toBe(true);
     expect(isSignupProgress({...progress, inputRequest: { id, key: 'repository', label: 'Which repository?', type: 'text', status: 'answered', answer: 'private/repo' }})).toBe(false);
     expect(isSignupProgress({...progress, product: 'flows', inputRequest: { id, key: 'draft_saved', label: 'Preview saved.', type: 'notice', status: 'pending', actionHref: `/dashboard/workflows/listeners/${id}`, step: 0 }})).toBe(true);
     expect(isSignupProgress({...progress, inputRequest: { id, key: 'draft_saved', label: 'Preview saved.', type: 'notice', status: 'pending', actionHref: 'https://evil.test' }})).toBe(false);
@@ -40,15 +40,17 @@ describe('signup progress handoff', () => {
     expect(guide).toContain('Do NOT use computer use, browser automation');
     expect(guide).toContain('Verify approval by polling the API');
     expect(guide).toContain('A missing binary is a blocker, not a build task.');
-    expect(guide).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/start');
+    expect(guide).toContain('Cloud API base: http://localhost:3100/cloud');
+    expect(guide).toContain('`POST /api/v1/auth/device/start`');
+    expect(guide).not.toContain('https://agentrelay.com/cloud');
     if (product === 'teams') {
-      expect(guide).toContain('there is no public HTTP endpoint that installs an app');
+      expect(guide).toContain('# Set Up Agent Relay Desktop');
       expect(guide).toContain('Do not build it, run the development launcher to produce it');
       expect(guide).not.toContain('the local stack must be built');
-      expect(guide).toContain("Do not inspect the app's");
-      expect(guide).toContain("attachment as unverified and keep progress waiting at step 5");
+      expect(guide).toContain('# Set Up Agent Relay Session Handoff');
+      expect(guide).toContain('only then PATCH step: 5, state: complete');
     } else {
-      expect(guide).toContain('POST http://localhost:3100/cloud/api/v1/flows/deploy');
+      expect(guide).toContain('POST /api/v1/flows/deploy');
       expect(guide).toContain('GET http://localhost:3100/api/v1/flows/catalog');
       expect(guide).toContain('POST the exact Progress API URL');
       expect(guide).toContain('authenticated GET includes inputRequest.answer');
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 1c7eef19..577b1cf0 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -1,7 +1,16 @@
+import { readFileSync } from 'node:fs';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { GET } from '../../app/signup/agent/[product]/route';
 import { agentSignupPrompt } from '../agent-signup';
+import { SETUP_SKILLS, SETUP_SKILLS_SOURCE } from '../generated/setup-skills';
 import { getRecommendedFlow } from '../recommended-flow-catalog';
+// @ts-expect-error -- plain .mjs build script without type declarations
+import { renderModule, stripFrontmatter } from '../../scripts/sync-setup-skills.mjs';
+
+const vendored = (name: string) => readFileSync(new URL(`../../content/setup-skills/${name}.md`, import.meta.url), 'utf8');
+const pin = JSON.parse(readFileSync(new URL('../../content/setup-skills/SOURCE.json', import.meta.url), 'utf8'));
+const guide = async (product: string, url = `https://agentrelay.com/signup/agent/${product}`) =>
+  (await GET(new Request(url), { params: Promise.resolve({ product }) })).text();
 
 afterEach(() => vi.unstubAllEnvs());
 
@@ -16,25 +25,96 @@ describe('agent signup instructions', () => {
     expect(response.headers.get('access-control-allow-origin')).toBe('*');
     expect(response.headers.get('cache-control')).toBe('no-store');
     const content = await response.text();
-    expect(content).toContain(`"signup_source":"${product}"`);
+    expect(content).toContain(`signup_source "${product}"`);
     expect(content).toContain('Cloud API base: https://agentrelay.com/cloud');
     expect(content).toContain('/api/v1/auth/device/token');
     expect(content).toContain('/api/v1/auth/whoami');
     expect(content).toContain('/api/v1/auth/token/refresh');
     expect(agentSignupPrompt(product as 'teams' | 'flows', 'https://agentrelay.com')).toContain('Do NOT use computer use, browser automation');
     if (product === 'teams') {
-      expect(content).toContain('--selected-sessions-only --json');
-      expect(content).toContain('releases/latest/download/AgentRelay-macOS-<arch>.dmg');
-      expect(content).toContain('site_url, account_id, and\nworkspace_id');
-      expect(content).toContain('last_cycle');
-      expect(content).toContain('SOURCE:SESSION_ID');
-      expect(content).toContain('will report a conflict, not switch accounts');
+      expect(content).toContain('releases/latest/download');
+      expect(content).toContain('AgentRelay-macOS-$relay_arch.dmg');
     } else {
       expect(content).toContain('"mode": "activate"');
       expect(content).toContain('/api/v1/flows/listeners/<agentId>');
     }
   });
 
+  it('vendors exactly the pinned skills, with frontmatter stripped', () => {
+    expect(pin.repository).toBe('AgentWorkforce/skills');
+    expect(pin.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(SETUP_SKILLS_SOURCE).toEqual({ repository: pin.repository, commit: pin.commit });
+    expect(Object.keys(SETUP_SKILLS)).toEqual(pin.skills);
+    for (const name of pin.skills) {
+      expect(SETUP_SKILLS[name]).toBe(vendored(name));
+      expect(SETUP_SKILLS[name].startsWith('# ')).toBe(true);
+      expect(SETUP_SKILLS[name]).not.toMatch(/^---\nname:/);
+    }
+    // The generated module is exactly what the sync script renders from the copies.
+    const generated = readFileSync(new URL('../generated/setup-skills.ts', import.meta.url), 'utf8');
+    expect(generated).toBe(renderModule(pin, Object.fromEntries(pin.skills.map((name: string) => [name, vendored(name)]))));
+    expect(stripFrontmatter('---\nname: x\ndescription: y\n---\n\n# X\n')).toBe('# X\n');
+    expect(() => stripFrontmatter('# X\n')).toThrow('frontmatter');
+  });
+
+  it.each([
+    ['teams', ['signing-in-to-agent-relay-cloud', 'setting-up-agent-relay-desktop', 'setting-up-agent-relay-sessions'], ['Cloud account', 'Desktop', 'Sessions']],
+    ['flows', ['signing-in-to-agent-relay-cloud', 'setting-up-agent-relay-flows', 'writing-relayflows'], ['Cloud account', 'Flows', 'Custom flow authoring']],
+  ])('renders %s as the signup header followed by the skills verbatim, in order', async (product, skills, labels) => {
+    const content = await guide(product);
+    expect(content).toContain(`verbatim at commit ${pin.commit}`);
+    let cursor = 0;
+    skills.forEach((name, index) => {
+      const part = content.indexOf(`# Part ${index + 1}: ${labels[index]}\n\n${SETUP_SKILLS[name].trim()}\n`, cursor);
+      expect(part, `${name} rendered verbatim as Part ${index + 1}`).toBeGreaterThan(cursor);
+      cursor = part;
+    });
+    expect(content).not.toContain(`# Part ${skills.length + 1}:`);
+    // The header keeps only signup-specific rules; no setup step is duplicated before Part 1.
+    const header = content.slice(0, content.indexOf('# Part 1:'));
+    expect(header).not.toContain('/api/v1/auth/device/start');
+    expect(header).not.toContain('hdiutil');
+    expect(header).not.toContain('claude mcp add');
+    expect(header).not.toContain('/api/v1/flows/deploy');
+  });
+
+  it('renders both Teams skills\' headings and claims completion only after the Sessions round trip', async () => {
+    const content = await guide('teams');
+    const desktop = content.indexOf('# Set Up Agent Relay Desktop');
+    const sessions = content.indexOf('# Set Up Agent Relay Session Handoff');
+    expect(desktop).toBeGreaterThan(0);
+    expect(sessions).toBeGreaterThan(desktop);
+    const roundTrip = content.indexOf('## 5. Prove one live round trip', sessions);
+    expect(roundTrip).toBeGreaterThan(sessions);
+    // Every instruction to PATCH completion is in the header and is tied to Part 3's round trip.
+    const header = content.slice(0, content.indexOf('# Part 1:'));
+    const completions = [...content.matchAll(/state: complete/g)].map(match => match.index!);
+    expect(completions.length).toBeGreaterThan(0);
+    for (const index of completions) expect(index).toBeLessThan(header.length);
+    expect(header).toContain('Keep step 5 working or waiting until Part 3 proves a\n   live round trip; only then PATCH step: 5, state: complete.');
+    expect(header).toContain('A self-verified\n   read path without a teammate is not completion.');
+    expect(header).toContain('Setup is complete only in Part 3\'s finished state: a proven live round trip.');
+    expect(content.slice(roundTrip)).toContain('Setup is not complete until the full round trip succeeds.');
+  });
+
+  it('reads the sharing mode from the desktop and asks before changing an existing one', async () => {
+    const content = await guide('teams');
+    expect(content).toContain("jq -r '.data.sharing_mode'");
+    expect(content).toContain('Never change it silently.');
+    expect(content).toContain('sharing_mode: .data.sharing_mode');
+    expect(content).toContain('Report\n   waiting while the user decides about an existing sharing mode.');
+  });
+
+  it('keeps the agent-relay CLI optional and carries the latency and HTTP-client guidance', async () => {
+    const content = await guide('teams');
+    expect(content).toContain('do not install or\nupgrade it just for these checks');
+    expect(content).not.toMatch(/npm install -g agent-relay/);
+    expect(content).toContain('relay-desktop#333');
+    expect(content).toContain('60-second timeout');
+    expect(content).toContain('Use `curl` or `fetch`');
+    expect(content).toContain('cloud#4254');
+  });
+
   it('keeps the local hostname and port for OAuth, APIs, and the dev desktop download', async () => {
     vi.stubEnv('NEXT_PUBLIC_CLOUD_URL', '/cloud');
     const content = await (await GET(new Request('http://127.0.0.1:3199/signup/agent/teams'), {
@@ -42,7 +122,9 @@ describe('agent signup instructions', () => {
     })).text();
     expect(content).toContain('Cloud API base: http://127.0.0.1:3199/cloud');
     expect(content).toContain('http://127.0.0.1:3199/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg');
-    expect(content).not.toContain('releases/latest/download');
+    expect(content).toContain('relay-socket.dev');
+    expect(content).toContain('http://127.0.0.1:3199/cloud/api/v1/mcp/shared-sessions');
+    expect(content).not.toContain('https://agentrelay.com/cloud');
     expect(agentSignupPrompt('teams', 'http://127.0.0.1:3199')).toContain('http://127.0.0.1:3199/signup/agent/teams');
   });
 
@@ -52,7 +134,7 @@ describe('agent signup instructions', () => {
       params: Promise.resolve({ product: 'flows' }),
     })).text();
     expect(content).toContain('Cloud API base: http://127.0.0.1:3100/cloud');
-    expect(content).toContain('POST the Progress API URL to request a choice');
+    expect(content).toContain('## Web input — ask on the signup page, never in chat');
   });
 
   it('ignores an invalid local Host port instead of constructing an invalid URL', async () => {
@@ -83,7 +165,7 @@ describe('agent signup instructions', () => {
     const content = await (await GET(new Request('https://agentrelay.com/signup/agent/flows'), {
       params: Promise.resolve({ product: 'flows' }),
     })).text();
-    const examples = [...content.matchAll(/~~~json\n([\s\S]*?)\n~~~/g)].map(match => JSON.parse(match[1]));
+    const examples = [...content.matchAll(/(?:~~~|```)json\n([\s\S]*?)\n(?:~~~|```)/g)].map(match => JSON.parse(match[1]));
     const deploy = examples.find(body => body.mode === 'activate');
     const flow = getRecommendedFlow('software-factory')!;
     expect(deploy).toMatchObject({
diff --git a/web/scripts/sync-setup-skills.mjs b/web/scripts/sync-setup-skills.mjs
new file mode 100644
index 00000000..d8d7bf4d
--- /dev/null
+++ b/web/scripts/sync-setup-skills.mjs
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Vendors the Agent Relay setup skills that /signup/agent/teams and
+// /signup/agent/flows render. The single source of truth is the public
+// AgentWorkforce/skills repository at the commit pinned in
+// web/content/setup-skills/SOURCE.json; nothing here is edited by hand.
+//
+//   node web/scripts/sync-setup-skills.mjs          # fetch the pin, rewrite the copies
+//   node web/scripts/sync-setup-skills.mjs --check  # fail when the copies differ from the pin
+//
+// To move the pin, change "commit" in SOURCE.json and run without --check.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const contentDir = new URL('../content/setup-skills/', import.meta.url);
+const sourceUrl = new URL('SOURCE.json', contentDir);
+const generatedUrl = new URL('../lib/generated/setup-skills.ts', import.meta.url);
+const SHA = /^[0-9a-f]{40}$/;
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function stripFrontmatter(text) {
+  const match = /^---\n[\s\S]*?\n---\n+/.exec(text);
+  if (!match) throw new Error('SKILL.md is missing YAML frontmatter');
+  return text.slice(match[0].length);
+}
+
+export function renderModule(source, skills) {
+  const banner = '// Generated by web/scripts/sync-setup-skills.mjs from the pinned\n'
+    + '// AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.\n';
+  return `${banner}export const SETUP_SKILLS_SOURCE = ${JSON.stringify({ repository: source.repository, commit: source.commit })} as const;\n\n`
+    + `export const SETUP_SKILLS: Readonly<Record<string, string>> = ${JSON.stringify(skills, null, 2)};\n`;
+}
+
+async function readSource() {
+  const source = JSON.parse(await readFile(sourceUrl, 'utf8'));
+  if (source.repository !== 'AgentWorkforce/skills') throw new Error('SOURCE.json repository must be AgentWorkforce/skills');
+  if (!SHA.test(source.commit ?? '')) throw new Error('SOURCE.json commit must be a full 40-character commit SHA');
+  if (!Array.isArray(source.skills) || source.skills.length === 0 || !source.skills.every(name => NAME.test(name))) {
+    throw new Error('SOURCE.json skills must be a non-empty list of skill directory names');
+  }
+  return source;
+}
+
+async function fetchSkill(source, name) {
+  const url = `https://raw.githubusercontent.com/${source.repository}/${source.commit}/skills/${name}/SKILL.md`;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return stripFrontmatter(await response.text());
+    } catch (error) {
+      if (attempt >= 3) throw new Error(`Could not fetch ${url}: ${error.message}`);
+      await new Promise(resolve => setTimeout(resolve, attempt * 2000));
+    }
+  }
+}
+
+async function main() {
+  const check = process.argv.includes('--check');
+  const source = await readSource();
+  const skills = Object.fromEntries(await Promise.all(source.skills.map(async name => [name, await fetchSkill(source, name)])));
+  const expected = new Map(source.skills.map(name => [new URL(`${name}.md`, contentDir), skills[name]]));
+  expected.set(generatedUrl, renderModule(source, skills));
+
+  if (check) {
+    const stale = [];
+    for (const [url, text] of expected) {
+      const existing = await readFile(url, 'utf8').catch(() => null);
+      if (existing !== text) stale.push(url.pathname);
+    }
+    if (stale.length) {
+      console.error(`Setup skills differ from AgentWorkforce/skills@${source.commit}:\n${stale.map(path => `  ${path}`).join('\n')}`);
+      console.error('Run node web/scripts/sync-setup-skills.mjs to re-vendor them; never edit the copies by hand.');
+      process.exit(1);
+    }
+    console.log(`Setup skills match AgentWorkforce/skills@${source.commit} (${source.skills.join(', ')}).`);
+    return;
+  }
+  await mkdir(new URL('.', generatedUrl), { recursive: true });
+  for (const [url, text] of expected) await writeFile(url, text);
+  console.log(`Vendored ${source.skills.length} setup skills from AgentWorkforce/skills@${source.commit}.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

From 7d69310d21238de7d3421ff159d7e8f04954dc65 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 22:39:20 -0700
Subject: [PATCH 2/9] test(signup): Flows guide never imports or installs
 @relayflows/core

The vendored writing-relayflows may name it only to warn against the v1
engine; no part before it mentions it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/lib/test/agent-signup.test.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 577b1cf0..2eff8cc4 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -78,6 +78,18 @@ describe('agent signup instructions', () => {
     expect(header).not.toContain('/api/v1/flows/deploy');
   });
 
+  it('keeps Flows on the v2 engine: it may warn about @relayflows/core but never imports or installs it', async () => {
+    const content = await guide('flows');
+    expect(content).toContain('@relayflows/surface');
+    expect(content).not.toMatch(/from\s+['"]@relayflows\/core['"]/);
+    expect(content).not.toMatch(/(?:npm|pnpm|yarn|bun)\s+(?:i|install|add)\b[^\n]*@relayflows\/core/);
+    expect(content).not.toMatch(/require\(\s*['"]@relayflows\/core['"]\s*\)/);
+    // The only mentions are writing-relayflows' warning against the older engine.
+    const header = content.slice(0, content.indexOf('# Part 1:'));
+    expect(header).not.toContain('@relayflows/core');
+    expect(content.slice(0, content.indexOf('# Part 3:'))).not.toContain('@relayflows/core');
+  });
+
   it('renders both Teams skills\' headings and claims completion only after the Sessions round trip', async () => {
     const content = await guide('teams');
     const desktop = content.indexOf('# Set Up Agent Relay Desktop');

From e375ad74986f67714f20f1edd598ea992e3bdc91 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 22:45:13 -0700
Subject: [PATCH 3/9] chore(signup): re-pin setup skills to
 AgentWorkforce/skills@7a63664

Picks up the review fixes in skills#145 (kept sharing mode, socket
timeouts, base-relative URLs); tests follow the new text.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/content/setup-skills/SOURCE.json          |  2 +-
 .../setting-up-agent-relay-desktop.md         | 75 ++++++++++++-------
 .../setting-up-agent-relay-flows.md           | 16 ++--
 .../setting-up-agent-relay-sessions.md        | 37 +++++----
 .../signing-in-to-agent-relay-cloud.md        | 12 +--
 web/lib/generated/setup-skills.ts             | 10 +--
 web/lib/test/agent-signup.test.ts             |  8 +-
 7 files changed, 103 insertions(+), 57 deletions(-)

diff --git a/web/content/setup-skills/SOURCE.json b/web/content/setup-skills/SOURCE.json
index 85c960de..42cffef2 100644
--- a/web/content/setup-skills/SOURCE.json
+++ b/web/content/setup-skills/SOURCE.json
@@ -1,6 +1,6 @@
 {
   "repository": "AgentWorkforce/skills",
-  "commit": "23a0754950654d765c417c188af52d130864b664",
+  "commit": "7a636649f914dbe9e6807ee491d556c2f3e7c070",
   "skills": [
     "signing-in-to-agent-relay-cloud",
     "setting-up-agent-relay-desktop",
diff --git a/web/content/setup-skills/setting-up-agent-relay-desktop.md b/web/content/setup-skills/setting-up-agent-relay-desktop.md
index 0000e184..f6c066fb 100644
--- a/web/content/setup-skills/setting-up-agent-relay-desktop.md
+++ b/web/content/setup-skills/setting-up-agent-relay-desktop.md
@@ -233,7 +233,7 @@ esac
 relay_unit="$HOME/.config/systemd/user/agent-relay.service"
 relay_installed_version=
 if test -S "${relay_socket:-/nonexistent}"; then
-  relay_installed_version=$(curl -fsS --unix-socket "$relay_socket" \
+  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket "$relay_socket" \
     http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)
 fi
 if test -z "$relay_installed_version" && test -r "$relay_unit"; then
@@ -345,7 +345,7 @@ if ! test -S "$relay_socket" && test "$(uname -s)" = Linux; then
   relay_socket="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock"
 fi
 test -S "$relay_socket"
-curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
+curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
 ```
 
 ## 3. Sign in by device approval
@@ -355,7 +355,7 @@ only read state. The CLI checks run only when section 2 found a `relay_cli`;
 never call the `.deb`'s `/usr/bin/agent-relay` launcher for them:
 
 ```sh
-curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{sign_in: .data.sign_in, workspace: .data.workspace}'
 if test -n "${relay_cli:-}"; then
   "$relay_cli" cloud whoami       # signed in, and as whom
@@ -377,7 +377,7 @@ human has confirmed that the reusable login's current workspace is intended.
 ```sh
 relay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'
 sign_in_payload=$(jq -nc --arg workspace "$relay_workspace_uuid" '{workspace:$workspace}')
-sign_in=$(curl -sS --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -396,7 +396,7 @@ acknowledgement added; never use it merely to suppress the error:
 ```sh
 sign_in_payload=$(printf '%s\n' "$sign_in_payload" | \
   jq '. + {acknowledge_uninspected_schedules:true}')
-sign_in=$(curl -sS --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -439,7 +439,7 @@ print it, and map the known messages to their fix instead of dumping raw state:
 
 ```sh
 while :; do
-  state=$(curl -sS --unix-socket "$relay_socket" http://relay/setup/status)
+  state=$(curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status)
   phase=$(printf '%s' "$state" | jq -r '.data.sign_in // .error.code')
   case "$phase" in
     signed_in)
@@ -473,15 +473,28 @@ uploading yet). The probe reports the same field, `sharing_mode`, in
 `agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.
 
 ```sh
-curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
-  jq -r '.data.sharing_mode'
+relay_prior_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+  http://relay/setup/status | jq -r '.data.sharing_mode // empty')
+case "$relay_prior_mode" in
+  new|all|selected) printf 'sharing_mode=%s\n' "$relay_prior_mode" ;;
+  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\n' >&2
+     exit 1 ;;
+esac
 ```
 
-On a fresh install, or when it already reports `new`, use `new`. When an
+Continue only with a verified `new`, `all`, or `selected`. If the status read
+fails or reports no mode, retry once; if it is still unknown, stop and ask the
+human how to proceed rather than sending any sharing request.
+
+On a fresh install, or when it already reports `new`, keep `new`. When an
 existing install reports `all` (which also uploads past sessions, so it is
 broader than this skill's default) or `selected`, tell the human the current
 mode and ask whether to keep it or change it to `new`. Never change it silently.
-Set `relay_sharing_mode` below to the human's answer.
+Only when the human explicitly chooses a different mode, set
+`relay_sharing_mode` to that answer at the top of the next block; left unset,
+the block keeps the mode the app reports, so nothing changes without an answer.
+Remember the chosen mode: section 8 checks it again, and shell variables do not
+survive between separate tool calls.
 
 Then set and verify all three agent-led defaults even when the app's `/setup/*`
 bootstrap already applied them. Sharing mode `new` uploads every new session;
@@ -489,8 +502,17 @@ auto-activation puts every existing live session and every future session on
 the relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:
 
 ```sh
-relay_sharing_mode=new   # or the existing mode the human chose to keep
-direct_delivery=$(curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+# Unset keeps the current mode; set it only to the human's explicit answer.
+if test -z "${relay_sharing_mode:-}"; then
+  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+    http://relay/setup/status | jq -r '.data.sharing_mode // empty')
+fi
+case "$relay_sharing_mode" in
+  new|all|selected) ;;
+  *) printf 'Sharing mode unknown; ask the human before changing sharing.\n' >&2
+     exit 1 ;;
+esac
+direct_delivery=$(curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' http://relay/setup/direct-delivery)
 printf '%s\n' "$direct_delivery" | jq
 if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; then
@@ -499,17 +521,17 @@ if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; t
   fi
   exit 1
 fi
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d "$(jq -nc --arg mode "$relay_sharing_mode" '{mode:$mode}')" \
   http://relay/setup/sharing | jq
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' \
   http://relay/setup/auto-activate | jq
-register=$(curl -sS --unix-socket "$relay_socket" \
+register=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d '{}' http://relay/register)
 printf '%s\n' "$register" | jq
-registration_status=$(curl -sS --unix-socket "$relay_socket" \
+registration_status=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   http://relay/setup/status)
 printf '%s\n' "$registration_status" | \
   jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'
@@ -548,7 +570,7 @@ Capture the one-time secret without echoing it:
 ```sh
 umask 077
 hook_file=$(mktemp)
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{}' http://relay/webhooks >"$hook_file"
 jq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' "$hook_file"
 ```
@@ -659,10 +681,10 @@ relay_req() {  # METHOD PATH [JSON body]
     printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\n' >&2
     return 1
   elif test -n "${3:-}"; then
-    curl -sS --unix-socket "$relay_socket" -X "$1" \
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' -d "$3" "http://relay$2"
   else
-    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 
@@ -809,15 +831,18 @@ agent acted only once.
 Read status again:
 
 ```sh
-curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'
 ```
 
-Require all three defaults before declaring setup complete:
+Require all three defaults before declaring setup complete. Set
+`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the
+existing mode the human kept); the check refuses to guess it:
 
 ```sh
-curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | \
-  jq -e --arg mode "${relay_sharing_mode:-new}" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'
+: "${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}"
+curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq -e --arg mode "$relay_sharing_mode" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'
 ```
 
 Report the exact version, `signed_in`, signed-in workspace id and name, sharing
@@ -891,7 +916,7 @@ event.
 - **Managed Claude policy:** if direct delivery reports `managed_policy`, the
   organization controls `crossSessionInbound`; report the policy block rather
   than modifying managed settings.
-- **Undo registration:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
+- **Undo registration:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
 - **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,
   `relay_req`, and `pr_resources` defined, remove every subscription the
   session holds for the pull request, in whichever form it was made. On macOS
@@ -909,7 +934,7 @@ event.
   ```
 
   Require the final list to hold none of that pull request's resources.
-- **Undo a webhook:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
+- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
 - **Undo direct delivery:** POST `{"enabled":false}` to
   `/setup/direct-delivery`. On Claude this restores the local opt-out; managed
   organization policy still wins.
diff --git a/web/content/setup-skills/setting-up-agent-relay-flows.md b/web/content/setup-skills/setting-up-agent-relay-flows.md
index d6358bb1..952b685f 100644
--- a/web/content/setup-skills/setting-up-agent-relay-flows.md
+++ b/web/content/setup-skills/setting-up-agent-relay-flows.md
@@ -7,9 +7,12 @@ those links with the OS URL opener (or give them the link), then verify by
 polling the API, never by inspecting the browser.
 
 Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
-including its `/cloud` prefix; the site is `https://agentrelay.com`. When a
+including its `/cloud` prefix; the site is `https://agentrelay.com`. The flow
+catalog is the one exception: it is a site API, served from the site origin
+without `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a
 guide names a different site and Cloud base (for example a local development
-stack), use those exact origins throughout and never fall back to production.
+stack), use those exact origins throughout, including for the catalog, the
+CLI's `--api-url` and the dashboard links, and never fall back to production.
 Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
 
 ## Requires
@@ -20,7 +23,8 @@ first, and send `Authorization: Bearer <access_token>` on every request below.
 
 ## API map
 
-- Flow catalog: `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.
+- Flow catalog (site origin, not under `/cloud`):
+  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.
 - Tool consent links: `POST /api/v1/integrations/connect-link`; poll
   `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.
 - Coding-agent credentials: the official CLI's `cloud connect` (section 3);
@@ -97,8 +101,8 @@ as a prebuilt one; only where the source comes from differs.
 
 The human-only steps are the same for both paths: Google sign-in and device
 approval, GitHub and trigger-app OAuth including the repository grants,
-model-provider login, and confirming the repository and trigger before
-activation. Do every other step yourself through the APIs.
+model-provider login when section 3 calls for one (not for an ordinary first
+activation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.
 
 ## 3. Connect the required tools and coding agents
 
@@ -141,7 +145,7 @@ verify the proxy, promotion flag, provider readiness, and enrollment. Never
 copy a house key into the agent environment or expose it in this guide.
 
 ```sh
-npx --yes agent-relay@latest cloud connect anthropic --api-url 'https://agentrelay.com/cloud'
+npx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'
 ```
 
 Use anthropic for Claude or openai for Codex, according to the selected flow.
diff --git a/web/content/setup-skills/setting-up-agent-relay-sessions.md b/web/content/setup-skills/setting-up-agent-relay-sessions.md
index c5ebe0c2..4ca07728 100644
--- a/web/content/setup-skills/setting-up-agent-relay-sessions.md
+++ b/web/content/setup-skills/setting-up-agent-relay-sessions.md
@@ -156,15 +156,20 @@ Before sending that message, check what this machine already has. If an Agent
 Relay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not
 the `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only
 checks. Without one, section 2 reads the signed-in workspace from
-`/setup/status` instead. The CLI is optional for this skill: check with
-`command -v agent-relay` and `agent-relay --version`, and do not install or
-upgrade it just for these checks.
+`/setup/status` instead. The CLI is optional for this skill: detect it as
+below, which skips the Desktop launcher that `command -v agent-relay` finds on
+a `.deb` install, and do not install or upgrade it just for these checks.
 
 ```sh
-agent-relay cloud whoami       # signed in, and as whom
-agent-relay workspace active   # the active Cloud workspace (keys stay masked)
-agent-relay cloud workspaces   # every workspace this login can use, with ids
-agent-relay status             # workspace, cloud login and local broker
+relay_cli=$(command -v agent-relay || true)
+case "$relay_cli" in ''|/usr/bin/agent-relay) relay_cli= ;; esac
+if test -n "$relay_cli"; then
+  "$relay_cli" --version
+  "$relay_cli" cloud whoami       # signed in, and as whom
+  "$relay_cli" workspace active   # the active Cloud workspace (keys stay masked)
+  "$relay_cli" cloud workspaces   # every workspace this login can use, with ids
+  "$relay_cli" status             # workspace, cloud login and local broker
+fi
 ```
 
 If the active workspace is already the shared one, confirm it with the person
@@ -244,10 +249,10 @@ relay_req() {
     return 1
   elif test -n "${3:-}"; then
     # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename
-    printf '%s' "$3" | curl -sS --unix-socket "$relay_socket" -X "$1" \
+    printf '%s' "$3" | curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' --data-binary @- "http://relay$2"
   else
-    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 ```
@@ -311,10 +316,16 @@ read **this** person's session, this machine must have uploaded it. If
 anyone can read this session — this is the single most common reason a live
 handoff silently fails.
 
-`sharing_mode` decides which sessions upload at all. `new` and `all` include
-this session. Under `selected`, only the sessions the person chose upload, so a
-teammate cannot read this one until the person selects it. Tell them that and
-ask; do not change the sharing mode or select sessions on their behalf.
+`sharing_mode` decides which sessions upload at all, and a healthy uploader
+does not prove that **this** session is among them. `all` includes it. `new`
+includes sessions that started after `new` was enabled, so a session that was
+already running when the desktop was set up may not be uploaded. Under
+`selected`, only the sessions the person chose upload. Unless the mode is
+`all`, tell the person that this session may not be shared yet, and ask them to
+select it in the app or to continue from a new session; do not change the
+sharing mode or select sessions on their behalf. Section 5's round trip is the
+proof: if the teammate cannot read this session there, this is the first
+thing to check.
 
 ## 3. Install the agent-sessions cloud MCP (before the session uses it)
 
diff --git a/web/content/setup-skills/signing-in-to-agent-relay-cloud.md b/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
index caa0e273..05b2e5ea 100644
--- a/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
+++ b/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
@@ -40,11 +40,13 @@ lets them sign in with Google, review the requesting device, and Approve or
 Deny. A signup marker in the returned URL creates the right account type;
 preserve it through sign-in. Do not call `/auth/device/approve` yourself.
 
-For a fresh signup, you can open
-`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`
-first, where `encoded-return-path` is the URL-encoded pathname plus query of
+For a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`
+on the same Cloud base first (in production,
+`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of
 `verification_uri_complete`. This opens Google immediately and returns to the
-same device approval with its code and signup marker intact.
+same device approval with its code and signup marker intact. Never open the
+production URL for a non-production base: that would sign the human in to
+production instead.
 
 ## 2. Poll for tokens
 
@@ -97,7 +99,7 @@ When running a child process, pass these through its environment from your
 private session object (never interpolate their values into logged commands):
 
 ```text
-CLOUD_API_URL=https://agentrelay.com/cloud
+CLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>
 CLOUD_API_ACCESS_TOKEN=<access_token>
 CLOUD_API_REFRESH_TOKEN=<refresh_token>
 CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
diff --git a/web/lib/generated/setup-skills.ts b/web/lib/generated/setup-skills.ts
index 9b84b94c..0cc5343e 100644
--- a/web/lib/generated/setup-skills.ts
+++ b/web/lib/generated/setup-skills.ts
@@ -1,11 +1,11 @@
 // Generated by web/scripts/sync-setup-skills.mjs from the pinned
 // AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.
-export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"23a0754950654d765c417c188af52d130864b664"} as const;
+export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"7a636649f914dbe9e6807ee491d556c2f3e7c070"} as const;
 
 export const SETUP_SKILLS: Readonly<Record<string, string>> = {
-  "signing-in-to-agent-relay-cloud": "# Sign In to Agent Relay Cloud\n\nUse the existing OAuth device flow. No API key, invitation, dashboard wizard,\nor pre-existing Agent Relay account is required. Only the human approves the\nsign-in; never approve access on their behalf, ask for their password, or\noperate the approval page yourself.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix. When a guide names a different Cloud base (for\nexample a local development stack), use that exact base throughout and never\nfall back to production.\n\n## HTTP client\n\nUse `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their\ndefault User-Agent: the device-token endpoint answers them with HTTP 403 and no\nJSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth\nresponse while debugging; on success it contains tokens. Send JSON request\nbodies with `Content-Type: application/json`, set a 30-second request timeout,\nand check every response status before proceeding.\n\n## 1. Start the device grant\n\n`POST /api/v1/auth/device/start` with:\n\n```json\n{\"client_name\":\"My agent setup\"}\n```\n\nAn agent-driven signup guide also passes its product as `signup_source`\n(`\"teams\"` or `\"flows\"`); keep the value the guide names. Omit it otherwise.\n\nExpect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,\n`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep\n`device_code` private. Open `verification_uri_complete` in the person's\nbrowser with the OS URL opener (for example macOS `open`, with the URL passed as\na separate argument, never interpolated into shell code), or give them the link\nif no opener is available. Show the `user_code` so they can compare it. The page\nlets them sign in with Google, review the requesting device, and Approve or\nDeny. A signup marker in the returned URL creates the right account type;\npreserve it through sign-in. Do not call `/auth/device/approve` yourself.\n\nFor a fresh signup, you can open\n`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`\nfirst, where `encoded-return-path` is the URL-encoded pathname plus query of\n`verification_uri_complete`. This opens Google immediately and returns to the\nsame device approval with its code and signup marker intact.\n\n## 2. Poll for tokens\n\nWhile the browser is open, wait `interval` seconds between POSTs to\n`/api/v1/auth/device/token` with this JSON (substitute the private\n`device_code`):\n\n```json\n{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"<device_code>\"}\n```\n\n- `authorization_pending`: keep waiting; respect a returned interval.\n- `slow_down`: increase the interval by at least 5 seconds.\n- HTTP 429: respect `Retry-After` and increase the interval.\n- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.\n- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start\n  a new grant only if the person still wants to continue. Never poll past\n  expiry.\n\nHTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,\n`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in\nmemory or a private file (directory 0700, file 0600) outside repositories.\nNever echo tokens, put them in chat or URLs, or dump full authentication\nresponses. Use `Authorization: Bearer <access_token>` for subsequent Cloud\nrequests. Reject an `api_url` pointing at another origin; keep using the Cloud\nbase above.\n\n## 3. Refresh before expiry\n\nBefore expiry, `POST /api/v1/auth/token/refresh` with\n`{\"refreshToken\":\"<refresh_token>\"}`. The response uses camelCase:\n`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,\n`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the\nrefresh token rotates and must not be shared between machines. An\ninvalid/expired refresh requires a new device login, not an endless retry.\n\n## 4. Read the account and workspace\n\n`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,\n`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups\ncreate a workspace automatically. Reuse it; do not create duplicate\naccounts/workspaces. If `currentWorkspace` is missing, or an existing account\nis in the wrong workspace, resolve that with the person before connecting or\nactivating anything. Never silently replace an existing connection to another\naccount.\n\n## 5. Hand the session to the official CLI\n\nWhen running a child process, pass these through its environment from your\nprivate session object (never interpolate their values into logged commands):\n\n```text\nCLOUD_API_URL=https://agentrelay.com/cloud\nCLOUD_API_ACCESS_TOKEN=<access_token>\nCLOUD_API_REFRESH_TOKEN=<refresh_token>\nCLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>\nCLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>\n```\n\nThe official CLI consumes this session. Refresh the parent session before\nstarting a long command; do not concurrently refresh it from parent and child\nprocesses. Do not overwrite an existing CLI auth file or copy a session to\nanother machine. Delete temporary authentication files after the work is\ncomplete.\n",
-  "setting-up-agent-relay-desktop": "# Set Up Agent Relay Desktop\n\nComplete the setup through the private session socket. Do not ask the human to\nclick through the desktop app. The only normal human step is approving one\ndevice-login link when no reusable `agent-relay` CLI login exists.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the current release is installed and running;\n- sign-in is complete;\n- sharing mode is `new` (new sessions upload automatically), unless an existing\n  install already uses another mode and the human chose to keep it (section 4);\n- auto-activate is on, with every existing live session and every future session on the relay;\n- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);\n- this Codex or Claude session is registered and accepts direct delivery;\n- the requested webhook and integration subscriptions work;\n- the human receives the session's `agent@machine` address and verification evidence.\n\nNever put a Cloud token, workspace key, agent token, or webhook secret in a\nRelay message. The webhook secret is returned once to this local calling\nsession; keep it in a mode-0600 temporary file and delete the file after the\ntest.\n\n## Install this skill for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage, then place that unchanged `SKILL.md` where Codex actually loads global\nskills:\n\n```sh\nnpx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y\ncodex_skill=\"$HOME/.codex/skills/setting-up-agent-relay-desktop\"\nmkdir -p \"$codex_skill\"\ninstall -m 0644 \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\ncmp \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\n```\n\nDo not use prpm's `--as codex` conversion for this package. It currently writes\nunder `~/.agents/skills`, which Codex does not load as its global skill folder,\nand its conversion drops explanatory paragraphs from this Markdown workflow.\nConfirm both final paths explicitly before continuing.\n\n## 1. Detect the host and current session\n\nRun setup commands from this agent's own shell tool. Do not run them from an\nunrelated terminal: the app identifies the caller from kernel credentials and\nthe Codex/Claude process ancestry.\n\n```sh\nuname -s\nuname -m\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\nif test \"$(uname -s)\" = Linux; then\n  if command -v dpkg-query >/dev/null; then\n    printf 'linux_install=deb\\n'\n  else\n    printf 'linux_install=per-user-tarball\\n'\n  fi\nfi\ncommand -v systemctl >/dev/null && systemctl --user is-system-running || true\n```\n\nOn Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other\nsystemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball\npath; do not try to install the `.deb`. The app scans same-user process trees\nand TTYs; it does not require the service itself to share the tmux session.\n\n`systemctl --user is-system-running` may report `degraded` because an unrelated\nuser unit failed. That is not a Relay failure when\n`systemctl --user is-active agent-relay.service` reports `active` and the Relay\nsocket passes its status check.\n\nFind an existing socket without printing private files:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test -n \"${XDG_RUNTIME_DIR:-}\"; then\n  relay_socket=\"$XDG_RUNTIME_DIR/agent-relay/relay.sock\"\nfi\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"/run/user/$(id -u)/agent-relay/relay.sock\"\nfi\nc=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Darwin && test -S \"$c\"; then   # pointer file missing: use the app's own socket\n  relay_socket=$c\nfi\ntest -S \"${relay_socket:-/nonexistent}\" && printf 'socket=%s\\n' \"$relay_socket\"\n```\n\nIf the socket exists, inspect it before installing anything:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout\n(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's\n`relay socket-request` can give up sooner with \"Probe could not finish. Check\nyour connection and run setup again\"; on these paths that is the same latency,\nnot a setup problem. Retry the call once before reporting a blocker, and do not\nstart a second install or sign-in because of it.\n\nPreserve a working newer install. When the socket is absent, check for an\ninstalled-but-stopped copy before downloading: use `dpkg-query -W agent-relay`\nwhen `dpkg-query` exists and `systemctl --user status agent-relay.service` on\nLinux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry\nstatus first.\nUpdate an older install only when it lacks the setup contract or reports an\nolder version. A `404` from `/setup/status` means the installed build is too\nold for agent-driven setup and should be updated.\n\n## 2. Install or update with checksum verification\n\nUse a private temporary directory. Never skip the published SHA-256 check.\n\n### Ubuntu LTS, headless `.deb` (preferred)\n\nSelect the release architecture and install:\n\nThis path needs passwordless sudo or one human-approved sudo prompt for the\npackage install and `loginctl enable-linger`. Explain that prerequisite before\nstarting; never capture or relay a sudo password.\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb\" -o \"$relay_tmp/AgentRelay.deb\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb.sha256\" -o \"$relay_tmp/AgentRelay.deb.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#\" AgentRelay.deb.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nsudo apt-get install -y \"$relay_tmp/AgentRelay.deb\"\nsudo loginctl enable-linger \"$USER\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n```\n\nThe unit runs the bundled core headless: no display, X server, or GTK\nwindow is needed. This session's own GitHub subscriptions (section 6) go\nthrough the Desktop and need no CLI. The separate Agent Relay CLI is needed\nonly to subscribe a fleet-spawned or named agent; record whether it is present\nand at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app\ndiscovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:\n\n```sh\nrelay_cli=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay\" \\\n  \"$HOME/.npm-global/bin/agent-relay\" \\\n  \"$HOME/.agentworkforce/relay/bin/agent-relay\"\ndo\n  if test -x \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n    relay_cli=$candidate\n    break\n  fi\ndone\nif test -z \"$relay_cli\"; then\n  for relay_root in \\\n    \"$HOME/.local/share/mise/installs/node\" \\\n    \"$HOME/.nvm/versions/node\"\n  do\n    test -d \"$relay_root\" || continue\n    candidate=$(find -L \"$relay_root\" -mindepth 3 -maxdepth 3 \\\n      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)\n    if test -n \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n      relay_cli=$candidate\n      break\n    fi\n  done\nfi\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" integration subscribe --help >/dev/null\nelse\n  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\\n'\nfi\n```\n\nOn Linux without `dpkg`, use this per-user tarball installation under a\nversioned user directory. It is also the fallback on Ubuntu when `.deb`\ninstallation is unavailable and the human approves a per-user install. The\narchive contains a unit whose `/usr/bin` path is correct for packages, so\nrewrite only that `ExecStart` in the user copy:\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz\" -o \"$relay_tmp/AgentRelay.tar.gz\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256\" -o \"$relay_tmp/AgentRelay.tar.gz.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#\" AgentRelay.tar.gz.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmkdir \"$relay_tmp/extracted\"\ntar -xzf \"$relay_tmp/AgentRelay.tar.gz\" -C \"$relay_tmp/extracted\"\nrelay_tree=\"$relay_tmp/extracted/AgentRelay-linux-$relay_arch\"\ntest -x \"$relay_tree/usr/bin/agent-relay\"\nrelay_version=$(sed -n 's/^__version__ = \"\\([0-9A-Za-z._-]*\\)\"$/\\1/p' \\\n  \"$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py\")\ncase \"$relay_version\" in\n  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\\n' >&2; exit 1 ;;\nesac\nrelay_unit=\"$HOME/.config/systemd/user/agent-relay.service\"\nrelay_installed_version=\nif test -S \"${relay_socket:-/nonexistent}\"; then\n  relay_installed_version=$(curl -fsS --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)\nfi\nif test -z \"$relay_installed_version\" && test -r \"$relay_unit\"; then\n  relay_installed_version=$(sed -n \\\n    's#^ExecStart=.*/\\.local/lib/agent-relay/\\([^/ ]*\\)/.*#\\1#p' \\\n    \"$relay_unit\")\nfi\ncase \"$relay_installed_version\" in\n  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;\nesac\nif test -n \"$relay_installed_version\" && \\\n   test \"$relay_installed_version\" != \"$relay_version\" && \\\n   test \"$(printf '%s\\n%s\\n' \"$relay_version\" \"$relay_installed_version\" | sort -V | tail -n 1)\" = \"$relay_installed_version\"; then\n  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\\n' \\\n    \"$relay_installed_version\" \"$relay_version\" >&2\n  exit 1\nfi\nrelay_prefix=\"$HOME/.local/lib/agent-relay/$relay_version\"\nmkdir -p \"$relay_prefix\"\ncp -a \"$relay_tree/usr\" \"$relay_prefix/\"\nmkdir -p \"$(dirname \"$relay_unit\")\"\nsed \"s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#\" \\\n  \"$relay_tree/usr/lib/systemd/user/agent-relay.service\" >\"$relay_unit.tmp\"\nchmod 0644 \"$relay_unit.tmp\"\nmv \"$relay_unit.tmp\" \"$relay_unit\"\ngrep -F \"ExecStart=$relay_prefix/usr/\" \"$relay_unit\" | grep -q -- ' --headless$'\nif ! loginctl show-user \"$USER\" -p Linger | grep -qx 'Linger=yes'; then\n  sudo loginctl enable-linger \"$USER\"\nfi\nsystemd-analyze --user verify \"$relay_unit\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n# List the app in the desktop's app launcher (no-op on a headless server).\n# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the\n# entry the first time it is opened.\nif test -x \"$relay_prefix/usr/bin/agent-relay-desktop\"; then\n  \"$relay_prefix/usr/bin/agent-relay-desktop\" --install-launcher || true\nfi\n```\n\nThe unit's `ExecStart` names the archive's own path under `/usr/`, either the\nlauncher or the bundled `agent-relay-probe`; the rewrite moves whichever it is\nunder `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its\nfull path, never the bare `agent-relay`, which is also the CLI's name.\n\nDo not improvise Alpine or RHEL distribution packages. On a compatible\nsystemd host without `dpkg`, use only the verified per-user tarball path above;\nnon-systemd hosts remain unsupported by this Linux workflow.\n\n### macOS DMG\n\n```sh\ncase \"$(uname -m)\" in\n  arm64) relay_arch=arm64 ;;\n  x86_64) relay_arch=x64 ;;\n  *) printf 'Unsupported Mac architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg\" -o \"$relay_tmp/AgentRelay.dmg\"\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg.sha256\" -o \"$relay_tmp/AgentRelay.dmg.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#\" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmount_point=$(hdiutil attach -nobrowse -readonly \"$relay_tmp/AgentRelay.dmg\" | awk '/\\/Volumes\\// {sub(/^.*\\/Volumes\\//,\"/Volumes/\"); print; exit}')\nincoming_id=$(defaults read \"$mount_point/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\nif test \"$incoming_id\" != com.agentrelay.desktop; then\n  hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\\n' \"$incoming_id\" >&2\n  exit 1\nfi\nif test -d \"/Applications/Agent Relay.app\"; then\n  existing_id=$(defaults read \"/Applications/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\n  if test \"$existing_id\" != com.agentrelay.desktop; then\n    hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\\n' \"$existing_id\" >&2\n    exit 1\n  fi\nfi\nosascript -e 'tell application \"Agent Relay\" to quit' 2>/dev/null || true\nditto \"$mount_point/Agent Relay.app\" \"/Applications/Agent Relay.app\"\nhdiutil detach \"$mount_point\"\nopen -a \"Agent Relay\"\n```\n\nIf `/Applications` needs administrator access, use `sudo ditto` only after the\nhuman has authorized installation. Do not remove or overwrite another app with\nan unexpected bundle identity.\n\nAfter either install, wait up to 30 seconds for the pointer:\n\n```sh\napp_sock=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nfor _ in $(seq 1 30); do\n  test -r \"$HOME/.agentworkforce/desktop/relay-socket\" && break\n  test \"$(uname -s)\" = Darwin && test -S \"$app_sock\" && break   # the app is already listening\n  sleep 1\ndone\nrelay_socket=$(sed -n '1p' \"$HOME/.agentworkforce/desktop/relay-socket\" 2>/dev/null)\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Darwin && test -S \"$app_sock\"; then\n  relay_socket=$app_sock\nfi\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock\"\nfi\ntest -S \"$relay_socket\"\ncurl -fsS --unix-socket \"$relay_socket\" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'\n```\n\n## 3. Sign in by device approval\n\nBefore choosing a workspace, check what the human already has. These commands\nonly read state. The CLI checks run only when section 2 found a `relay_cli`;\nnever call the `.deb`'s `/usr/bin/agent-relay` launcher for them:\n\n```sh\ncurl -sS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'\nif test -n \"${relay_cli:-}\"; then\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nSign in to the workspace they already use. Pick a different or new workspace\nonly when the human explicitly asks for it.\n\nFor a multi-server rollout, obtain the existing enterprise workspace UUID from\nthe human and pass it explicitly on every server. Do not guess it and do not\nuse `{}` when the target workspace is known: that could select a default/free\nworkspace and split the fleet. Use `{}` only for an individual setup where the\nhuman has confirmed that the reusable login's current workspace is intended.\n\n```sh\nrelay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'\nsign_in_payload=$(jq -nc --arg workspace \"$relay_workspace_uuid\" '{workspace:$workspace}')\nsign_in=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nIf sign-in reports that older upload schedules could not be inspected, first\ninspect the user's legacy cron, launchd, and user-service upload schedules.\nAfter completing that safety check, retry the original request with the\nacknowledgement added; never use it merely to suppress the error:\n\n```sh\nsign_in_payload=$(printf '%s\\n' \"$sign_in_payload\" | \\\n  jq '. + {acknowledge_uninspected_schedules:true}')\nsign_in=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nPrint a device link and code only when the response actually contains a code:\n\n```sh\nuser_code=$(printf '%s\\n' \"$sign_in\" | jq -r '.data.user_code // empty')\nif test -n \"$user_code\"; then\n  verification_url_complete=$(printf '%s\\n' \"$sign_in\" | \\\n    jq -r '.data.verification_url_complete // empty')\n  if test -n \"$verification_url_complete\"; then\n    printf 'Open %s and approve code %s\\n' \"$verification_url_complete\" \"$user_code\"\n  else\n    verification_url=$(printf '%s\\n' \"$sign_in\" | \\\n      jq -r '.data.verification_url // empty')\n    printf 'Open %s and enter code %s\\n' \"$verification_url\" \"$user_code\"\n  fi\nfi\n```\n\nIf the response is `signed_in` with `reused_login:true`, the app reused an\neligible same-origin CLI or desktop login and intentionally issued no device\ncode. Confirm the returned workspace id and name with the human rather than\nwaiting for a code, then continue only if it is the intended workspace.\n\nFor `pending_approval`, the human can approve from any phone or browser. Do not\ncreate another code while this one is pending. A `preparing` response is also\nnormal: poll `/setup/status` at the reported interval. Preparing local history\ncan take about a minute when the app reuses an existing `agent-relay` CLI login.\nPoll both states until sign-in finishes. The reason for a failure is in\n`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so\nprint it, and map the known messages to their fix instead of dumping raw state:\n\n```sh\nwhile :; do\n  state=$(curl -sS --unix-socket \"$relay_socket\" http://relay/setup/status)\n  phase=$(printf '%s' \"$state\" | jq -r '.data.sign_in // .error.code')\n  case \"$phase\" in\n    signed_in)\n      printf '%s\\n' \"$state\" | jq \\\n        '{sign_in: .data.sign_in, workspace: .data.workspace}'\n      break\n      ;;\n    preparing|pending_approval) ;;\n    denied|expired|error)\n      msg=$(printf '%s' \"$state\" | jq -r '.data.sign_in_message // .error.message // \"no message reported\"')\n      printf 'Sign-in %s: %s\\n' \"$phase\" \"$msg\" >&2\n      case \"$msg\" in\n        *\"older managed history uploader\"*)\n          printf 'See \"Sign-in blocked by a legacy uploader\" under Recovery.\\n' >&2 ;;\n        *\"older upload schedules\"*)\n          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\\n' >&2 ;;\n        *) printf '%s\\n' \"$state\" | jq '.data' >&2 ;;\n      esac\n      exit 1\n      ;;\n  esac\n  sleep \"$(printf '%s' \"$sign_in\" | jq -r '.data.interval // 5')\"\ndone\n```\n\n## 4. Apply the agent-led defaults and register this session\n\nRead the current sharing mode before changing it. `/setup/status` reports it as\n`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is\nuploading yet). The probe reports the same field, `sharing_mode`, in\n`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -r '.data.sharing_mode'\n```\n\nOn a fresh install, or when it already reports `new`, use `new`. When an\nexisting install reports `all` (which also uploads past sessions, so it is\nbroader than this skill's default) or `selected`, tell the human the current\nmode and ask whether to keep it or change it to `new`. Never change it silently.\nSet `relay_sharing_mode` below to the human's answer.\n\nThen set and verify all three agent-led defaults even when the app's `/setup/*`\nbootstrap already applied them. Sharing mode `new` uploads every new session;\nauto-activation puts every existing live session and every future session on\nthe relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:\n\n```sh\nrelay_sharing_mode=new   # or the existing mode the human chose to keep\ndirect_delivery=$(curl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' http://relay/setup/direct-delivery)\nprintf '%s\\n' \"$direct_delivery\" | jq\nif ! printf '%s\\n' \"$direct_delivery\" | jq -e '.ok and .data.direct_delivery'; then\n  if printf '%s\\n' \"$direct_delivery\" | jq -e '.error.code == \"managed_policy\"' >/dev/null; then\n    printf 'Organization-managed Claude settings forbid direct delivery.\\n' >&2\n  fi\n  exit 1\nfi\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d \"$(jq -nc --arg mode \"$relay_sharing_mode\" '{mode:$mode}')\" \\\n  http://relay/setup/sharing | jq\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' \\\n  http://relay/setup/auto-activate | jq\nregister=$(curl -sS --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/register)\nprintf '%s\\n' \"$register\" | jq\nregistration_status=$(curl -sS --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status)\nprintf '%s\\n' \"$registration_status\" | \\\n  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'\nprintf '%s\\n' \"$registration_status\" | jq -e \\\n  '.ok and (.data.session.id | type == \"string\" and length > 0) and\n   .data.session.registered == true and .data.session.direct_delivery == true'\n```\n\nDirect delivery is checked first so a managed-policy refusal stops setup\nbefore auto-activation or upload settings are changed. Report that refusal\nclearly; never claim the three-default setup completed.\n\nSharing mode and auto-activate are different settings: the former\ncontrols upload eligibility and the latter controls Relay registration. The\nsetup flow requires both.\n\n`POST /register` discovers the nearest live Codex or Claude ancestor. A session\ninside tmux over SSH is valid. Never pass a session id or token in the body.\nThe default name includes a 128-bit session-derived suffix, so dozens of\nsessions in the same checkout receive distinct `name@direct` addresses. Save\nand report the address from `/setup/status` for each session; never reuse one\nsession's address for another. `/register` may omit the session id or\ndirect-delivery state, so its response alone is not verification. Require the\nstatus response to show this session's non-empty id, `registered:true`, and\n`session.direct_delivery:true` as above. An app fix is expected to add those\nfields to `/register`, but the status check remains authoritative.\n\n## 5. Create and test the webhook\n\nPerform this section only when the human requested a webhook (or explicitly\nasked for the full end-to-end setup). Otherwise skip it; webhook creation is a\npersistent external mutation, not an install prerequisite.\n\nCapture the one-time secret without echoing it:\n\n```sh\numask 077\nhook_file=$(mktemp)\ncurl -sS --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/webhooks >\"$hook_file\"\njq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' \"$hook_file\"\n```\n\nWhen `created:true`, send a unique marker. Initialize every temporary path so\ncleanup can name and delete exact files without `-f` or globs:\n\n```sh\nhook_config=\nmarker=\nwebhook_post_ok=false\nwebhook_post_status=0\nif test \"$(jq -r '.data.created // false' \"$hook_file\")\" = true && \\\n   test \"$(jq -r '.data.secret // empty' \"$hook_file\")\" != ''; then\n  hook_url=$(jq -r '.data.url' \"$hook_file\")\n  hook_secret=$(jq -r '.data.secret' \"$hook_file\")\n  hook_config=$(mktemp)\n  chmod 600 \"$hook_config\"\n  printf 'header = \"Authorization: Bearer %s\"\\n' \"$hook_secret\" >\"$hook_config\"\n  marker=\"agent-relay-webhook-test-$(date +%s)\"\n  if curl -fsS --config \"$hook_config\" -X POST \"$hook_url\" \\\n      -H 'Content-Type: application/json' \\\n      -d \"{\\\"text\\\":\\\"$marker\\\",\\\"source\\\":\\\"agent-driven-setup\\\"}\"; then\n    webhook_post_ok=true\n  else\n    webhook_post_status=$?\n  fi\nelse\n  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\\n' >&2\nfi\nif test -n \"$hook_config\" && test -e \"$hook_config\"; then\n  rm -- \"$hook_config\"\nfi\nif test -e \"$hook_file\"; then\n  rm -- \"$hook_file\"\nfi\nunset hook_secret\nif test \"$webhook_post_ok\" = true; then\n  printf 'Webhook test sent; end this turn and wait for marker: %s\\n' \"$marker\"\nelif test -n \"$marker\"; then\n  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\\n' \\\n    \"$webhook_post_status\" >&2\n  exit \"$webhook_post_status\"\nfi\n```\n\nDo not claim success merely because the POST returned 2xx, and do not sleep or\npoll for the injected message during the same turn. Relay injects only after\nthe session becomes idle between turns. After the POST and exact-file cleanup,\nend the current turn by saying that setup is waiting for the exact marker. On\nthe next turn, confirm that the injected body contains that marker and its\nAgent Relay header contains a full message id; record that id in the final\nevidence. If a polling consumer is part of the setup, also observe that same id\nthere before declaring the webhook test complete. If the webhook already\nexisted, its secret is correctly returned as null; do not revoke or recreate it\nwithout human authorization. Ask for the existing secret or report that the\ndelivery test could not be repeated.\n\n## 6. Subscribe requested integrations\n\nRequire the provider and repository from the human. A GitHub pull request needs\none resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's\nreviews, review comments, conversation comments and check runs to that glob by\nthe PR they reference, so no other glob is needed: nothing is written under\n`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or\n`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This\nworks on every released Desktop and is the path to use today. If a review or\ncomment then never arrives, read it back in relayfile at its own path (the\ntable in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event\nnever reached relayfile\n([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),\nnot that the subscription is wrong.\n\nFirst find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions\n(below) and it is the client for the one-command form once that ships:\n\n```sh\nrelay_probe=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay-probe\" \\\n  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n  \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"\ndo\n  if test -x \"$candidate\"; then relay_probe=$candidate; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\nprintf 'relay_probe=%s\\n' \"${relay_probe:-none}\"\n```\n\nA running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the\nother candidates are the copies bundled by the `.deb`, the macOS app, and the\nper-user tarball. Then subscribe through the socket. On macOS use the probe\nclient when there is one: the system `curl` hides a Codex session's identity\nthere and is refused `not_a_relay_session`, so a Codex session with no probe\nstops instead. `curl` is correct for Claude Code and on Linux:\n\n```sh\n# One client for every socket request in this section and in undo: the probe\n# on macOS (system curl hides a Codex session there), curl elsewhere.\nrelay_req() {  # METHOD PATH [JSON body]\n  if test \"$(uname -s)\" = Darwin && test -n \"${relay_probe:-}\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\\n' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' -d \"$3\" \"http://relay$2\"\n  else\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n\n# This PR's subscriptions, in whichever form they were made. Fails, rather than\n# answering \"none\", when the status cannot be read: both callers stop then.\npr_url='https://github.com/OWNER/REPO/pull/NUMBER'\npr_resources() {\n  relay_status=$(relay_req GET /setup/status) || return 1\n  # -s reads the whole body as one list, so an empty body is an error too.\n  printf '%s\\n' \"$relay_status\" | jq -rs --arg url \"$pr_url\" \\\n    --arg short 'OWNER/REPO#NUMBER' \\\n    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \\\n    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '\n    if length == 1 and .[0].ok == true\n       and (.[0].data.integrations | type) == \"array\" then\n      .[0].data.integrations[] | select(.provider == \"github\") | .resource\n      | select(. == $url or . == $short or startswith($url + \"/\")\n               or startswith($pulls) or startswith($issues))\n    else\n      error(\"Agent Relay status is unreadable; no subscription was changed.\")\n    end'\n}\n\nheld=$(pr_resources) || exit 1\nif printf '%s\\n' \"$held\" | grep -Fqx -e \"$pr_url\" -e 'OWNER/REPO#NUMBER'; then\n  # The one-command subscription is a single complete request: nothing to add.\n  printf 'Already subscribed:\\n%s\\n' \"$held\"\nelif test -z \"$held\" && test -n \"${relay_probe:-}\" && \\\n     \"$relay_probe\" relay --help 2>&1 | grep -q '^  subscribe'; then\n  # The one-command form (below), only for a PR with no subscription yet and\n  # only when the installed probe has it.\n  \"$relay_probe\" relay subscribe \"$pr_url\" | jq\nelse\n  relay_req POST /integrations/subscribe \\\n    \"$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \\\n      '{provider:\"github\",resource:$resource}')\" | jq\nfi\nrelay_req GET /setup/status | jq -c '.data.integrations'\n```\n\nRequire `.ok` and `.data.subscribed` to be `true`, and the entry in the status\nlist to be `ready: true`. A repeated request returns HTTP 409\n`conflict` (\"already subscribed\"). That is success only for a binding made on\nor after 2026-09-19. Earlier bindings predate PR-identity matching\n(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews\nand comments. If the binding may be older, or you cannot tell, recreate it\nonce: `relay_req DELETE /integrations/subscribe` with the same body, then\nsubscribe again. Verified on\nDesktop 2026.10.6 with both the probe client and `curl`.\n\n**One-command form (not yet released).** `relay-desktop#216` adds\n`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`\n(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription\nthat the Desktop correlates with the PR's reviews, comments, and checks. It is\nabsent from Desktop 2026.10.6, where it fails with `unrecognized subcommand\n'subscribe'`, so do not lead with it. Use it only when the installed probe\nadvertises it. The block above makes that choice, and first checks the\nsession's existing subscriptions. A pull request already subscribed with the\none-command form is left alone. A pull request already holding\nthe number glob answers 409 `conflict` on a repeat; recreate that binding once\nif it may predate 2026-09-19 (see above). Extra `reviews`, `status` or\n`issues/NUMBER/comments` globs from an earlier version of this skill never\ndeliver; unsubscribe them.\n\nOnce released, re-test it before relying on its details; the behavior described\nin that PR (a repeat answering `\"already_subscribed\":true`, `--remove` to end it,\nand a numeric subscription covering reviews, comments and checks) has not been verified here.\n\nRefusals and what they mean:\n\n- `not_a_relay_session`, \"Register this session before subscribing it\": run\n  section 4's `POST /register` first.\n- `not_a_relay_session`, \"already managed by this computer's relay\" from\n  `/register`: this session was started by the Agent Relay fleet broker, not\n  the Desktop. Use the workspace CLI below instead.\n- `refused` or `busy`: an earlier subscription is still being made or cleaned\n  up; repeat the command shortly.\n\nA fleet-spawned session, or an operator subscribing a named agent, uses the\n`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in\n`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let\nthe worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail\nwith `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`\nis set:\n\n```sh\npull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'\nrelay_cli_major=\nif test -n \"${relay_cli:-}\"; then\n  relay_cli_major=$(\"$relay_cli\" --version 2>/dev/null | sed -n 's/^[^0-9]*\\([0-9][0-9]*\\)\\..*/\\1/p' | sed -n '1p')\nfi\nif test -n \"$relay_cli_major\" && test \"$relay_cli_major\" -ge 13; then\n  \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelif test -n \"$relay_cli_major\"; then\n  # 12.x and older: keep the ambient agent token from displacing the key.\n  env -u RELAY_AGENT_TOKEN \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelse\n  # No usable installed CLI: run the fixed release without installing it.\n  npx -y agent-relay@13 integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nfi\n```\n\nUse the `relay_cli` found in section 2, never a bare `agent-relay`: on a\n`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may\nresolve to it or to a different, older CLI than the one whose version was\nchecked.\n\nThe CLI path follows `orchestrating-agent-relay`, which subscribes the same\nsingle `pulls/NUMBER/**` glob. Never put the workspace key in argv.\n\nMake the subscribe step a required post-create step in the agent's PR\nworkflow: whenever it authors a PR, it subscribes its own live session\nimmediately, without waiting for an operator to name the PR. This is the\nauthored-PR pattern from `orchestrating-agent-relay`; it covers every future PR\nthe agent authors without subscribing unrelated repository traffic. The\nDesktop removes the subscription itself after the PR closes or merges.\nFor real GitHub verification, use a harmless event the human authorized\non that PR (for example, a test conversation comment and a requested bot\nreview). After causing the event, do not wait or poll within the active turn:\nend the turn saying which event marker is expected. Confirm the injected event\nand record its full message id on the next turn after Relay has delivered it.\nDo not create a comment, review, or rerun without authorization. A successful\nsubscribe response alone does not prove end-to-end delivery.\n\n## 7. Coexist with a REST-polling MCP\n\nDo not disable an existing polling consumer. Desktop injection acknowledges\nonly this registered agent's delivery queue and does not advance a separate\nworkspace consumer's cursor. A polling MCP should use its own identity/cursor,\nnot this session agent's `/v1/deliveries` token.\n\nInjected text contains both the full Relaycast message id and a short `ref`.\nWhen polling and injection can surface the same workspace message, deduplicate\non the full message id before acting. During verification, leave the poller\nrunning and observe the test message there. Then end the current turn so Relay\ncan inject it, and on the next turn confirm the same full id arrived while the\nagent acted only once.\n\n## 8. Final verification and report\n\nRead status again:\n\n```sh\ncurl -sS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'\n```\n\nRequire all three defaults before declaring setup complete:\n\n```sh\ncurl -fsS --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -e --arg mode \"${relay_sharing_mode:-new}\" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'\n```\n\nReport the exact version, `signed_in`, signed-in workspace id and name, sharing\nmode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,\nuploader health, session address, direct-delivery state, webhook test marker,\nsubscriptions, real GitHub event evidence, and polling-coexistence result.\nSeparate verified facts from steps that still require a human or external\nevent.\n\n## Recovery and undo\n\n- **Socket missing or slow:** check `systemctl --user status agent-relay.service`\n  on Linux or `open -a \"Agent Relay\"` on macOS. Confirm the pointer names a\n  socket. Never delete a live socket; restart the owning service/app. A reply\n  that takes up to about 30 seconds is the known latency in section 1\n  (relay-desktop#333), not a fault: allow 60 seconds and retry once.\n- **`not_a_relay_session`:** the command is not a descendant of a supported\n  live Codex/Claude session, or the session id/process start no longer matches.\n  Run it through this agent's shell tool. In tmux, confirm the agent process and\n  shell share the pane's process tree.\n- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message \"An older\n  managed history uploader is active. Stop it explicitly before enabling this\n  probe.\"): the probe counts any of these legacy `ai-hist push` registrations as\n  active, even when idle: the file\n  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded\n  launchd label `com.ai-hist.push`, or a crontab line containing\n  `# ai-hist push (managed)`. Check each, then with the human's approval unload\n  and move aside (do not delete) what exists. Create the backup directory first,\n  use a unique no-clobber destination, and confirm the move before retrying:\n\n  ```sh\n  # bootout exits non-zero when the label was never loaded; that is fine, so\n  # judge success by whether the label is still loaded, not by its exit code.\n  launchctl bootout \"gui/$(id -u)/com.ai-hist.push\" 2>/dev/null || true\n  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then\n    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2\n    exit 1\n  fi\n  plist=\"$HOME/Library/LaunchAgents/com.ai-hist.push.plist\"\n  if test -e \"$plist\"; then\n    backup_dir=\"$HOME/.agentworkforce/backup\"\n    mkdir -p \"$backup_dir\"\n    mv -n \"$plist\" \"$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)\"\n    test ! -e \"$plist\" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }\n  fi\n  ```\n\n  If instead the marked cron line is the cause, back up the full crontab first\n  and remove only that line, so the change can be reversed with\n  `crontab <backup-file>`:\n\n  ```sh\n  mkdir -p \"$HOME/.agentworkforce/backup\"\n  cron_backup=\"$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)\"\n  crontab -l > \"$cron_backup\" && test -s \"$cron_backup\" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }\n  grep -vF '# ai-hist push (managed)' \"$cron_backup\" | crontab -\n  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }\n  ```\n\n  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run\n  `/setup/sign-in` with the same payload.\n- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the\n  request. Restart after `expired` or `denied` to obtain a new code.\n- **Older schedules could not be inspected:** inspect the user's legacy cron,\n  launchd, or user-service upload schedules first. Only after that inspection,\n  retry `/setup/sign-in` with the original payload plus\n  `\"acknowledge_uninspected_schedules\":true`. This flag records a completed\n  safety check; never send it merely to silence an error.\n- **`not_allowed` from `/register`:** enable the app's self-registration\n  setting. Do not bypass it with workspace credentials.\n- **Managed Claude policy:** if direct delivery reports `managed_policy`, the\n  organization controls `crossSessionInbound`; report the policy block rather\n  than modifying managed settings.\n- **Undo registration:** `curl -sS --unix-socket \"$relay_socket\" -X DELETE http://relay/register | jq`.\n- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,\n  `relay_req`, and `pr_resources` defined, remove every subscription the\n  session holds for the pull request, in whichever form it was made. On macOS\n  `relay_req` uses the probe, and a Codex session without one stops instead of\n  sending a `curl` request that cannot be identified:\n\n  ```sh\n  held=$(pr_resources) || exit 1\n  printf '%s\\n' \"$held\" | while IFS= read -r resource; do\n    test -n \"$resource\" || continue\n    relay_req DELETE /integrations/subscribe \\\n      \"$(jq -nc --arg resource \"$resource\" '{provider:\"github\",resource:$resource}')\" | jq\n  done\n  relay_req GET /setup/status | jq -c '.data.integrations'\n  ```\n\n  Require the final list to hold none of that pull request's resources.\n- **Undo a webhook:** `curl -sS --unix-socket \"$relay_socket\" -X DELETE http://relay/webhooks | jq`.\n- **Undo direct delivery:** POST `{\"enabled\":false}` to\n  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed\n  organization policy still wins.\n- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to\n  `/setup/sharing`. Ask before changing it when the earlier value is unknown.\n- **Auto-activate accidentally enabled:** POST `{\"enabled\":false}` to\n  `/setup/auto-activate`. This does not remove existing registrations.\n- **Uninstall:** stop/disable the user service before removing the Linux\n  package, or quit the Mac app before removing it. Do not delete app data or\n  revoke webhooks unless the human explicitly asks for data removal.\n",
-  "setting-up-agent-relay-sessions": "# Set Up Agent Relay Session Handoff\n\nDrive the whole onboarding from this agent's own shell and MCP tools. Do **not**\nhand the person the six-step Markdown guide and ask them to click through the\napp and the dashboard.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the desktop app is installed, signed in to the **intended workspace**, the\n  uploader is healthy, and this session is registered with direct delivery on;\n- the **agent-sessions cloud MCP** is installed in this project and loaded by\n  this session, so the handoff tools (`list_relay_agents`, `send_relay_message`,\n  `read_relay_conversation`, `check_relay_inbox`, `get_shared_session`,\n  `get_shared_session_context`, `search_shared_sessions`) are available;\n- a live round trip is proven when a teammate is online: this agent messages the\n  teammate's agent, **reads the teammate's real session back** with\n  `get_shared_session_context`, and the teammate reads this session and replies.\n  When no teammate is online yet, the fallback is the roster plus this person's\n  own uploaded session reading back cleanly — reported as self-verified, not as a\n  proven two-way handoff.\n\n## Requires\n\nThis skill builds on `setting-up-agent-relay-desktop` (verified install, sign-in,\nregistration, agent-led defaults). If that skill is **not installed** in this\nagent, stop, tell the person, and have them install the companions together,\nthen restart the agent. Do not improvise the install or sign-in from memory.\n\n- prpm: `npx prpm install collections/agent-relay-setup --as claude --global -y`\n- skills.sh: `npx skills add https://github.com/AgentWorkforce/skills --skill setting-up-agent-relay-desktop --skill setting-up-agent-relay-sessions`\n- Codex: do not use prpm's `--as codex` (it drops paragraphs and writes under `~/.agents/skills`, which Codex does not load as its global skill folder). Mirror both installed `SKILL.md` files into `~/.codex/skills/<name>/` with the loop in **Install this skill (and its dependency)** below.\n\n## The only human steps\n\nEverything else is automatable; be honest that these are not. **Ask for all of\nthem up front, before touching anything** — the token in particular is needed\nonly at section 3, but minting it and exporting it into the launching\nenvironment takes the person a few minutes, so have them start it while the\ndesktop install and sign-in run:\n\n1. **Approve one Google device-login link** — only when no reusable `agent-relay`\n   CLI/desktop login exists. A reused login needs zero clicks.\n2. **Provide one Bearer token** minted in the dashboard's **\"Connect your agent\"**\n   card. No setup route returns this token by design. **Do not have the person\n   paste it into this conversation** — the uploader shares this session's prompts\n   with teammates, so a pasted secret would become teammate-readable. Instead the\n   person puts it into the **environment that launches their agent** (or an OS\n   keychain / a mode-0600 file) via a shell *they* run, and this agent references\n   it only by variable name — never by value. See **Token handling** below.\n3. **Same workspace, both sides.** The teammate (or workspace admin) must have\n   invited this person's email to the **shared** workspace — two agents can only\n   reach each other inside one workspace. Confirm the workspace id matches on\n   both machines; do not guess it.\n\nOne structural note so expectations are right: there is **no automatic ack** to\nthe sender when a handoff is picked up, and **no partial session sharing** — a\nsession is on-or-off on the relay. Confirm a handoff by activity, not a push.\n\n## How this composes with `setting-up-agent-relay-desktop`\n\nThis skill is a thin layer on a working desktop. The desktop skill owns install,\nsign-in, defaults and self-registration; this one owns only the agent-sessions\ncloud MCP and the live handoff. Section 2 checks the desktop prerequisite and,\nif it is not met, invokes `/setting-up-agent-relay-desktop` to completion and\nreturns here. Keep the `/setup/*` details in that one skill so a contract change\nupdates it once.\n\n## Install this skill (and its dependency) for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage **and** the desktop skill it depends on, then mirror both unchanged\n`SKILL.md` files where Codex loads global skills:\n\n```sh\nfor pkg in setting-up-agent-relay-sessions setting-up-agent-relay-desktop; do\n  npx prpm install \"@agent-relay/$pkg\" --as claude --global -y\n  codex_skill=\"$HOME/.codex/skills/$pkg\"\n  mkdir -p \"$codex_skill\"\n  install -m 0644 \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\n  cmp \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\ndone\n```\n\nWith skills.sh instead, use the command under **Requires**; it installs into each agent's skills folder directly, so the manual Codex mirror below is only for the prpm route.\n\nDo not use prpm's `--as codex` conversion for these packages: it writes under\n`~/.agents/skills`, which Codex does not load as its global skill folder, and it\ndrops explanatory paragraphs from the Markdown workflow. Confirm both final\npaths explicitly before continuing.\n\n## Why ordering matters\n\nMCPs load at agent **startup**. The agent-sessions MCP must be installed\n**before** the session that will use it starts. A session already running when\nthe MCP was added has no handoff tools and must be **restarted**. Install the\nMCP (section 3) before relying on the tools (sections 4–5); if this very session\npredates the MCP, say so and restart it rather than reporting missing tools as a\nfailure.\n\n## Token handling\n\nThe token must never land in the agent conversation, in a Relay message, in\nprocess argv, or in the repo. Three places leak it, and this skill avoids all\nthree:\n\n- **The chat** — this session is uploaded and teammate-readable, so a token\n  pasted to the agent leaks to the workspace. The person sets it themselves (see\n  below); the agent only ever sees the variable **name**.\n- **Process argv** — a token interpolated into `claude mcp add --header\n  \"... Bearer $TOKEN\"` is visible to `ps` and gets written literally into\n  `~/.claude.json`. Pass the unexpanded placeholder `${AGENT_RELAY_SESSIONS_TOKEN}`\n  instead; Claude Code expands `${VAR}` in MCP headers from the environment at\n  launch, so the stored config holds only a reference and argv holds only the\n  literal `${…}`. **This expansion exists only in Claude Code ≥ 2.1.119** — an\n  older client sends the placeholder literally and auth fails, so check the\n  version first (section 3) and update Claude rather than inlining the token.\n- **The launching environment** — both CLIs read the token from an environment\n  variable (`${VAR}` for Claude, `--bearer-token-env-var` for Codex), so the\n  variable must exist in the environment that **launches the agent**, not in a\n  transient shell-tool subprocess (which cannot alter its parent or a later\n  process).\n\nUse the single variable name `AGENT_RELAY_SESSIONS_TOKEN` throughout. Keep the\none-time entry separate from durable supply:\n\n- **One-time, into the current shell** (non-echoing, run by the person, never\n  the agent): `read -rs AGENT_RELAY_SESSIONS_TOKEN && export AGENT_RELAY_SESSIONS_TOKEN`,\n  then launch the agent from *that* shell. Do **not** add this `read` to a shell\n  profile — every shell that sources the profile would block waiting for input.\n- **Durable across restarts:** store the token in the OS keychain or a mode-0600\n  file, and have the launcher export it **non-interactively**, e.g.\n  `export AGENT_RELAY_SESSIONS_TOKEN=\"$(security find-generic-password -s agent-relay-sessions -w)\"`\n  (macOS keychain) or from a 0600 file. Put that line in a dedicated launcher the\n  person starts the agent from — not an interactive prompt in the profile.\n\nThe agent never prints the value; verify presence only with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"`.\n\n## 0. Preflight: collect the human inputs first\n\nBefore section 1, tell the person what they need and ask for it in one message:\n\n1. the **shared workspace id** (or the teammate/admin who invited them);\n2. a **Bearer token** minted in the dashboard's \"Connect your agent\" card for\n   that workspace, stored by *them* as `AGENT_RELAY_SESSIONS_TOKEN` in the\n   environment that launches their agent (see **Token handling** — never pasted\n   into this chat);\n3. the **teammate's relay address** for the round trip, if one will be online.\n\nBefore sending that message, check what this machine already has. If an Agent\nRelay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not\nthe `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only\nchecks. Without one, section 2 reads the signed-in workspace from\n`/setup/status` instead. The CLI is optional for this skill: check with\n`command -v agent-relay` and `agent-relay --version`, and do not install or\nupgrade it just for these checks.\n\n```sh\nagent-relay cloud whoami       # signed in, and as whom\nagent-relay workspace active   # the active Cloud workspace (keys stay masked)\nagent-relay cloud workspaces   # every workspace this login can use, with ids\nagent-relay status             # workspace, cloud login and local broker\n```\n\nIf the active workspace is already the shared one, confirm it with the person\ninstead of asking them to look it up. Never switch to or create another\nworkspace unless they explicitly ask.\n\nCheck presence without printing the value:\n\n```sh\ntest -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\" && echo token=present || echo token=missing\n```\n\nA missing token does **not** block sections 1–3: the MCP config stores only a\n`${AGENT_RELAY_SESSIONS_TOKEN}` reference, never the value, so it can be added\nnow. Do the desktop work and add the MCP, then have the person restart the agent\n**once**, from an environment that exports the token, so that single restart both\nloads the MCP and supplies the credential. Sections 4–5 are gated on that\nrestart. If the person would rather not defer, they can export the token and\nrestart first, which then costs a second restart only if the MCP was added after.\n\n## 1. Confirm the host and this session\n\nRun every command from this agent's own shell tool, and only from a **genuine\ninteractive** Claude Code or Codex session. The app identifies the caller from\nkernel credentials and resolves its process ancestry against discovered live\nsessions, so a command from an unrelated terminal — or from a non-interactive\n`codex exec` / `claude -p` run — is rejected with `not_a_relay_session`. (This\nis verified: a plain SSH shell and a `codex exec` invocation are both refused;\nan interactive session is admitted.)\n\n```sh\nuname -s; uname -m\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\n```\n\nDefine the request helper once per shell. It finds the private setup socket\nwithout printing private files and uses the desktop's `agent-relay-probe` on\nmacOS (the system `curl` hides a Codex session's identity there and is refused\n`not_a_relay_session`), `curl` elsewhere, and stops with a message for a macOS\nCodex session that has no probe:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Linux; then\n  for c in \"${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock\" \"/run/user/$(id -u)/agent-relay/relay.sock\"; do\n    if test -S \"$c\"; then relay_socket=$c; break; fi\n  done\nfi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Darwin; then   # pointer file missing: use the app's own socket\n  c=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\n  if test -S \"$c\"; then relay_socket=$c; fi\nfi\nrelay_probe=\nfor c in \"$HOME/.local/bin/agent-relay-probe\" \\\n         /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n         \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"; do\n  if test -x \"$c\"; then relay_probe=$c; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then   # per-user tarball\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\n# relay_req METHOD PATH [JSON-BODY]\nrelay_req() {\n  if ! test -S \"${relay_socket:-/nonexistent}\"; then\n    echo 'No Agent Relay socket found; start Agent Relay (the desktop) and retry.' >&2\n    return 1\n  fi\n  if test \"$(uname -s)\" = Darwin && test -n \"$relay_probe\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    echo 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename\n    printf '%s' \"$3\" | curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' --data-binary @- \"http://relay$2\"\n  else\n    curl -sS --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add\n`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a\nfailure. The probe's `relay socket-request` can give up sooner with \"Probe\ncould not finish. Check your connection and run setup again\"; on these paths\nthat is the same latency, not a setup problem. Retry once before reporting a\nblocker, and do not rerun desktop setup because of it.\n\n## 2. Make sure the desktop is set up first\n\nSession handoff needs a signed-in, healthy desktop underneath it. If the socket\nis missing, or `/setup/status` returns `404`, or sign-in/uploader/registration\nare not in the finished state below, **invoke the `setting-up-agent-relay-desktop`\nskill** (`/setting-up-agent-relay-desktop`; if it is not installed, see **Requires**), let it run to completion, and then\nreturn to section 2's verification. Do not re-implement its install, sign-in, or\n`/setup/*` steps here — that skill is the single source of truth for them, and\nthis skill resumes once it reports a registered, signed-in session.\n\nVerify the desktop state this skill depends on:\n\n```sh\nrelay_req GET /setup/status | jq '{\n  version: .data.version,\n  sign_in: .data.sign_in,\n  workspace: .data.workspace,\n  sharing_mode: .data.sharing_mode,\n  uploader: .data.uploader,\n  direct_delivery: .data.direct_delivery,\n  session: .data.session,\n  defaults_error: .data.defaults_error\n}'\n```\n\nRequire all of these before continuing, and stop with a clear message if any\nfails. `/setup/status` reports sign-in as the string `sign_in` (match the desktop\nskill), and the flag that actually governs whether **this** session's handoff\nreplies arrive live is the session-level `session.direct_delivery`, not the\ntop-level default — require both:\n\n```sh\nrelay_req GET /setup/status | jq -e '\n  .ok\n  and .data.sign_in == \"signed_in\"\n  and (.data.workspace.id | type == \"string\" and length > 0)\n  and .data.uploader.healthy == true\n  and .data.direct_delivery == true\n  and (.data.session.id | type == \"string\" and length > 0)\n  and .data.session.registered == true\n  and .data.session.direct_delivery == true'\n```\n\nConfirm `workspace.id` is the **shared** workspace both sides agreed on. A\nhealthy uploader is the one non-obvious prerequisite: for a teammate's agent to\nread **this** person's session, this machine must have uploaded it. If\n`uploader.healthy` is false (paused, or a failed cycle), fix it before promising\nanyone can read this session — this is the single most common reason a live\nhandoff silently fails.\n\n`sharing_mode` decides which sessions upload at all. `new` and `all` include\nthis session. Under `selected`, only the sessions the person chose upload, so a\nteammate cannot read this one until the person selects it. Tell them that and\nask; do not change the sharing mode or select sessions on their behalf.\n\n## 3. Install the agent-sessions cloud MCP (before the session uses it)\n\nCheck whether the token is present in the environment **without printing it**\n(see **Token handling**). It is not required to *add* the MCP, since only a\nreference is stored, but it is required for the tools to authenticate after the\nrestart. If it is missing, add the MCP anyway, tell the person plainly that the\ntools will fail auth until they restart the agent from an environment that\nexports `AGENT_RELAY_SESSIONS_TOKEN`, and do not report setup complete:\n\n```sh\nif ! test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"; then\n  echo 'AGENT_RELAY_SESSIONS_TOKEN is not set here; the MCP will be added by reference, but the agent must be restarted from an environment that exports it.' >&2\nfi\n```\n\nDetect which agent CLI this session runs and install accordingly.\n\nClaude Code — pass the **unexpanded** placeholder so the token stays out of argv\nand out of `~/.claude.json`; Claude expands `${VAR}` in MCP headers from the\nenvironment at launch. This expansion requires **Claude Code ≥ 2.1.119**, so\nverify the version first and update rather than inlining the token on an older\nclient. Single-quote the header so the shell does not expand it here. Default\nscope is `local` (this project only), which is what you want:\n\n```sh\nclaude_ver=$(claude --version 2>/dev/null | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1)\nif test -z \"$claude_ver\" || test \"$(printf '%s\\n2.1.119\\n' \"$claude_ver\" | sort -V | head -1)\" != 2.1.119; then\n  echo \"Claude Code $claude_ver does not expand \\${VAR} in MCP headers (need >= 2.1.119); update Claude Code before adding this server.\" >&2\n  exit 1\nfi\nclaude mcp add --transport http agent-relay-sessions \\\n  https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --header 'Authorization: Bearer ${AGENT_RELAY_SESSIONS_TOKEN}'\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nCodex — `codex mcp add` records the **variable name**, not the value, and writes\nto user-level `~/.codex/config.toml`, so the server is enabled for **all** Codex\nprojects (Codex has no project-scoped MCP). Confirm the person is OK with\nuser-wide access before adding it:\n\n```sh\ncodex mcp add agent-relay-sessions \\\n  --url https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --bearer-token-env-var AGENT_RELAY_SESSIONS_TOKEN\ncodex mcp list | grep -F agent-relay-sessions\n```\n\nBecause MCPs load at startup, the running session must be **restarted** to pick\nup the server — and because both CLIs read the token from the environment at\nlaunch, the restarted process must **inherit** `AGENT_RELAY_SESSIONS_TOKEN`.\nThat is why the variable belongs in the shell profile / launcher, not a transient\nshell-tool subprocess: an `export` in this agent's shell tool cannot reach the\nparent or a freshly launched session. After the restart, re-verify presence with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"` before using the tools, and do not\nreport the tools as missing without first confirming the session started *after*\nthe MCP was added and with the variable set.\n\n## 4. Confirm the handoff tools loaded\n\nIn the session that started after the MCP was added, confirm the tools are\npresent before using them. List this session's MCP tools and check for the\nagent-sessions set; the authoritative check is that the tools actually appear to\nthis agent:\n\n```sh\n# Claude Code: the tools surface as mcp__agent-relay-sessions__*\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nThen call `list_relay_agents` through the MCP (an MCP tool call, not a shell\ncommand). A successful call that returns the workspace roster proves the MCP is\nloaded, the token is valid, and this session can see the shared workspace. If\nthe call errors with auth, the token is wrong or for another workspace — have\nthe person re-mint it from the correct workspace's dashboard.\n\n## 5. Prove one live round trip\n\nThe real proof is agent-to-agent, so it needs a counterpart. Pick the path that\nmatches what is available:\n\n**A teammate's agent is online (full round trip).** Ask the person for the\nteammate's relay address (e.g. `@manav`), then:\n\n1. `list_relay_agents` — confirm the teammate's address is listed.\n2. **Prove the reverse read path first:** call `get_shared_session_context` on\n   the teammate's session and confirm it returns their **real** content (prompts/\n   events + a dashboard citation link). If it errors or is empty, their uploader\n   is unhealthy — stop and have them fix it; do not declare GREEN, because this\n   side cannot actually read their work yet.\n3. `send_relay_message` — send a short, uniquely-marked message to that address.\n4. The teammate's agent reads this session with `get_shared_session_context` and\n   continues; have them reply through the relay.\n5. GREEN requires **both directions**: this agent read the teammate's real\n   content (step 2) **and** the teammate's reply lands here. There is no\n   automatic ack — confirm by the reply/activity, not a push. Because Relay\n   injects an inbound message only when the session is idle between turns, **end\n   the turn** after sending and confirm the reply on the next turn; do not sleep\n   or poll inside one turn.\n\n**No teammate online yet (self-verify the read path).** Prove the machinery\nwithout a second person:\n\n1. `list_relay_agents` returns the roster — MCP + token + workspace are good.\n2. `search_shared_sessions` / `get_shared_session_context` return this person's\n   **own** recently uploaded session (real prompts/events plus a dashboard\n   citation link) — the uploader→read path works.\n3. Record that the two-party round trip still needs the teammate online, and\n   name it as the remaining step rather than claiming the handoff is proven.\n   Setup is not complete until the full round trip succeeds.\n\nNever paste the Bearer token or any session token into a `send_relay_message`\nbody or any artifact.\n\n## 6. Report\n\nSeparate verified facts from what still needs a human or a second machine:\n\n- app version, `signed_in`, the signed-in **workspace id and name**;\n- uploader `healthy`, this session's `agent@machine` address, direct delivery on;\n- agent-sessions MCP installed and its tools confirmed loaded in this session;\n- `list_relay_agents` roster seen; and either the full round-trip evidence (the\n  teammate's real content + reply) or the self-verified read path plus the named\n  remaining step (teammate online).\n\nDo not call the setup complete on a 2xx from `claude mcp add` alone, and do not\ncount a roster listing as a proven handoff.\n\n## Recovery\n\n- **`not_a_relay_session` from `/setup/*`:** the caller is not inside a discovered\n  interactive session. Run it from this agent's own shell inside an **interactive**\n  Claude Code or Codex session — a non-interactive `codex exec` or `claude -p` run\n  is not admitted, and neither is an unrelated terminal. In tmux/SSH, confirm the\n  agent process and shell share the pane's process tree.\n- **No handoff tools in the session:** the MCP was added after the session\n  started, or at the wrong scope. Reinstall at project scope (section 3) and\n  **restart** the session; MCPs load only at startup.\n- **`list_relay_agents` auth error:** the token is wrong, expired, or from a\n  different workspace. Because the MCP config stores only a **reference** to\n  `AGENT_RELAY_SESSIONS_TOKEN`, fixing it means updating the **value in the\n  launch environment** (keychain / 0600 file) and **restarting** the agent so it\n  re-reads it — re-running `claude mcp add` / `codex mcp add` alone changes\n  nothing. Re-mint from the intended workspace's \"Connect your agent\" card if the\n  token itself is bad. On Claude, also confirm the client is ≥ 2.1.119 (older\n  clients send the `${VAR}` placeholder literally).\n- **Teammate's address missing from the roster:** they are not on the **same**\n  workspace, or their session is not on the relay. Have them register their\n  session and confirm the shared workspace id.\n- **Can't read the teammate's session:** their **uploader** is not healthy\n  (paused or a failed cycle). Have them check `/setup/status` shows\n  `uploader.healthy == true`, not \"Sync paused/offline\".\n- **Message arrives held, not live:** direct delivery is off for the recipient —\n  POST `{\"enabled\":true}` to `/setup/direct-delivery` on their machine (Codex\n  delivers directly by default). A managed Claude policy can block this; report\n  it rather than editing managed settings.\n- **Remove the MCP:** `claude mcp remove agent-relay-sessions` /\n  `codex mcp remove agent-relay-sessions`. This removes only the handoff tools;\n  it does not sign the desktop out or stop uploads.\n\n## Relationship to the other skills\n\n- **`setting-up-agent-relay-desktop`** — the layer below this one: install,\n  sign-in, agent-led defaults, self-registration. Use it when section 2 is not\n  yet satisfied.\n- **`relay-connect`** — a lighter, account-free, time-boxed way for two agents to\n  share one session via a hand-over link. Prefer it for an ad-hoc pairing;\n  prefer this skill for durable teammate-to-teammate handoff inside a shared\n  workspace.\n",
-  "setting-up-agent-relay-flows": "# Set Up Agent Relay Flows\n\nDrive the setup through the documented Cloud APIs and the official CLI. Do not\nuse computer use, browser automation, or the dashboard UI. The human approves\nsign-in, tool consent, and provider logins on their own approval pages; open\nthose links with the OS URL opener (or give them the link), then verify by\npolling the API, never by inspecting the browser.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix; the site is `https://agentrelay.com`. When a\nguide names a different site and Cloud base (for example a local development\nstack), use those exact origins throughout and never fall back to production.\nFlows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.\n\n## Requires\n\nA signed-in Cloud session: an access token and the `user.id` and\n`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`\nfirst, and send `Authorization: Bearer <access_token>` on every request below.\n\n## API map\n\n- Flow catalog: `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.\n- Tool consent links: `POST /api/v1/integrations/connect-link`; poll\n  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.\n- Coding-agent credentials: the official CLI's `cloud connect` (section 3);\n  `GET /api/v1/cloud-agents` inspects existing connections.\n- Activation: `POST /api/v1/flows/deploy` with the body in section 4.\n- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`\n  reports whether it is available.\n- Verification: `GET /api/v1/flows/listeners/<agentId>`.\n\n## 1. Prebuilt or custom?\n\nAsk the human first, unless their request already says: a **prebuilt** flow\nfrom the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**\nflow of their own? In an agent-driven signup, ask through that guide's\nweb-input protocol on the signup page, not in chat.\n\n- Prebuilt: continue with section 2.\n- Custom: follow **Custom flow: deploy journey** below. A custom flow is\n  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and\n  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is\n  no separate custom API.\n\n## 2. Choose the flow and repository\n\nAsk the human for missing product choices: repository, desired\nworkflow/trigger, and approver. In an agent-driven signup, ask through that\nguide's web-input protocol on the signup page, not in chat. Ask for the approver's\nGitHub username in plain language (for example, \"octocat\" or \"@octocat\"),\nnot an internal provider-address format or their Google email. Normalize the\nanswer to github:@handle when constructing the deploy API request. Human-gate\nreplies are matched to that provider identity. Infer choices from the user's request and current\nrepository where clear.\nDo not invent a repository or enable automation on an unrelated project.\n\nGET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.\nGET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's\nkind before doing anything executable: only an entry with kind: flow (or a\nlegacy entry with kind omitted) is deployable through the direct-source API\nbelow. An entry with kind: extension is discoverable metadata, not a standalone\nlistener. Do not download or deploy its source, even when it declares trigger\nand input fields. Inspect baseFlowId and extension.activation instead. If the\nextension is blocked, report the unmet dependencies and that it can only be\nadded to its base flow after a supported extension activation path is available;\nnever substitute a standalone flow deployment.\n\nFor a deployable flow, use the catalog's\nsupportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and\ninputs.allowedAgents. Name a model per harness in inputs.models when the house\ndefault is wrong (for example {\"claude\": \"claude-sonnet-4\"}); omit it to fund\nthe house default for each declared agent. Download source.rawUrl, verify its bytes against\nsource.sha256, and use that source text unchanged for a recommended flow.\nThe source is TypeScript, not the source URL. Do not guess a template or hash.\n\n## Custom flow: deploy journey\n\nThere is no journey API. A `journey_id` (for example in a\n`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it\nthrough unchanged where you received it, and never call an endpoint with it or\nwait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`\nas a prebuilt one; only where the source comes from differs.\n\n1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,\n   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that\n   skill for the flow's shape and checks; Flows are always v2. Cloud's\n   prompt generator is an optional shortcut: use it only when\n   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it\n   reports unavailable, refuses your session (403 `session_required`), or\n   fails, author with `writing-relayflows` instead; do not retry into it.\n2. Choose its repository, trigger and approver as in section 2.\n3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the\n   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent\n   only when the prompt generator produced one. `base` and `extensions` are\n   optional and only for a flow that names them.\n\nThe human-only steps are the same for both paths: Google sign-in and device\napproval, GitHub and trigger-app OAuth including the repository grants,\nmodel-provider login, and confirming the repository and trigger before\nactivation. Do every other step yourself through the APIs.\n\n## 3. Connect the required tools and coding agents\n\nUse bearer-authenticated POST /api/v1/integrations/connect-link:\n\n```json\n{\"provider\":\"github\",\"workspaceId\":\"<currentWorkspace.id>\"}\n```\n\nOpen the returned connectUrl for the user to approve. Keep token/sessionToken\nprivate. Connect only the repository and tools the chosen flow requires.\nFor GitHub the user must grant repository access. Repeat with the chosen trigger\nprovider if different. Reuse existing ready connections rather than relinking.\nCheck GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status\nuntil oauth.connected is true (poll with backoff and a bounded timeout); a\nreturned connect link or a closed popup alone does not prove the connection.\nFor the GitHub-triggered Software Garden flow, activation separately checks\nthat the connected GitHub App covers the selected repository. Its trigger\ndoes not require background data indexing, so do not block solely because\nthe broader status.ready is false from queued syncs.\nIf a different flow declares Relayfile data that requires synced records,\nverify that readiness separately before activating it.\n\nDo not connect a Claude or Codex subscription yet. The first three runs use\nCloud's own model key, so no provider login is needed to activate. If the chosen\nflow declares more than one coding agent in inputs.agents, included Cloud runs\ncan fund only one of them per run — connect your own subscription for at least\none declared agent before activating a multi-agent flow. After the included\nruns, activation and launches will ask for your own subscription; only then use\nthe official Relay CLI with the private credential environment from\n`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:\n\nThis promotion depends on Cloud's internal house-key proxy and account\nenrollment. If local activation returns flow_credentials_unavailable or\nflow_model_not_connected before the three promotional runs, treat it as an\ninternal configuration or eligibility issue. Do not ask the user to connect\nClaude/Codex, provide an API key, or choose an inactive draft as a workaround.\nReport the blocker (in a signup, through its Progress API) and have an internal developer\nverify the proxy, promotion flag, provider readiness, and enrollment. Never\ncopy a house key into the agent environment or expose it in this guide.\n\n```sh\nnpx --yes agent-relay@latest cloud connect anthropic --api-url 'https://agentrelay.com/cloud'\n```\n\nUse anthropic for Claude or openai for Codex, according to the selected flow.\nThe command drives provider login; open its authorization URL for the user,\nand keep the process alive until it confirms the credential is connected.\nGoogle approval does not grant GitHub or model-provider access: those services\nmay require their own consent. Never fabricate credentials or claim consent\nhappened. GET /api/v1/cloud-agents lets you inspect the account's credential\nstate without reconnecting.\n\n## 4. Activate through the same API as web onboarding\n\nPOST /api/v1/flows/deploy with Content-Type: application/json and the bearer\nsession. The token must be the device-flow session from\n`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with\n`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the\nbrowser onboarding handoff: source is TypeScript text, repository is singular,\nand sources contains provider/settings objects. The catalog supplies the source\nreference and defaults; it is not itself a deploy request. The current endpoint\ndoes not accept a flowId/repositories-only catalog activation request or fetch\nthe source for you. For multiple repositories, submit one deployment per\nrepository with a distinct name and handoffId.\n\nFor the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the\nworkspace, verified source, repository, GitHub approver and a new UUID:\n\n```json\n{\n  \"workspaceId\": \"<currentWorkspace.id>\",\n  \"name\": \"Software Garden\",\n  \"workflow\": \"software-factory\",\n  \"source\": \"<verified TypeScript source text>\",\n  \"handoffId\": \"<one UUID generated for this setup>\",\n  \"inputs\": {\"approver\": \"github:@octocat\", \"agents\": [\"claude\"]},\n  \"mode\": \"activate\",\n  \"repository\": {\"owner\": \"acme\", \"name\": \"api\"},\n  \"sources\": [{\"provider\": \"github\", \"settings\": {\"repository\": \"acme/api\"}}]\n}\n```\n\nFor another deployable kind: flow catalog entry use its id as workflow, allowed agents, and\ndefaultTrigger for sources, then apply the user's trigger settings. Scope a\nGitHub issue trigger with settings.repository set to the chosen owner/name;\nfor GitLab use settings.project. Cloud does not derive this filter from the\ndeployment repository. An empty filter can trigger on other repositories in\nthe workspace. Only use a different trigger scope when explicitly requested.\nGive each repository its own trigger filter for multi-repository setup. Do not send\nthe example acme repository or octocat approver unchanged. The workflow field\nis a label, not a source lookup; keep the verified source in the request.\nFor GitLab set repository.host to gitlab and use the namespace path\nas owner. Reuse the handoffId on retry. Before retrying an ambiguous network\nfailure, GET /api/v1/flows/listeners and check whether the flow already exists;\ndo not create a new ID/name on every retry. Activation subscribes to matching\nfuture events and can run work; confirm the intended repository and trigger\nwith the user if they have not specified them.\n\nHTTP 201 must contain agentId and status: listening. A draft is not completion.\nFor a 409 workspace_mismatch, verify the active workspace; for connection\npreflight failures, fix the indicated connection before retrying. If the user\nwants to save incomplete work, use mode: draft explicitly and report that it\nis inactive. Never mask activation failures by silently falling back to draft.\n\n## 5. Verify\n\nGET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and\nverify its repository and sources match the request. Open\nhttps://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,\nworkspace, repository, trigger, and verified listening state. This proves\nactivation; only an actual completed run proves execution. Do not create a\nreal issue or launch paid work merely to make the onboarding check turn green.\nDelete temporary authentication files after the work is complete.\n\nThe desktop app is optional for Flows. If the user also wants local session\nsharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`\nwith the same account (an agent-driven signup can follow\nhttps://agentrelay.com/signup/agent/teams).\n",
+  "signing-in-to-agent-relay-cloud": "# Sign In to Agent Relay Cloud\n\nUse the existing OAuth device flow. No API key, invitation, dashboard wizard,\nor pre-existing Agent Relay account is required. Only the human approves the\nsign-in; never approve access on their behalf, ask for their password, or\noperate the approval page yourself.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix. When a guide names a different Cloud base (for\nexample a local development stack), use that exact base throughout and never\nfall back to production.\n\n## HTTP client\n\nUse `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their\ndefault User-Agent: the device-token endpoint answers them with HTTP 403 and no\nJSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth\nresponse while debugging; on success it contains tokens. Send JSON request\nbodies with `Content-Type: application/json`, set a 30-second request timeout,\nand check every response status before proceeding.\n\n## 1. Start the device grant\n\n`POST /api/v1/auth/device/start` with:\n\n```json\n{\"client_name\":\"My agent setup\"}\n```\n\nAn agent-driven signup guide also passes its product as `signup_source`\n(`\"teams\"` or `\"flows\"`); keep the value the guide names. Omit it otherwise.\n\nExpect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,\n`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep\n`device_code` private. Open `verification_uri_complete` in the person's\nbrowser with the OS URL opener (for example macOS `open`, with the URL passed as\na separate argument, never interpolated into shell code), or give them the link\nif no opener is available. Show the `user_code` so they can compare it. The page\nlets them sign in with Google, review the requesting device, and Approve or\nDeny. A signup marker in the returned URL creates the right account type;\npreserve it through sign-in. Do not call `/auth/device/approve` yourself.\n\nFor a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`\non the same Cloud base first (in production,\n`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of\n`verification_uri_complete`. This opens Google immediately and returns to the\nsame device approval with its code and signup marker intact. Never open the\nproduction URL for a non-production base: that would sign the human in to\nproduction instead.\n\n## 2. Poll for tokens\n\nWhile the browser is open, wait `interval` seconds between POSTs to\n`/api/v1/auth/device/token` with this JSON (substitute the private\n`device_code`):\n\n```json\n{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"<device_code>\"}\n```\n\n- `authorization_pending`: keep waiting; respect a returned interval.\n- `slow_down`: increase the interval by at least 5 seconds.\n- HTTP 429: respect `Retry-After` and increase the interval.\n- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.\n- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start\n  a new grant only if the person still wants to continue. Never poll past\n  expiry.\n\nHTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,\n`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in\nmemory or a private file (directory 0700, file 0600) outside repositories.\nNever echo tokens, put them in chat or URLs, or dump full authentication\nresponses. Use `Authorization: Bearer <access_token>` for subsequent Cloud\nrequests. Reject an `api_url` pointing at another origin; keep using the Cloud\nbase above.\n\n## 3. Refresh before expiry\n\nBefore expiry, `POST /api/v1/auth/token/refresh` with\n`{\"refreshToken\":\"<refresh_token>\"}`. The response uses camelCase:\n`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,\n`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the\nrefresh token rotates and must not be shared between machines. An\ninvalid/expired refresh requires a new device login, not an endless retry.\n\n## 4. Read the account and workspace\n\n`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,\n`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups\ncreate a workspace automatically. Reuse it; do not create duplicate\naccounts/workspaces. If `currentWorkspace` is missing, or an existing account\nis in the wrong workspace, resolve that with the person before connecting or\nactivating anything. Never silently replace an existing connection to another\naccount.\n\n## 5. Hand the session to the official CLI\n\nWhen running a child process, pass these through its environment from your\nprivate session object (never interpolate their values into logged commands):\n\n```text\nCLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>\nCLOUD_API_ACCESS_TOKEN=<access_token>\nCLOUD_API_REFRESH_TOKEN=<refresh_token>\nCLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>\nCLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>\n```\n\nThe official CLI consumes this session. Refresh the parent session before\nstarting a long command; do not concurrently refresh it from parent and child\nprocesses. Do not overwrite an existing CLI auth file or copy a session to\nanother machine. Delete temporary authentication files after the work is\ncomplete.\n",
+  "setting-up-agent-relay-desktop": "# Set Up Agent Relay Desktop\n\nComplete the setup through the private session socket. Do not ask the human to\nclick through the desktop app. The only normal human step is approving one\ndevice-login link when no reusable `agent-relay` CLI login exists.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the current release is installed and running;\n- sign-in is complete;\n- sharing mode is `new` (new sessions upload automatically), unless an existing\n  install already uses another mode and the human chose to keep it (section 4);\n- auto-activate is on, with every existing live session and every future session on the relay;\n- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);\n- this Codex or Claude session is registered and accepts direct delivery;\n- the requested webhook and integration subscriptions work;\n- the human receives the session's `agent@machine` address and verification evidence.\n\nNever put a Cloud token, workspace key, agent token, or webhook secret in a\nRelay message. The webhook secret is returned once to this local calling\nsession; keep it in a mode-0600 temporary file and delete the file after the\ntest.\n\n## Install this skill for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage, then place that unchanged `SKILL.md` where Codex actually loads global\nskills:\n\n```sh\nnpx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y\ncodex_skill=\"$HOME/.codex/skills/setting-up-agent-relay-desktop\"\nmkdir -p \"$codex_skill\"\ninstall -m 0644 \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\ncmp \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\n```\n\nDo not use prpm's `--as codex` conversion for this package. It currently writes\nunder `~/.agents/skills`, which Codex does not load as its global skill folder,\nand its conversion drops explanatory paragraphs from this Markdown workflow.\nConfirm both final paths explicitly before continuing.\n\n## 1. Detect the host and current session\n\nRun setup commands from this agent's own shell tool. Do not run them from an\nunrelated terminal: the app identifies the caller from kernel credentials and\nthe Codex/Claude process ancestry.\n\n```sh\nuname -s\nuname -m\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\nif test \"$(uname -s)\" = Linux; then\n  if command -v dpkg-query >/dev/null; then\n    printf 'linux_install=deb\\n'\n  else\n    printf 'linux_install=per-user-tarball\\n'\n  fi\nfi\ncommand -v systemctl >/dev/null && systemctl --user is-system-running || true\n```\n\nOn Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other\nsystemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball\npath; do not try to install the `.deb`. The app scans same-user process trees\nand TTYs; it does not require the service itself to share the tmux session.\n\n`systemctl --user is-system-running` may report `degraded` because an unrelated\nuser unit failed. That is not a Relay failure when\n`systemctl --user is-active agent-relay.service` reports `active` and the Relay\nsocket passes its status check.\n\nFind an existing socket without printing private files:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test -n \"${XDG_RUNTIME_DIR:-}\"; then\n  relay_socket=\"$XDG_RUNTIME_DIR/agent-relay/relay.sock\"\nfi\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"/run/user/$(id -u)/agent-relay/relay.sock\"\nfi\nc=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Darwin && test -S \"$c\"; then   # pointer file missing: use the app's own socket\n  relay_socket=$c\nfi\ntest -S \"${relay_socket:-/nonexistent}\" && printf 'socket=%s\\n' \"$relay_socket\"\n```\n\nIf the socket exists, inspect it before installing anything:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout\n(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's\n`relay socket-request` can give up sooner with \"Probe could not finish. Check\nyour connection and run setup again\"; on these paths that is the same latency,\nnot a setup problem. Retry the call once before reporting a blocker, and do not\nstart a second install or sign-in because of it.\n\nPreserve a working newer install. When the socket is absent, check for an\ninstalled-but-stopped copy before downloading: use `dpkg-query -W agent-relay`\nwhen `dpkg-query` exists and `systemctl --user status agent-relay.service` on\nLinux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry\nstatus first.\nUpdate an older install only when it lacks the setup contract or reports an\nolder version. A `404` from `/setup/status` means the installed build is too\nold for agent-driven setup and should be updated.\n\n## 2. Install or update with checksum verification\n\nUse a private temporary directory. Never skip the published SHA-256 check.\n\n### Ubuntu LTS, headless `.deb` (preferred)\n\nSelect the release architecture and install:\n\nThis path needs passwordless sudo or one human-approved sudo prompt for the\npackage install and `loginctl enable-linger`. Explain that prerequisite before\nstarting; never capture or relay a sudo password.\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb\" -o \"$relay_tmp/AgentRelay.deb\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb.sha256\" -o \"$relay_tmp/AgentRelay.deb.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#\" AgentRelay.deb.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nsudo apt-get install -y \"$relay_tmp/AgentRelay.deb\"\nsudo loginctl enable-linger \"$USER\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n```\n\nThe unit runs the bundled core headless: no display, X server, or GTK\nwindow is needed. This session's own GitHub subscriptions (section 6) go\nthrough the Desktop and need no CLI. The separate Agent Relay CLI is needed\nonly to subscribe a fleet-spawned or named agent; record whether it is present\nand at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app\ndiscovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:\n\n```sh\nrelay_cli=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay\" \\\n  \"$HOME/.npm-global/bin/agent-relay\" \\\n  \"$HOME/.agentworkforce/relay/bin/agent-relay\"\ndo\n  if test -x \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n    relay_cli=$candidate\n    break\n  fi\ndone\nif test -z \"$relay_cli\"; then\n  for relay_root in \\\n    \"$HOME/.local/share/mise/installs/node\" \\\n    \"$HOME/.nvm/versions/node\"\n  do\n    test -d \"$relay_root\" || continue\n    candidate=$(find -L \"$relay_root\" -mindepth 3 -maxdepth 3 \\\n      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)\n    if test -n \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n      relay_cli=$candidate\n      break\n    fi\n  done\nfi\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" integration subscribe --help >/dev/null\nelse\n  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\\n'\nfi\n```\n\nOn Linux without `dpkg`, use this per-user tarball installation under a\nversioned user directory. It is also the fallback on Ubuntu when `.deb`\ninstallation is unavailable and the human approves a per-user install. The\narchive contains a unit whose `/usr/bin` path is correct for packages, so\nrewrite only that `ExecStart` in the user copy:\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz\" -o \"$relay_tmp/AgentRelay.tar.gz\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256\" -o \"$relay_tmp/AgentRelay.tar.gz.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#\" AgentRelay.tar.gz.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmkdir \"$relay_tmp/extracted\"\ntar -xzf \"$relay_tmp/AgentRelay.tar.gz\" -C \"$relay_tmp/extracted\"\nrelay_tree=\"$relay_tmp/extracted/AgentRelay-linux-$relay_arch\"\ntest -x \"$relay_tree/usr/bin/agent-relay\"\nrelay_version=$(sed -n 's/^__version__ = \"\\([0-9A-Za-z._-]*\\)\"$/\\1/p' \\\n  \"$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py\")\ncase \"$relay_version\" in\n  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\\n' >&2; exit 1 ;;\nesac\nrelay_unit=\"$HOME/.config/systemd/user/agent-relay.service\"\nrelay_installed_version=\nif test -S \"${relay_socket:-/nonexistent}\"; then\n  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)\nfi\nif test -z \"$relay_installed_version\" && test -r \"$relay_unit\"; then\n  relay_installed_version=$(sed -n \\\n    's#^ExecStart=.*/\\.local/lib/agent-relay/\\([^/ ]*\\)/.*#\\1#p' \\\n    \"$relay_unit\")\nfi\ncase \"$relay_installed_version\" in\n  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;\nesac\nif test -n \"$relay_installed_version\" && \\\n   test \"$relay_installed_version\" != \"$relay_version\" && \\\n   test \"$(printf '%s\\n%s\\n' \"$relay_version\" \"$relay_installed_version\" | sort -V | tail -n 1)\" = \"$relay_installed_version\"; then\n  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\\n' \\\n    \"$relay_installed_version\" \"$relay_version\" >&2\n  exit 1\nfi\nrelay_prefix=\"$HOME/.local/lib/agent-relay/$relay_version\"\nmkdir -p \"$relay_prefix\"\ncp -a \"$relay_tree/usr\" \"$relay_prefix/\"\nmkdir -p \"$(dirname \"$relay_unit\")\"\nsed \"s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#\" \\\n  \"$relay_tree/usr/lib/systemd/user/agent-relay.service\" >\"$relay_unit.tmp\"\nchmod 0644 \"$relay_unit.tmp\"\nmv \"$relay_unit.tmp\" \"$relay_unit\"\ngrep -F \"ExecStart=$relay_prefix/usr/\" \"$relay_unit\" | grep -q -- ' --headless$'\nif ! loginctl show-user \"$USER\" -p Linger | grep -qx 'Linger=yes'; then\n  sudo loginctl enable-linger \"$USER\"\nfi\nsystemd-analyze --user verify \"$relay_unit\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n# List the app in the desktop's app launcher (no-op on a headless server).\n# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the\n# entry the first time it is opened.\nif test -x \"$relay_prefix/usr/bin/agent-relay-desktop\"; then\n  \"$relay_prefix/usr/bin/agent-relay-desktop\" --install-launcher || true\nfi\n```\n\nThe unit's `ExecStart` names the archive's own path under `/usr/`, either the\nlauncher or the bundled `agent-relay-probe`; the rewrite moves whichever it is\nunder `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its\nfull path, never the bare `agent-relay`, which is also the CLI's name.\n\nDo not improvise Alpine or RHEL distribution packages. On a compatible\nsystemd host without `dpkg`, use only the verified per-user tarball path above;\nnon-systemd hosts remain unsupported by this Linux workflow.\n\n### macOS DMG\n\n```sh\ncase \"$(uname -m)\" in\n  arm64) relay_arch=arm64 ;;\n  x86_64) relay_arch=x64 ;;\n  *) printf 'Unsupported Mac architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg\" -o \"$relay_tmp/AgentRelay.dmg\"\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg.sha256\" -o \"$relay_tmp/AgentRelay.dmg.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#\" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmount_point=$(hdiutil attach -nobrowse -readonly \"$relay_tmp/AgentRelay.dmg\" | awk '/\\/Volumes\\// {sub(/^.*\\/Volumes\\//,\"/Volumes/\"); print; exit}')\nincoming_id=$(defaults read \"$mount_point/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\nif test \"$incoming_id\" != com.agentrelay.desktop; then\n  hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\\n' \"$incoming_id\" >&2\n  exit 1\nfi\nif test -d \"/Applications/Agent Relay.app\"; then\n  existing_id=$(defaults read \"/Applications/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\n  if test \"$existing_id\" != com.agentrelay.desktop; then\n    hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\\n' \"$existing_id\" >&2\n    exit 1\n  fi\nfi\nosascript -e 'tell application \"Agent Relay\" to quit' 2>/dev/null || true\nditto \"$mount_point/Agent Relay.app\" \"/Applications/Agent Relay.app\"\nhdiutil detach \"$mount_point\"\nopen -a \"Agent Relay\"\n```\n\nIf `/Applications` needs administrator access, use `sudo ditto` only after the\nhuman has authorized installation. Do not remove or overwrite another app with\nan unexpected bundle identity.\n\nAfter either install, wait up to 30 seconds for the pointer:\n\n```sh\napp_sock=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nfor _ in $(seq 1 30); do\n  test -r \"$HOME/.agentworkforce/desktop/relay-socket\" && break\n  test \"$(uname -s)\" = Darwin && test -S \"$app_sock\" && break   # the app is already listening\n  sleep 1\ndone\nrelay_socket=$(sed -n '1p' \"$HOME/.agentworkforce/desktop/relay-socket\" 2>/dev/null)\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Darwin && test -S \"$app_sock\"; then\n  relay_socket=$app_sock\nfi\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock\"\nfi\ntest -S \"$relay_socket\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'\n```\n\n## 3. Sign in by device approval\n\nBefore choosing a workspace, check what the human already has. These commands\nonly read state. The CLI checks run only when section 2 found a `relay_cli`;\nnever call the `.deb`'s `/usr/bin/agent-relay` launcher for them:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'\nif test -n \"${relay_cli:-}\"; then\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nSign in to the workspace they already use. Pick a different or new workspace\nonly when the human explicitly asks for it.\n\nFor a multi-server rollout, obtain the existing enterprise workspace UUID from\nthe human and pass it explicitly on every server. Do not guess it and do not\nuse `{}` when the target workspace is known: that could select a default/free\nworkspace and split the fleet. Use `{}` only for an individual setup where the\nhuman has confirmed that the reusable login's current workspace is intended.\n\n```sh\nrelay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'\nsign_in_payload=$(jq -nc --arg workspace \"$relay_workspace_uuid\" '{workspace:$workspace}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nIf sign-in reports that older upload schedules could not be inspected, first\ninspect the user's legacy cron, launchd, and user-service upload schedules.\nAfter completing that safety check, retry the original request with the\nacknowledgement added; never use it merely to suppress the error:\n\n```sh\nsign_in_payload=$(printf '%s\\n' \"$sign_in_payload\" | \\\n  jq '. + {acknowledge_uninspected_schedules:true}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nPrint a device link and code only when the response actually contains a code:\n\n```sh\nuser_code=$(printf '%s\\n' \"$sign_in\" | jq -r '.data.user_code // empty')\nif test -n \"$user_code\"; then\n  verification_url_complete=$(printf '%s\\n' \"$sign_in\" | \\\n    jq -r '.data.verification_url_complete // empty')\n  if test -n \"$verification_url_complete\"; then\n    printf 'Open %s and approve code %s\\n' \"$verification_url_complete\" \"$user_code\"\n  else\n    verification_url=$(printf '%s\\n' \"$sign_in\" | \\\n      jq -r '.data.verification_url // empty')\n    printf 'Open %s and enter code %s\\n' \"$verification_url\" \"$user_code\"\n  fi\nfi\n```\n\nIf the response is `signed_in` with `reused_login:true`, the app reused an\neligible same-origin CLI or desktop login and intentionally issued no device\ncode. Confirm the returned workspace id and name with the human rather than\nwaiting for a code, then continue only if it is the intended workspace.\n\nFor `pending_approval`, the human can approve from any phone or browser. Do not\ncreate another code while this one is pending. A `preparing` response is also\nnormal: poll `/setup/status` at the reported interval. Preparing local history\ncan take about a minute when the app reuses an existing `agent-relay` CLI login.\nPoll both states until sign-in finishes. The reason for a failure is in\n`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so\nprint it, and map the known messages to their fix instead of dumping raw state:\n\n```sh\nwhile :; do\n  state=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status)\n  phase=$(printf '%s' \"$state\" | jq -r '.data.sign_in // .error.code')\n  case \"$phase\" in\n    signed_in)\n      printf '%s\\n' \"$state\" | jq \\\n        '{sign_in: .data.sign_in, workspace: .data.workspace}'\n      break\n      ;;\n    preparing|pending_approval) ;;\n    denied|expired|error)\n      msg=$(printf '%s' \"$state\" | jq -r '.data.sign_in_message // .error.message // \"no message reported\"')\n      printf 'Sign-in %s: %s\\n' \"$phase\" \"$msg\" >&2\n      case \"$msg\" in\n        *\"older managed history uploader\"*)\n          printf 'See \"Sign-in blocked by a legacy uploader\" under Recovery.\\n' >&2 ;;\n        *\"older upload schedules\"*)\n          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\\n' >&2 ;;\n        *) printf '%s\\n' \"$state\" | jq '.data' >&2 ;;\n      esac\n      exit 1\n      ;;\n  esac\n  sleep \"$(printf '%s' \"$sign_in\" | jq -r '.data.interval // 5')\"\ndone\n```\n\n## 4. Apply the agent-led defaults and register this session\n\nRead the current sharing mode before changing it. `/setup/status` reports it as\n`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is\nuploading yet). The probe reports the same field, `sharing_mode`, in\n`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.\n\n```sh\nrelay_prior_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status | jq -r '.data.sharing_mode // empty')\ncase \"$relay_prior_mode\" in\n  new|all|selected) printf 'sharing_mode=%s\\n' \"$relay_prior_mode\" ;;\n  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\n```\n\nContinue only with a verified `new`, `all`, or `selected`. If the status read\nfails or reports no mode, retry once; if it is still unknown, stop and ask the\nhuman how to proceed rather than sending any sharing request.\n\nOn a fresh install, or when it already reports `new`, keep `new`. When an\nexisting install reports `all` (which also uploads past sessions, so it is\nbroader than this skill's default) or `selected`, tell the human the current\nmode and ask whether to keep it or change it to `new`. Never change it silently.\nOnly when the human explicitly chooses a different mode, set\n`relay_sharing_mode` to that answer at the top of the next block; left unset,\nthe block keeps the mode the app reports, so nothing changes without an answer.\nRemember the chosen mode: section 8 checks it again, and shell variables do not\nsurvive between separate tool calls.\n\nThen set and verify all three agent-led defaults even when the app's `/setup/*`\nbootstrap already applied them. Sharing mode `new` uploads every new session;\nauto-activation puts every existing live session and every future session on\nthe relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:\n\n```sh\n# Unset keeps the current mode; set it only to the human's explicit answer.\nif test -z \"${relay_sharing_mode:-}\"; then\n  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status | jq -r '.data.sharing_mode // empty')\nfi\ncase \"$relay_sharing_mode\" in\n  new|all|selected) ;;\n  *) printf 'Sharing mode unknown; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\ndirect_delivery=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' http://relay/setup/direct-delivery)\nprintf '%s\\n' \"$direct_delivery\" | jq\nif ! printf '%s\\n' \"$direct_delivery\" | jq -e '.ok and .data.direct_delivery'; then\n  if printf '%s\\n' \"$direct_delivery\" | jq -e '.error.code == \"managed_policy\"' >/dev/null; then\n    printf 'Organization-managed Claude settings forbid direct delivery.\\n' >&2\n  fi\n  exit 1\nfi\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d \"$(jq -nc --arg mode \"$relay_sharing_mode\" '{mode:$mode}')\" \\\n  http://relay/setup/sharing | jq\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' \\\n  http://relay/setup/auto-activate | jq\nregister=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/register)\nprintf '%s\\n' \"$register\" | jq\nregistration_status=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status)\nprintf '%s\\n' \"$registration_status\" | \\\n  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'\nprintf '%s\\n' \"$registration_status\" | jq -e \\\n  '.ok and (.data.session.id | type == \"string\" and length > 0) and\n   .data.session.registered == true and .data.session.direct_delivery == true'\n```\n\nDirect delivery is checked first so a managed-policy refusal stops setup\nbefore auto-activation or upload settings are changed. Report that refusal\nclearly; never claim the three-default setup completed.\n\nSharing mode and auto-activate are different settings: the former\ncontrols upload eligibility and the latter controls Relay registration. The\nsetup flow requires both.\n\n`POST /register` discovers the nearest live Codex or Claude ancestor. A session\ninside tmux over SSH is valid. Never pass a session id or token in the body.\nThe default name includes a 128-bit session-derived suffix, so dozens of\nsessions in the same checkout receive distinct `name@direct` addresses. Save\nand report the address from `/setup/status` for each session; never reuse one\nsession's address for another. `/register` may omit the session id or\ndirect-delivery state, so its response alone is not verification. Require the\nstatus response to show this session's non-empty id, `registered:true`, and\n`session.direct_delivery:true` as above. An app fix is expected to add those\nfields to `/register`, but the status check remains authoritative.\n\n## 5. Create and test the webhook\n\nPerform this section only when the human requested a webhook (or explicitly\nasked for the full end-to-end setup). Otherwise skip it; webhook creation is a\npersistent external mutation, not an install prerequisite.\n\nCapture the one-time secret without echoing it:\n\n```sh\numask 077\nhook_file=$(mktemp)\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/webhooks >\"$hook_file\"\njq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' \"$hook_file\"\n```\n\nWhen `created:true`, send a unique marker. Initialize every temporary path so\ncleanup can name and delete exact files without `-f` or globs:\n\n```sh\nhook_config=\nmarker=\nwebhook_post_ok=false\nwebhook_post_status=0\nif test \"$(jq -r '.data.created // false' \"$hook_file\")\" = true && \\\n   test \"$(jq -r '.data.secret // empty' \"$hook_file\")\" != ''; then\n  hook_url=$(jq -r '.data.url' \"$hook_file\")\n  hook_secret=$(jq -r '.data.secret' \"$hook_file\")\n  hook_config=$(mktemp)\n  chmod 600 \"$hook_config\"\n  printf 'header = \"Authorization: Bearer %s\"\\n' \"$hook_secret\" >\"$hook_config\"\n  marker=\"agent-relay-webhook-test-$(date +%s)\"\n  if curl -fsS --config \"$hook_config\" -X POST \"$hook_url\" \\\n      -H 'Content-Type: application/json' \\\n      -d \"{\\\"text\\\":\\\"$marker\\\",\\\"source\\\":\\\"agent-driven-setup\\\"}\"; then\n    webhook_post_ok=true\n  else\n    webhook_post_status=$?\n  fi\nelse\n  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\\n' >&2\nfi\nif test -n \"$hook_config\" && test -e \"$hook_config\"; then\n  rm -- \"$hook_config\"\nfi\nif test -e \"$hook_file\"; then\n  rm -- \"$hook_file\"\nfi\nunset hook_secret\nif test \"$webhook_post_ok\" = true; then\n  printf 'Webhook test sent; end this turn and wait for marker: %s\\n' \"$marker\"\nelif test -n \"$marker\"; then\n  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\\n' \\\n    \"$webhook_post_status\" >&2\n  exit \"$webhook_post_status\"\nfi\n```\n\nDo not claim success merely because the POST returned 2xx, and do not sleep or\npoll for the injected message during the same turn. Relay injects only after\nthe session becomes idle between turns. After the POST and exact-file cleanup,\nend the current turn by saying that setup is waiting for the exact marker. On\nthe next turn, confirm that the injected body contains that marker and its\nAgent Relay header contains a full message id; record that id in the final\nevidence. If a polling consumer is part of the setup, also observe that same id\nthere before declaring the webhook test complete. If the webhook already\nexisted, its secret is correctly returned as null; do not revoke or recreate it\nwithout human authorization. Ask for the existing secret or report that the\ndelivery test could not be repeated.\n\n## 6. Subscribe requested integrations\n\nRequire the provider and repository from the human. A GitHub pull request needs\none resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's\nreviews, review comments, conversation comments and check runs to that glob by\nthe PR they reference, so no other glob is needed: nothing is written under\n`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or\n`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This\nworks on every released Desktop and is the path to use today. If a review or\ncomment then never arrives, read it back in relayfile at its own path (the\ntable in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event\nnever reached relayfile\n([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),\nnot that the subscription is wrong.\n\nFirst find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions\n(below) and it is the client for the one-command form once that ships:\n\n```sh\nrelay_probe=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay-probe\" \\\n  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n  \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"\ndo\n  if test -x \"$candidate\"; then relay_probe=$candidate; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\nprintf 'relay_probe=%s\\n' \"${relay_probe:-none}\"\n```\n\nA running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the\nother candidates are the copies bundled by the `.deb`, the macOS app, and the\nper-user tarball. Then subscribe through the socket. On macOS use the probe\nclient when there is one: the system `curl` hides a Codex session's identity\nthere and is refused `not_a_relay_session`, so a Codex session with no probe\nstops instead. `curl` is correct for Claude Code and on Linux:\n\n```sh\n# One client for every socket request in this section and in undo: the probe\n# on macOS (system curl hides a Codex session there), curl elsewhere.\nrelay_req() {  # METHOD PATH [JSON body]\n  if test \"$(uname -s)\" = Darwin && test -n \"${relay_probe:-}\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\\n' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' -d \"$3\" \"http://relay$2\"\n  else\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n\n# This PR's subscriptions, in whichever form they were made. Fails, rather than\n# answering \"none\", when the status cannot be read: both callers stop then.\npr_url='https://github.com/OWNER/REPO/pull/NUMBER'\npr_resources() {\n  relay_status=$(relay_req GET /setup/status) || return 1\n  # -s reads the whole body as one list, so an empty body is an error too.\n  printf '%s\\n' \"$relay_status\" | jq -rs --arg url \"$pr_url\" \\\n    --arg short 'OWNER/REPO#NUMBER' \\\n    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \\\n    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '\n    if length == 1 and .[0].ok == true\n       and (.[0].data.integrations | type) == \"array\" then\n      .[0].data.integrations[] | select(.provider == \"github\") | .resource\n      | select(. == $url or . == $short or startswith($url + \"/\")\n               or startswith($pulls) or startswith($issues))\n    else\n      error(\"Agent Relay status is unreadable; no subscription was changed.\")\n    end'\n}\n\nheld=$(pr_resources) || exit 1\nif printf '%s\\n' \"$held\" | grep -Fqx -e \"$pr_url\" -e 'OWNER/REPO#NUMBER'; then\n  # The one-command subscription is a single complete request: nothing to add.\n  printf 'Already subscribed:\\n%s\\n' \"$held\"\nelif test -z \"$held\" && test -n \"${relay_probe:-}\" && \\\n     \"$relay_probe\" relay --help 2>&1 | grep -q '^  subscribe'; then\n  # The one-command form (below), only for a PR with no subscription yet and\n  # only when the installed probe has it.\n  \"$relay_probe\" relay subscribe \"$pr_url\" | jq\nelse\n  relay_req POST /integrations/subscribe \\\n    \"$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \\\n      '{provider:\"github\",resource:$resource}')\" | jq\nfi\nrelay_req GET /setup/status | jq -c '.data.integrations'\n```\n\nRequire `.ok` and `.data.subscribed` to be `true`, and the entry in the status\nlist to be `ready: true`. A repeated request returns HTTP 409\n`conflict` (\"already subscribed\"). That is success only for a binding made on\nor after 2026-09-19. Earlier bindings predate PR-identity matching\n(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews\nand comments. If the binding may be older, or you cannot tell, recreate it\nonce: `relay_req DELETE /integrations/subscribe` with the same body, then\nsubscribe again. Verified on\nDesktop 2026.10.6 with both the probe client and `curl`.\n\n**One-command form (not yet released).** `relay-desktop#216` adds\n`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`\n(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription\nthat the Desktop correlates with the PR's reviews, comments, and checks. It is\nabsent from Desktop 2026.10.6, where it fails with `unrecognized subcommand\n'subscribe'`, so do not lead with it. Use it only when the installed probe\nadvertises it. The block above makes that choice, and first checks the\nsession's existing subscriptions. A pull request already subscribed with the\none-command form is left alone. A pull request already holding\nthe number glob answers 409 `conflict` on a repeat; recreate that binding once\nif it may predate 2026-09-19 (see above). Extra `reviews`, `status` or\n`issues/NUMBER/comments` globs from an earlier version of this skill never\ndeliver; unsubscribe them.\n\nOnce released, re-test it before relying on its details; the behavior described\nin that PR (a repeat answering `\"already_subscribed\":true`, `--remove` to end it,\nand a numeric subscription covering reviews, comments and checks) has not been verified here.\n\nRefusals and what they mean:\n\n- `not_a_relay_session`, \"Register this session before subscribing it\": run\n  section 4's `POST /register` first.\n- `not_a_relay_session`, \"already managed by this computer's relay\" from\n  `/register`: this session was started by the Agent Relay fleet broker, not\n  the Desktop. Use the workspace CLI below instead.\n- `refused` or `busy`: an earlier subscription is still being made or cleaned\n  up; repeat the command shortly.\n\nA fleet-spawned session, or an operator subscribing a named agent, uses the\n`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in\n`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let\nthe worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail\nwith `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`\nis set:\n\n```sh\npull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'\nrelay_cli_major=\nif test -n \"${relay_cli:-}\"; then\n  relay_cli_major=$(\"$relay_cli\" --version 2>/dev/null | sed -n 's/^[^0-9]*\\([0-9][0-9]*\\)\\..*/\\1/p' | sed -n '1p')\nfi\nif test -n \"$relay_cli_major\" && test \"$relay_cli_major\" -ge 13; then\n  \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelif test -n \"$relay_cli_major\"; then\n  # 12.x and older: keep the ambient agent token from displacing the key.\n  env -u RELAY_AGENT_TOKEN \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelse\n  # No usable installed CLI: run the fixed release without installing it.\n  npx -y agent-relay@13 integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nfi\n```\n\nUse the `relay_cli` found in section 2, never a bare `agent-relay`: on a\n`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may\nresolve to it or to a different, older CLI than the one whose version was\nchecked.\n\nThe CLI path follows `orchestrating-agent-relay`, which subscribes the same\nsingle `pulls/NUMBER/**` glob. Never put the workspace key in argv.\n\nMake the subscribe step a required post-create step in the agent's PR\nworkflow: whenever it authors a PR, it subscribes its own live session\nimmediately, without waiting for an operator to name the PR. This is the\nauthored-PR pattern from `orchestrating-agent-relay`; it covers every future PR\nthe agent authors without subscribing unrelated repository traffic. The\nDesktop removes the subscription itself after the PR closes or merges.\nFor real GitHub verification, use a harmless event the human authorized\non that PR (for example, a test conversation comment and a requested bot\nreview). After causing the event, do not wait or poll within the active turn:\nend the turn saying which event marker is expected. Confirm the injected event\nand record its full message id on the next turn after Relay has delivered it.\nDo not create a comment, review, or rerun without authorization. A successful\nsubscribe response alone does not prove end-to-end delivery.\n\n## 7. Coexist with a REST-polling MCP\n\nDo not disable an existing polling consumer. Desktop injection acknowledges\nonly this registered agent's delivery queue and does not advance a separate\nworkspace consumer's cursor. A polling MCP should use its own identity/cursor,\nnot this session agent's `/v1/deliveries` token.\n\nInjected text contains both the full Relaycast message id and a short `ref`.\nWhen polling and injection can surface the same workspace message, deduplicate\non the full message id before acting. During verification, leave the poller\nrunning and observe the test message there. Then end the current turn so Relay\ncan inject it, and on the next turn confirm the same full id arrived while the\nagent acted only once.\n\n## 8. Final verification and report\n\nRead status again:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'\n```\n\nRequire all three defaults before declaring setup complete. Set\n`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the\nexisting mode the human kept); the check refuses to guess it:\n\n```sh\n: \"${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -e --arg mode \"$relay_sharing_mode\" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'\n```\n\nReport the exact version, `signed_in`, signed-in workspace id and name, sharing\nmode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,\nuploader health, session address, direct-delivery state, webhook test marker,\nsubscriptions, real GitHub event evidence, and polling-coexistence result.\nSeparate verified facts from steps that still require a human or external\nevent.\n\n## Recovery and undo\n\n- **Socket missing or slow:** check `systemctl --user status agent-relay.service`\n  on Linux or `open -a \"Agent Relay\"` on macOS. Confirm the pointer names a\n  socket. Never delete a live socket; restart the owning service/app. A reply\n  that takes up to about 30 seconds is the known latency in section 1\n  (relay-desktop#333), not a fault: allow 60 seconds and retry once.\n- **`not_a_relay_session`:** the command is not a descendant of a supported\n  live Codex/Claude session, or the session id/process start no longer matches.\n  Run it through this agent's shell tool. In tmux, confirm the agent process and\n  shell share the pane's process tree.\n- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message \"An older\n  managed history uploader is active. Stop it explicitly before enabling this\n  probe.\"): the probe counts any of these legacy `ai-hist push` registrations as\n  active, even when idle: the file\n  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded\n  launchd label `com.ai-hist.push`, or a crontab line containing\n  `# ai-hist push (managed)`. Check each, then with the human's approval unload\n  and move aside (do not delete) what exists. Create the backup directory first,\n  use a unique no-clobber destination, and confirm the move before retrying:\n\n  ```sh\n  # bootout exits non-zero when the label was never loaded; that is fine, so\n  # judge success by whether the label is still loaded, not by its exit code.\n  launchctl bootout \"gui/$(id -u)/com.ai-hist.push\" 2>/dev/null || true\n  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then\n    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2\n    exit 1\n  fi\n  plist=\"$HOME/Library/LaunchAgents/com.ai-hist.push.plist\"\n  if test -e \"$plist\"; then\n    backup_dir=\"$HOME/.agentworkforce/backup\"\n    mkdir -p \"$backup_dir\"\n    mv -n \"$plist\" \"$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)\"\n    test ! -e \"$plist\" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }\n  fi\n  ```\n\n  If instead the marked cron line is the cause, back up the full crontab first\n  and remove only that line, so the change can be reversed with\n  `crontab <backup-file>`:\n\n  ```sh\n  mkdir -p \"$HOME/.agentworkforce/backup\"\n  cron_backup=\"$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)\"\n  crontab -l > \"$cron_backup\" && test -s \"$cron_backup\" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }\n  grep -vF '# ai-hist push (managed)' \"$cron_backup\" | crontab -\n  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }\n  ```\n\n  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run\n  `/setup/sign-in` with the same payload.\n- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the\n  request. Restart after `expired` or `denied` to obtain a new code.\n- **Older schedules could not be inspected:** inspect the user's legacy cron,\n  launchd, or user-service upload schedules first. Only after that inspection,\n  retry `/setup/sign-in` with the original payload plus\n  `\"acknowledge_uninspected_schedules\":true`. This flag records a completed\n  safety check; never send it merely to silence an error.\n- **`not_allowed` from `/register`:** enable the app's self-registration\n  setting. Do not bypass it with workspace credentials.\n- **Managed Claude policy:** if direct delivery reports `managed_policy`, the\n  organization controls `crossSessionInbound`; report the policy block rather\n  than modifying managed settings.\n- **Undo registration:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/register | jq`.\n- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,\n  `relay_req`, and `pr_resources` defined, remove every subscription the\n  session holds for the pull request, in whichever form it was made. On macOS\n  `relay_req` uses the probe, and a Codex session without one stops instead of\n  sending a `curl` request that cannot be identified:\n\n  ```sh\n  held=$(pr_resources) || exit 1\n  printf '%s\\n' \"$held\" | while IFS= read -r resource; do\n    test -n \"$resource\" || continue\n    relay_req DELETE /integrations/subscribe \\\n      \"$(jq -nc --arg resource \"$resource\" '{provider:\"github\",resource:$resource}')\" | jq\n  done\n  relay_req GET /setup/status | jq -c '.data.integrations'\n  ```\n\n  Require the final list to hold none of that pull request's resources.\n- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/webhooks | jq`.\n- **Undo direct delivery:** POST `{\"enabled\":false}` to\n  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed\n  organization policy still wins.\n- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to\n  `/setup/sharing`. Ask before changing it when the earlier value is unknown.\n- **Auto-activate accidentally enabled:** POST `{\"enabled\":false}` to\n  `/setup/auto-activate`. This does not remove existing registrations.\n- **Uninstall:** stop/disable the user service before removing the Linux\n  package, or quit the Mac app before removing it. Do not delete app data or\n  revoke webhooks unless the human explicitly asks for data removal.\n",
+  "setting-up-agent-relay-sessions": "# Set Up Agent Relay Session Handoff\n\nDrive the whole onboarding from this agent's own shell and MCP tools. Do **not**\nhand the person the six-step Markdown guide and ask them to click through the\napp and the dashboard.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the desktop app is installed, signed in to the **intended workspace**, the\n  uploader is healthy, and this session is registered with direct delivery on;\n- the **agent-sessions cloud MCP** is installed in this project and loaded by\n  this session, so the handoff tools (`list_relay_agents`, `send_relay_message`,\n  `read_relay_conversation`, `check_relay_inbox`, `get_shared_session`,\n  `get_shared_session_context`, `search_shared_sessions`) are available;\n- a live round trip is proven when a teammate is online: this agent messages the\n  teammate's agent, **reads the teammate's real session back** with\n  `get_shared_session_context`, and the teammate reads this session and replies.\n  When no teammate is online yet, the fallback is the roster plus this person's\n  own uploaded session reading back cleanly — reported as self-verified, not as a\n  proven two-way handoff.\n\n## Requires\n\nThis skill builds on `setting-up-agent-relay-desktop` (verified install, sign-in,\nregistration, agent-led defaults). If that skill is **not installed** in this\nagent, stop, tell the person, and have them install the companions together,\nthen restart the agent. Do not improvise the install or sign-in from memory.\n\n- prpm: `npx prpm install collections/agent-relay-setup --as claude --global -y`\n- skills.sh: `npx skills add https://github.com/AgentWorkforce/skills --skill setting-up-agent-relay-desktop --skill setting-up-agent-relay-sessions`\n- Codex: do not use prpm's `--as codex` (it drops paragraphs and writes under `~/.agents/skills`, which Codex does not load as its global skill folder). Mirror both installed `SKILL.md` files into `~/.codex/skills/<name>/` with the loop in **Install this skill (and its dependency)** below.\n\n## The only human steps\n\nEverything else is automatable; be honest that these are not. **Ask for all of\nthem up front, before touching anything** — the token in particular is needed\nonly at section 3, but minting it and exporting it into the launching\nenvironment takes the person a few minutes, so have them start it while the\ndesktop install and sign-in run:\n\n1. **Approve one Google device-login link** — only when no reusable `agent-relay`\n   CLI/desktop login exists. A reused login needs zero clicks.\n2. **Provide one Bearer token** minted in the dashboard's **\"Connect your agent\"**\n   card. No setup route returns this token by design. **Do not have the person\n   paste it into this conversation** — the uploader shares this session's prompts\n   with teammates, so a pasted secret would become teammate-readable. Instead the\n   person puts it into the **environment that launches their agent** (or an OS\n   keychain / a mode-0600 file) via a shell *they* run, and this agent references\n   it only by variable name — never by value. See **Token handling** below.\n3. **Same workspace, both sides.** The teammate (or workspace admin) must have\n   invited this person's email to the **shared** workspace — two agents can only\n   reach each other inside one workspace. Confirm the workspace id matches on\n   both machines; do not guess it.\n\nOne structural note so expectations are right: there is **no automatic ack** to\nthe sender when a handoff is picked up, and **no partial session sharing** — a\nsession is on-or-off on the relay. Confirm a handoff by activity, not a push.\n\n## How this composes with `setting-up-agent-relay-desktop`\n\nThis skill is a thin layer on a working desktop. The desktop skill owns install,\nsign-in, defaults and self-registration; this one owns only the agent-sessions\ncloud MCP and the live handoff. Section 2 checks the desktop prerequisite and,\nif it is not met, invokes `/setting-up-agent-relay-desktop` to completion and\nreturns here. Keep the `/setup/*` details in that one skill so a contract change\nupdates it once.\n\n## Install this skill (and its dependency) for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage **and** the desktop skill it depends on, then mirror both unchanged\n`SKILL.md` files where Codex loads global skills:\n\n```sh\nfor pkg in setting-up-agent-relay-sessions setting-up-agent-relay-desktop; do\n  npx prpm install \"@agent-relay/$pkg\" --as claude --global -y\n  codex_skill=\"$HOME/.codex/skills/$pkg\"\n  mkdir -p \"$codex_skill\"\n  install -m 0644 \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\n  cmp \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\ndone\n```\n\nWith skills.sh instead, use the command under **Requires**; it installs into each agent's skills folder directly, so the manual Codex mirror below is only for the prpm route.\n\nDo not use prpm's `--as codex` conversion for these packages: it writes under\n`~/.agents/skills`, which Codex does not load as its global skill folder, and it\ndrops explanatory paragraphs from the Markdown workflow. Confirm both final\npaths explicitly before continuing.\n\n## Why ordering matters\n\nMCPs load at agent **startup**. The agent-sessions MCP must be installed\n**before** the session that will use it starts. A session already running when\nthe MCP was added has no handoff tools and must be **restarted**. Install the\nMCP (section 3) before relying on the tools (sections 4–5); if this very session\npredates the MCP, say so and restart it rather than reporting missing tools as a\nfailure.\n\n## Token handling\n\nThe token must never land in the agent conversation, in a Relay message, in\nprocess argv, or in the repo. Three places leak it, and this skill avoids all\nthree:\n\n- **The chat** — this session is uploaded and teammate-readable, so a token\n  pasted to the agent leaks to the workspace. The person sets it themselves (see\n  below); the agent only ever sees the variable **name**.\n- **Process argv** — a token interpolated into `claude mcp add --header\n  \"... Bearer $TOKEN\"` is visible to `ps` and gets written literally into\n  `~/.claude.json`. Pass the unexpanded placeholder `${AGENT_RELAY_SESSIONS_TOKEN}`\n  instead; Claude Code expands `${VAR}` in MCP headers from the environment at\n  launch, so the stored config holds only a reference and argv holds only the\n  literal `${…}`. **This expansion exists only in Claude Code ≥ 2.1.119** — an\n  older client sends the placeholder literally and auth fails, so check the\n  version first (section 3) and update Claude rather than inlining the token.\n- **The launching environment** — both CLIs read the token from an environment\n  variable (`${VAR}` for Claude, `--bearer-token-env-var` for Codex), so the\n  variable must exist in the environment that **launches the agent**, not in a\n  transient shell-tool subprocess (which cannot alter its parent or a later\n  process).\n\nUse the single variable name `AGENT_RELAY_SESSIONS_TOKEN` throughout. Keep the\none-time entry separate from durable supply:\n\n- **One-time, into the current shell** (non-echoing, run by the person, never\n  the agent): `read -rs AGENT_RELAY_SESSIONS_TOKEN && export AGENT_RELAY_SESSIONS_TOKEN`,\n  then launch the agent from *that* shell. Do **not** add this `read` to a shell\n  profile — every shell that sources the profile would block waiting for input.\n- **Durable across restarts:** store the token in the OS keychain or a mode-0600\n  file, and have the launcher export it **non-interactively**, e.g.\n  `export AGENT_RELAY_SESSIONS_TOKEN=\"$(security find-generic-password -s agent-relay-sessions -w)\"`\n  (macOS keychain) or from a 0600 file. Put that line in a dedicated launcher the\n  person starts the agent from — not an interactive prompt in the profile.\n\nThe agent never prints the value; verify presence only with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"`.\n\n## 0. Preflight: collect the human inputs first\n\nBefore section 1, tell the person what they need and ask for it in one message:\n\n1. the **shared workspace id** (or the teammate/admin who invited them);\n2. a **Bearer token** minted in the dashboard's \"Connect your agent\" card for\n   that workspace, stored by *them* as `AGENT_RELAY_SESSIONS_TOKEN` in the\n   environment that launches their agent (see **Token handling** — never pasted\n   into this chat);\n3. the **teammate's relay address** for the round trip, if one will be online.\n\nBefore sending that message, check what this machine already has. If an Agent\nRelay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not\nthe `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only\nchecks. Without one, section 2 reads the signed-in workspace from\n`/setup/status` instead. The CLI is optional for this skill: detect it as\nbelow, which skips the Desktop launcher that `command -v agent-relay` finds on\na `.deb` install, and do not install or upgrade it just for these checks.\n\n```sh\nrelay_cli=$(command -v agent-relay || true)\ncase \"$relay_cli\" in ''|/usr/bin/agent-relay) relay_cli= ;; esac\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nIf the active workspace is already the shared one, confirm it with the person\ninstead of asking them to look it up. Never switch to or create another\nworkspace unless they explicitly ask.\n\nCheck presence without printing the value:\n\n```sh\ntest -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\" && echo token=present || echo token=missing\n```\n\nA missing token does **not** block sections 1–3: the MCP config stores only a\n`${AGENT_RELAY_SESSIONS_TOKEN}` reference, never the value, so it can be added\nnow. Do the desktop work and add the MCP, then have the person restart the agent\n**once**, from an environment that exports the token, so that single restart both\nloads the MCP and supplies the credential. Sections 4–5 are gated on that\nrestart. If the person would rather not defer, they can export the token and\nrestart first, which then costs a second restart only if the MCP was added after.\n\n## 1. Confirm the host and this session\n\nRun every command from this agent's own shell tool, and only from a **genuine\ninteractive** Claude Code or Codex session. The app identifies the caller from\nkernel credentials and resolves its process ancestry against discovered live\nsessions, so a command from an unrelated terminal — or from a non-interactive\n`codex exec` / `claude -p` run — is rejected with `not_a_relay_session`. (This\nis verified: a plain SSH shell and a `codex exec` invocation are both refused;\nan interactive session is admitted.)\n\n```sh\nuname -s; uname -m\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\n```\n\nDefine the request helper once per shell. It finds the private setup socket\nwithout printing private files and uses the desktop's `agent-relay-probe` on\nmacOS (the system `curl` hides a Codex session's identity there and is refused\n`not_a_relay_session`), `curl` elsewhere, and stops with a message for a macOS\nCodex session that has no probe:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Linux; then\n  for c in \"${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock\" \"/run/user/$(id -u)/agent-relay/relay.sock\"; do\n    if test -S \"$c\"; then relay_socket=$c; break; fi\n  done\nfi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Darwin; then   # pointer file missing: use the app's own socket\n  c=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\n  if test -S \"$c\"; then relay_socket=$c; fi\nfi\nrelay_probe=\nfor c in \"$HOME/.local/bin/agent-relay-probe\" \\\n         /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n         \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"; do\n  if test -x \"$c\"; then relay_probe=$c; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then   # per-user tarball\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\n# relay_req METHOD PATH [JSON-BODY]\nrelay_req() {\n  if ! test -S \"${relay_socket:-/nonexistent}\"; then\n    echo 'No Agent Relay socket found; start Agent Relay (the desktop) and retry.' >&2\n    return 1\n  fi\n  if test \"$(uname -s)\" = Darwin && test -n \"$relay_probe\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    echo 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename\n    printf '%s' \"$3\" | curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' --data-binary @- \"http://relay$2\"\n  else\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add\n`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a\nfailure. The probe's `relay socket-request` can give up sooner with \"Probe\ncould not finish. Check your connection and run setup again\"; on these paths\nthat is the same latency, not a setup problem. Retry once before reporting a\nblocker, and do not rerun desktop setup because of it.\n\n## 2. Make sure the desktop is set up first\n\nSession handoff needs a signed-in, healthy desktop underneath it. If the socket\nis missing, or `/setup/status` returns `404`, or sign-in/uploader/registration\nare not in the finished state below, **invoke the `setting-up-agent-relay-desktop`\nskill** (`/setting-up-agent-relay-desktop`; if it is not installed, see **Requires**), let it run to completion, and then\nreturn to section 2's verification. Do not re-implement its install, sign-in, or\n`/setup/*` steps here — that skill is the single source of truth for them, and\nthis skill resumes once it reports a registered, signed-in session.\n\nVerify the desktop state this skill depends on:\n\n```sh\nrelay_req GET /setup/status | jq '{\n  version: .data.version,\n  sign_in: .data.sign_in,\n  workspace: .data.workspace,\n  sharing_mode: .data.sharing_mode,\n  uploader: .data.uploader,\n  direct_delivery: .data.direct_delivery,\n  session: .data.session,\n  defaults_error: .data.defaults_error\n}'\n```\n\nRequire all of these before continuing, and stop with a clear message if any\nfails. `/setup/status` reports sign-in as the string `sign_in` (match the desktop\nskill), and the flag that actually governs whether **this** session's handoff\nreplies arrive live is the session-level `session.direct_delivery`, not the\ntop-level default — require both:\n\n```sh\nrelay_req GET /setup/status | jq -e '\n  .ok\n  and .data.sign_in == \"signed_in\"\n  and (.data.workspace.id | type == \"string\" and length > 0)\n  and .data.uploader.healthy == true\n  and .data.direct_delivery == true\n  and (.data.session.id | type == \"string\" and length > 0)\n  and .data.session.registered == true\n  and .data.session.direct_delivery == true'\n```\n\nConfirm `workspace.id` is the **shared** workspace both sides agreed on. A\nhealthy uploader is the one non-obvious prerequisite: for a teammate's agent to\nread **this** person's session, this machine must have uploaded it. If\n`uploader.healthy` is false (paused, or a failed cycle), fix it before promising\nanyone can read this session — this is the single most common reason a live\nhandoff silently fails.\n\n`sharing_mode` decides which sessions upload at all, and a healthy uploader\ndoes not prove that **this** session is among them. `all` includes it. `new`\nincludes sessions that started after `new` was enabled, so a session that was\nalready running when the desktop was set up may not be uploaded. Under\n`selected`, only the sessions the person chose upload. Unless the mode is\n`all`, tell the person that this session may not be shared yet, and ask them to\nselect it in the app or to continue from a new session; do not change the\nsharing mode or select sessions on their behalf. Section 5's round trip is the\nproof: if the teammate cannot read this session there, this is the first\nthing to check.\n\n## 3. Install the agent-sessions cloud MCP (before the session uses it)\n\nCheck whether the token is present in the environment **without printing it**\n(see **Token handling**). It is not required to *add* the MCP, since only a\nreference is stored, but it is required for the tools to authenticate after the\nrestart. If it is missing, add the MCP anyway, tell the person plainly that the\ntools will fail auth until they restart the agent from an environment that\nexports `AGENT_RELAY_SESSIONS_TOKEN`, and do not report setup complete:\n\n```sh\nif ! test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"; then\n  echo 'AGENT_RELAY_SESSIONS_TOKEN is not set here; the MCP will be added by reference, but the agent must be restarted from an environment that exports it.' >&2\nfi\n```\n\nDetect which agent CLI this session runs and install accordingly.\n\nClaude Code — pass the **unexpanded** placeholder so the token stays out of argv\nand out of `~/.claude.json`; Claude expands `${VAR}` in MCP headers from the\nenvironment at launch. This expansion requires **Claude Code ≥ 2.1.119**, so\nverify the version first and update rather than inlining the token on an older\nclient. Single-quote the header so the shell does not expand it here. Default\nscope is `local` (this project only), which is what you want:\n\n```sh\nclaude_ver=$(claude --version 2>/dev/null | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1)\nif test -z \"$claude_ver\" || test \"$(printf '%s\\n2.1.119\\n' \"$claude_ver\" | sort -V | head -1)\" != 2.1.119; then\n  echo \"Claude Code $claude_ver does not expand \\${VAR} in MCP headers (need >= 2.1.119); update Claude Code before adding this server.\" >&2\n  exit 1\nfi\nclaude mcp add --transport http agent-relay-sessions \\\n  https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --header 'Authorization: Bearer ${AGENT_RELAY_SESSIONS_TOKEN}'\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nCodex — `codex mcp add` records the **variable name**, not the value, and writes\nto user-level `~/.codex/config.toml`, so the server is enabled for **all** Codex\nprojects (Codex has no project-scoped MCP). Confirm the person is OK with\nuser-wide access before adding it:\n\n```sh\ncodex mcp add agent-relay-sessions \\\n  --url https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --bearer-token-env-var AGENT_RELAY_SESSIONS_TOKEN\ncodex mcp list | grep -F agent-relay-sessions\n```\n\nBecause MCPs load at startup, the running session must be **restarted** to pick\nup the server — and because both CLIs read the token from the environment at\nlaunch, the restarted process must **inherit** `AGENT_RELAY_SESSIONS_TOKEN`.\nThat is why the variable belongs in the shell profile / launcher, not a transient\nshell-tool subprocess: an `export` in this agent's shell tool cannot reach the\nparent or a freshly launched session. After the restart, re-verify presence with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"` before using the tools, and do not\nreport the tools as missing without first confirming the session started *after*\nthe MCP was added and with the variable set.\n\n## 4. Confirm the handoff tools loaded\n\nIn the session that started after the MCP was added, confirm the tools are\npresent before using them. List this session's MCP tools and check for the\nagent-sessions set; the authoritative check is that the tools actually appear to\nthis agent:\n\n```sh\n# Claude Code: the tools surface as mcp__agent-relay-sessions__*\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nThen call `list_relay_agents` through the MCP (an MCP tool call, not a shell\ncommand). A successful call that returns the workspace roster proves the MCP is\nloaded, the token is valid, and this session can see the shared workspace. If\nthe call errors with auth, the token is wrong or for another workspace — have\nthe person re-mint it from the correct workspace's dashboard.\n\n## 5. Prove one live round trip\n\nThe real proof is agent-to-agent, so it needs a counterpart. Pick the path that\nmatches what is available:\n\n**A teammate's agent is online (full round trip).** Ask the person for the\nteammate's relay address (e.g. `@manav`), then:\n\n1. `list_relay_agents` — confirm the teammate's address is listed.\n2. **Prove the reverse read path first:** call `get_shared_session_context` on\n   the teammate's session and confirm it returns their **real** content (prompts/\n   events + a dashboard citation link). If it errors or is empty, their uploader\n   is unhealthy — stop and have them fix it; do not declare GREEN, because this\n   side cannot actually read their work yet.\n3. `send_relay_message` — send a short, uniquely-marked message to that address.\n4. The teammate's agent reads this session with `get_shared_session_context` and\n   continues; have them reply through the relay.\n5. GREEN requires **both directions**: this agent read the teammate's real\n   content (step 2) **and** the teammate's reply lands here. There is no\n   automatic ack — confirm by the reply/activity, not a push. Because Relay\n   injects an inbound message only when the session is idle between turns, **end\n   the turn** after sending and confirm the reply on the next turn; do not sleep\n   or poll inside one turn.\n\n**No teammate online yet (self-verify the read path).** Prove the machinery\nwithout a second person:\n\n1. `list_relay_agents` returns the roster — MCP + token + workspace are good.\n2. `search_shared_sessions` / `get_shared_session_context` return this person's\n   **own** recently uploaded session (real prompts/events plus a dashboard\n   citation link) — the uploader→read path works.\n3. Record that the two-party round trip still needs the teammate online, and\n   name it as the remaining step rather than claiming the handoff is proven.\n   Setup is not complete until the full round trip succeeds.\n\nNever paste the Bearer token or any session token into a `send_relay_message`\nbody or any artifact.\n\n## 6. Report\n\nSeparate verified facts from what still needs a human or a second machine:\n\n- app version, `signed_in`, the signed-in **workspace id and name**;\n- uploader `healthy`, this session's `agent@machine` address, direct delivery on;\n- agent-sessions MCP installed and its tools confirmed loaded in this session;\n- `list_relay_agents` roster seen; and either the full round-trip evidence (the\n  teammate's real content + reply) or the self-verified read path plus the named\n  remaining step (teammate online).\n\nDo not call the setup complete on a 2xx from `claude mcp add` alone, and do not\ncount a roster listing as a proven handoff.\n\n## Recovery\n\n- **`not_a_relay_session` from `/setup/*`:** the caller is not inside a discovered\n  interactive session. Run it from this agent's own shell inside an **interactive**\n  Claude Code or Codex session — a non-interactive `codex exec` or `claude -p` run\n  is not admitted, and neither is an unrelated terminal. In tmux/SSH, confirm the\n  agent process and shell share the pane's process tree.\n- **No handoff tools in the session:** the MCP was added after the session\n  started, or at the wrong scope. Reinstall at project scope (section 3) and\n  **restart** the session; MCPs load only at startup.\n- **`list_relay_agents` auth error:** the token is wrong, expired, or from a\n  different workspace. Because the MCP config stores only a **reference** to\n  `AGENT_RELAY_SESSIONS_TOKEN`, fixing it means updating the **value in the\n  launch environment** (keychain / 0600 file) and **restarting** the agent so it\n  re-reads it — re-running `claude mcp add` / `codex mcp add` alone changes\n  nothing. Re-mint from the intended workspace's \"Connect your agent\" card if the\n  token itself is bad. On Claude, also confirm the client is ≥ 2.1.119 (older\n  clients send the `${VAR}` placeholder literally).\n- **Teammate's address missing from the roster:** they are not on the **same**\n  workspace, or their session is not on the relay. Have them register their\n  session and confirm the shared workspace id.\n- **Can't read the teammate's session:** their **uploader** is not healthy\n  (paused or a failed cycle). Have them check `/setup/status` shows\n  `uploader.healthy == true`, not \"Sync paused/offline\".\n- **Message arrives held, not live:** direct delivery is off for the recipient —\n  POST `{\"enabled\":true}` to `/setup/direct-delivery` on their machine (Codex\n  delivers directly by default). A managed Claude policy can block this; report\n  it rather than editing managed settings.\n- **Remove the MCP:** `claude mcp remove agent-relay-sessions` /\n  `codex mcp remove agent-relay-sessions`. This removes only the handoff tools;\n  it does not sign the desktop out or stop uploads.\n\n## Relationship to the other skills\n\n- **`setting-up-agent-relay-desktop`** — the layer below this one: install,\n  sign-in, agent-led defaults, self-registration. Use it when section 2 is not\n  yet satisfied.\n- **`relay-connect`** — a lighter, account-free, time-boxed way for two agents to\n  share one session via a hand-over link. Prefer it for an ad-hoc pairing;\n  prefer this skill for durable teammate-to-teammate handoff inside a shared\n  workspace.\n",
+  "setting-up-agent-relay-flows": "# Set Up Agent Relay Flows\n\nDrive the setup through the documented Cloud APIs and the official CLI. Do not\nuse computer use, browser automation, or the dashboard UI. The human approves\nsign-in, tool consent, and provider logins on their own approval pages; open\nthose links with the OS URL opener (or give them the link), then verify by\npolling the API, never by inspecting the browser.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix; the site is `https://agentrelay.com`. The flow\ncatalog is the one exception: it is a site API, served from the site origin\nwithout `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a\nguide names a different site and Cloud base (for example a local development\nstack), use those exact origins throughout, including for the catalog, the\nCLI's `--api-url` and the dashboard links, and never fall back to production.\nFlows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.\n\n## Requires\n\nA signed-in Cloud session: an access token and the `user.id` and\n`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`\nfirst, and send `Authorization: Bearer <access_token>` on every request below.\n\n## API map\n\n- Flow catalog (site origin, not under `/cloud`):\n  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.\n- Tool consent links: `POST /api/v1/integrations/connect-link`; poll\n  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.\n- Coding-agent credentials: the official CLI's `cloud connect` (section 3);\n  `GET /api/v1/cloud-agents` inspects existing connections.\n- Activation: `POST /api/v1/flows/deploy` with the body in section 4.\n- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`\n  reports whether it is available.\n- Verification: `GET /api/v1/flows/listeners/<agentId>`.\n\n## 1. Prebuilt or custom?\n\nAsk the human first, unless their request already says: a **prebuilt** flow\nfrom the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**\nflow of their own? In an agent-driven signup, ask through that guide's\nweb-input protocol on the signup page, not in chat.\n\n- Prebuilt: continue with section 2.\n- Custom: follow **Custom flow: deploy journey** below. A custom flow is\n  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and\n  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is\n  no separate custom API.\n\n## 2. Choose the flow and repository\n\nAsk the human for missing product choices: repository, desired\nworkflow/trigger, and approver. In an agent-driven signup, ask through that\nguide's web-input protocol on the signup page, not in chat. Ask for the approver's\nGitHub username in plain language (for example, \"octocat\" or \"@octocat\"),\nnot an internal provider-address format or their Google email. Normalize the\nanswer to github:@handle when constructing the deploy API request. Human-gate\nreplies are matched to that provider identity. Infer choices from the user's request and current\nrepository where clear.\nDo not invent a repository or enable automation on an unrelated project.\n\nGET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.\nGET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's\nkind before doing anything executable: only an entry with kind: flow (or a\nlegacy entry with kind omitted) is deployable through the direct-source API\nbelow. An entry with kind: extension is discoverable metadata, not a standalone\nlistener. Do not download or deploy its source, even when it declares trigger\nand input fields. Inspect baseFlowId and extension.activation instead. If the\nextension is blocked, report the unmet dependencies and that it can only be\nadded to its base flow after a supported extension activation path is available;\nnever substitute a standalone flow deployment.\n\nFor a deployable flow, use the catalog's\nsupportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and\ninputs.allowedAgents. Name a model per harness in inputs.models when the house\ndefault is wrong (for example {\"claude\": \"claude-sonnet-4\"}); omit it to fund\nthe house default for each declared agent. Download source.rawUrl, verify its bytes against\nsource.sha256, and use that source text unchanged for a recommended flow.\nThe source is TypeScript, not the source URL. Do not guess a template or hash.\n\n## Custom flow: deploy journey\n\nThere is no journey API. A `journey_id` (for example in a\n`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it\nthrough unchanged where you received it, and never call an endpoint with it or\nwait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`\nas a prebuilt one; only where the source comes from differs.\n\n1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,\n   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that\n   skill for the flow's shape and checks; Flows are always v2. Cloud's\n   prompt generator is an optional shortcut: use it only when\n   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it\n   reports unavailable, refuses your session (403 `session_required`), or\n   fails, author with `writing-relayflows` instead; do not retry into it.\n2. Choose its repository, trigger and approver as in section 2.\n3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the\n   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent\n   only when the prompt generator produced one. `base` and `extensions` are\n   optional and only for a flow that names them.\n\nThe human-only steps are the same for both paths: Google sign-in and device\napproval, GitHub and trigger-app OAuth including the repository grants,\nmodel-provider login when section 3 calls for one (not for an ordinary first\nactivation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.\n\n## 3. Connect the required tools and coding agents\n\nUse bearer-authenticated POST /api/v1/integrations/connect-link:\n\n```json\n{\"provider\":\"github\",\"workspaceId\":\"<currentWorkspace.id>\"}\n```\n\nOpen the returned connectUrl for the user to approve. Keep token/sessionToken\nprivate. Connect only the repository and tools the chosen flow requires.\nFor GitHub the user must grant repository access. Repeat with the chosen trigger\nprovider if different. Reuse existing ready connections rather than relinking.\nCheck GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status\nuntil oauth.connected is true (poll with backoff and a bounded timeout); a\nreturned connect link or a closed popup alone does not prove the connection.\nFor the GitHub-triggered Software Garden flow, activation separately checks\nthat the connected GitHub App covers the selected repository. Its trigger\ndoes not require background data indexing, so do not block solely because\nthe broader status.ready is false from queued syncs.\nIf a different flow declares Relayfile data that requires synced records,\nverify that readiness separately before activating it.\n\nDo not connect a Claude or Codex subscription yet. The first three runs use\nCloud's own model key, so no provider login is needed to activate. If the chosen\nflow declares more than one coding agent in inputs.agents, included Cloud runs\ncan fund only one of them per run — connect your own subscription for at least\none declared agent before activating a multi-agent flow. After the included\nruns, activation and launches will ask for your own subscription; only then use\nthe official Relay CLI with the private credential environment from\n`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:\n\nThis promotion depends on Cloud's internal house-key proxy and account\nenrollment. If local activation returns flow_credentials_unavailable or\nflow_model_not_connected before the three promotional runs, treat it as an\ninternal configuration or eligibility issue. Do not ask the user to connect\nClaude/Codex, provide an API key, or choose an inactive draft as a workaround.\nReport the blocker (in a signup, through its Progress API) and have an internal developer\nverify the proxy, promotion flag, provider readiness, and enrollment. Never\ncopy a house key into the agent environment or expose it in this guide.\n\n```sh\nnpx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'\n```\n\nUse anthropic for Claude or openai for Codex, according to the selected flow.\nThe command drives provider login; open its authorization URL for the user,\nand keep the process alive until it confirms the credential is connected.\nGoogle approval does not grant GitHub or model-provider access: those services\nmay require their own consent. Never fabricate credentials or claim consent\nhappened. GET /api/v1/cloud-agents lets you inspect the account's credential\nstate without reconnecting.\n\n## 4. Activate through the same API as web onboarding\n\nPOST /api/v1/flows/deploy with Content-Type: application/json and the bearer\nsession. The token must be the device-flow session from\n`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with\n`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the\nbrowser onboarding handoff: source is TypeScript text, repository is singular,\nand sources contains provider/settings objects. The catalog supplies the source\nreference and defaults; it is not itself a deploy request. The current endpoint\ndoes not accept a flowId/repositories-only catalog activation request or fetch\nthe source for you. For multiple repositories, submit one deployment per\nrepository with a distinct name and handoffId.\n\nFor the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the\nworkspace, verified source, repository, GitHub approver and a new UUID:\n\n```json\n{\n  \"workspaceId\": \"<currentWorkspace.id>\",\n  \"name\": \"Software Garden\",\n  \"workflow\": \"software-factory\",\n  \"source\": \"<verified TypeScript source text>\",\n  \"handoffId\": \"<one UUID generated for this setup>\",\n  \"inputs\": {\"approver\": \"github:@octocat\", \"agents\": [\"claude\"]},\n  \"mode\": \"activate\",\n  \"repository\": {\"owner\": \"acme\", \"name\": \"api\"},\n  \"sources\": [{\"provider\": \"github\", \"settings\": {\"repository\": \"acme/api\"}}]\n}\n```\n\nFor another deployable kind: flow catalog entry use its id as workflow, allowed agents, and\ndefaultTrigger for sources, then apply the user's trigger settings. Scope a\nGitHub issue trigger with settings.repository set to the chosen owner/name;\nfor GitLab use settings.project. Cloud does not derive this filter from the\ndeployment repository. An empty filter can trigger on other repositories in\nthe workspace. Only use a different trigger scope when explicitly requested.\nGive each repository its own trigger filter for multi-repository setup. Do not send\nthe example acme repository or octocat approver unchanged. The workflow field\nis a label, not a source lookup; keep the verified source in the request.\nFor GitLab set repository.host to gitlab and use the namespace path\nas owner. Reuse the handoffId on retry. Before retrying an ambiguous network\nfailure, GET /api/v1/flows/listeners and check whether the flow already exists;\ndo not create a new ID/name on every retry. Activation subscribes to matching\nfuture events and can run work; confirm the intended repository and trigger\nwith the user if they have not specified them.\n\nHTTP 201 must contain agentId and status: listening. A draft is not completion.\nFor a 409 workspace_mismatch, verify the active workspace; for connection\npreflight failures, fix the indicated connection before retrying. If the user\nwants to save incomplete work, use mode: draft explicitly and report that it\nis inactive. Never mask activation failures by silently falling back to draft.\n\n## 5. Verify\n\nGET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and\nverify its repository and sources match the request. Open\nhttps://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,\nworkspace, repository, trigger, and verified listening state. This proves\nactivation; only an actual completed run proves execution. Do not create a\nreal issue or launch paid work merely to make the onboarding check turn green.\nDelete temporary authentication files after the work is complete.\n\nThe desktop app is optional for Flows. If the user also wants local session\nsharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`\nwith the same account (an agent-driven signup can follow\nhttps://agentrelay.com/signup/agent/teams).\n",
   "writing-relayflows": "# Writing Relayflows\n\n## Overview\n\nRelayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real — a journal write that fails fails the step, with no silent fallback.\n\n**Name collision warning.** This repo also has skills for an older, unrelated engine that is *also* casually called \"Relayflow\" (singular) — `@relayflows/core`'s `WorkflowBuilder`, a chained builder (`workflow('name').pattern('dag').agent(...).step(...).run()`). That's `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`'s territory. This skill is the **v2** engine: `@relayflows/surface`'s `flow()` function and the YAML/JSON dialect compiled by `@relayflows/sdk`. If you see `.pattern(`, `.agent(` as a chained builder call, or `ctx.workflow.run()`, you're in the other engine — stop and use one of those skills instead.\n\n## When to use this skill\n\n- Writing a new `.flow.ts` or `.flow.yaml`/`.flow.json` for the `flows` CLI (package `@relayflows/sdk`, binary name `flows`).\n- Deciding whether a step needs `run` (shell), `llm` (bare model call), or `agent` (harnessed coding agent in a workspace).\n- Choosing a verification gate that will actually run — a wrong choice here compiles fine and fails at `flows run` time, not authoring time.\n- Wiring up `cli`/`model` for an `agent` or `llm` step, in either language.\n- Debugging a `REFUSED [...]` message from `flows check` or `flows run`.\n- Deciding between running a flow locally, deploying it to listen for tickets, or scheduling it on a cron.\n\n## The ladder\n\nThree step verbs, one per rung (`@relayflows/sdk`'s `StepType = 'deterministic' | 'llm' | 'agent'`):\n\n1. **`run` / `deterministic`** — a shell command. No model. Implicit gate is `exit_code == 0`.\n2. **`llm` / `llm`** — a bare model call. Prompt in, verified output out. No workspace, no tool use.\n3. **`agent` / `agent`** — a harnessed coding agent in a workspace. Returns `{ summary, artifacts }`, not raw text.\n\nPlus resident verbs that aren't ladder rungs: `human` (durable approval), `dispatch` (a direct child flow declared in `use`), and `done` (typed finish). `dispatch` executes in `2.0.35` and newer; see **Human approval and direct child flows**. The generated **helper** namespace (`f.slack`, `f.github`, `f.linear`, `f.notion`, `f.jira`, and 30+ others — see **Helpers**) and YAML `on`/triggers are separate surfaces.\n\nMost flows only need `run` and `llm`. Climb to `agent` once a step needs hands on a real workspace.\n\n## Two ways to author the same thing\n\n**YAML/JSON** is data: `flows check` or CI can validate it without running anything. **TypeScript** calls the same primitives imperatively as ordinary async code. Both compile to the same journal.\n\n### TypeScript\n\n```ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('hello', { budget: { wallclock: '10m' } }, async (f) => {\n  const greeting = await f.run('echo \"Hello from Relayflows\"');\n  console.log(greeting.trim());\n\n  const answer = await f.agent('greeter', {\n    task: 'Reply with one short hello sentence. Do not use tools or modify files.',\n    cli: 'claude',\n    model: 'claude-sonnet-4-6',\n  });\n  console.log(answer.summary);\n\n  f.done('success');\n});\n```\n\n### YAML\n\n```yaml\nversion: '0.1.0'\nname: hello\nsteps:\n  - id: greeting\n    type: deterministic\n    command: 'echo \"Hello from Relayflows\"'\n  - id: greeter\n    type: agent\n    dependsOn: [greeting]\n    instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'\n    cli: claude\n    model: claude-sonnet-4-6\n```\n\n**Version note.** The contracts below were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations. Direct `use`/`f.dispatch` composition requires `2.0.35` or newer. `AgentOptions.permissions` landed in `2.0.17`; predicate `.gate()` and `artifact_exists` landed with [flows#449](https://github.com/AgentWorkforce/flows/pull/449); `f.human` was already executable in `2.0.22`.\n\n## The real `Ctx` contract (TypeScript)\n\nFrom the shipped `@relayflows/surface@2.0.35` `.d.ts` files (`dist/context.d.ts`, `dist/step.d.ts`, `dist/flow.d.ts`, `dist/completion.d.ts`):\n\n```ts\nexport interface AgentResult {\n  summary: string;\n  artifacts: string[];\n}\n\nexport interface PermissionsSpec {     // exported from the package root\n  fileGlobs?: string[];\n  networkAllowlist?: string[];\n  accessPreset?: 'readonly' | 'readwrite';\n}\n\nexport interface AgentOptions {\n  task: string;\n  workspace?: string;\n  permissions?: PermissionsSpec;         // since 2.0.17 — declared and journaled, NOT enforced\n  cli?: string;\n  model?: string;\n  cwd?: string;                          // working dir for the CLI subprocess; defaults to the flow-runner's cwd\n  transport?: 'direct' | 'relay';        // see Agent-relay transport, below\n}\n\nexport interface LlmOptions {\n  output: Record<string, unknown>;       // JSON Schema, checked before the journal accepts the result\n  cli?: string;\n  model?: string;\n}\n\nexport interface DispatchResult {\n  name: string;\n  completionReason: 'success';\n  completionDetail?: string;\n}\n\nexport interface Ctx extends Helpers {   // Helpers = f.slack, f.github, f.linear, f.notion, ... — see Helpers\n  readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;\n  run(command: string, options?: { timeout?: string | number }): Step<string>;\n  llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;\n  llm(prompt: string, options: LlmOptions): Step<unknown>;\n  agent(name: string, options: AgentOptions): Step<AgentResult>;\n  human(question: string, options: { to: string }): Step<boolean>;\n  dispatch(flow: string, input: unknown): Step<DispatchResult>;\n  done(reason: FlowCompletionReason): void;\n  cloud: CloudHelper;\n  memory: MemoryHelper;\n}\n```\n\nDo not add fields to `AgentOptions`/`Ctx` that aren't in this list — they don't exist in the shipped SDK. In particular: **no flow-level named-agent selector on `f.agent`, no `recoveryMode`/`surfaces`/`output`** on the TypeScript call site. Those stay YAML/JSON step fields. `FlowHeader` (`dist/flow.d.ts`) allows `use`, `identity`, `memory`, `budget`, `tools`, `workspace` — no bare `agents` map key (TypeScript composes reusable flows via `use: string[]` instead — see **Named agents and flow composition**). An unknown *header* field throws a `TypeError` at authoring time, before anything is journaled; an unknown `AgentOptions` field is caught by `tsc`, not at runtime.\n\n**`permissions` is a real TypeScript option and it does not sandbox anything.** Since `2.0.17` it is on `AgentOptions`, validated by the SDK, lowered to `file_globs`/`network_allowlist`/`access_preset` and journaled with the step — and nothing reads it to gate a file or a network call. `flows check` warns `permissions_unenforced` on any declaration, including `{}`. Enforcement is [flows#442](https://github.com/AgentWorkforce/flows/issues/442). Declare it to record intent; do not rely on it to contain an agent.\n\n`run()`'s second argument is a real, current option: `{ timeout?: string | number }` — a duration string (`\"15m\"`) or milliseconds. Every real cookbook example that runs something slower than a few seconds sets this explicitly.\n\n### `f.done()`'s closed set is six values, not four\n\n```ts\nexport const FLOW_COMPLETION_REASONS = ['success', 'step_failed', 'canceled', 'budget_exceeded', 'needs_human', 'declined'] as const;\n```\n\nAn authored body can meaningfully call `f.done('success')`, `f.done('step_failed')`, `f.done('needs_human')` (parks the run — it's not a kernel cancellation), or `f.done('declined')` (a deliberate decision not to act — also not a cancellation). `'canceled'` and `'budget_exceeded'` exist in the same closed set but are the **kernel's** to record; a body calling them itself is calling the wrong verdict for what actually happened. The verdict for a human declining a durable approval is `f.done('declined')`, not `f.done('canceled')` — a human declining is a decision, not the kernel calling off the run.\n\n`Step<T>` (`dist/step.d.ts`) is a `PromiseLike<T>` with one extra method, `.gate(...)` — see **Verification gates**. Every awaited step must actually be awaited — an unawaited or manually-`.then()`-chained step is refused (`unawaited_step` / a manual `.then()` is not an await), not silently dropped.\n\n## Verification gates\n\nVerification is control flow, not decoration — a gate decides whether a step actually completed, not just whether the process exited cleanly.\n\n### YAML/JSON (`@relayflows/sdk`'s `VerificationSpec`)\n\n```ts\nexport type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate | NamedDataGate;\n// NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate\n//              | ArtifactExistsGate\n```\n\n- `exit_code` — implicit default for `deterministic` steps. Not configurable; writing it explicitly is allowed and compiles to the same thing as omitting it.\n- `output_contains` — step output (stdout tail, or the LLM value stringified) contains `value`.\n- `json_schema` — step output validates against a JSON Schema (`boolean | Record<string, unknown>`). Used for structured LLM/agent output; `output?: JsonOutputSchema` on an `llm`/`agent` step is sugar that compiles to this.\n- `subprocess_gate` — runs `command` under `/bin/sh`, judged on its exit code. The gate that actually works for \"check a file the agent wrote\": `{ type: 'subprocess_gate', command: 'test -s review.md' }`. If you also need to inspect the step's own output (via `from_output`), the SDK's generated wrapper reads its internal `FLOWS_INPUT` env var, extracts the value, and passes it to *your* command as `$INPUT` — `FLOWS_INPUT` itself is never visible to the author's command, only `$INPUT` is: `{ type: 'subprocess_gate', command: 'echo \"$INPUT\" | grep -q PASSED', from_output: ['summary'] }`.\n- `regex_match` — the step's output (or a value at `in_output_at`) matches `pattern`, evaluated by a non-backtracking RE2 engine (only `i`, `m`, `s` flags).\n- `artifact_exists` — passes when the step's journaled `artifacts` list contains `path` (working-directory-relative POSIX). It reads the journal, not the disk, so it sees exactly what the worker measured at `step.completed`; a path the worker never journaled reads as missing even when the file is there.\n- `word_count_bounds`, `references_input` — narrower named gates; see `packages/sdk/src/named-gates.ts` in the flows repo for the exact contract.\n\n```yaml\n- id: classify\n  type: llm\n  prompt: 'Classify this ticket as bug, feature, or question: \"the export button does nothing\"'\n  cli: claude\n  model: claude-sonnet-4-6\n  verification:\n    type: output_contains\n    value: bug\n```\n\n### TypeScript (`Step<T>.gate(...)`) — read this before you write one\n\n`Step<T>` has **two** overloads, and **one `.gate()` per step** — a second throws `unsupported_gate`:\n\n```ts\ngate(config: NamedGate): Step<T>;\n// NamedGate = ReferencesInputNamedGate | SubprocessNamedGate | WordCountBoundsNamedGate\n//           | RegexMatchNamedGate | ArtifactExistsNamedGate\n// — the surface-visible subset of NamedDataGate above. Data, not code: `flows check` can prove it.\n\ngate(predicate: (value: T) => boolean, because?: string): Step<T>;\n// Runs since flows#449. The executor calls the closure once, on the journaled value, and\n// journals the VERDICT as a lowered `<step>.gate` step — so resume and replay read the\n// recorded verdict and never re-run the function. A false verdict fails the run as\n// `gate_failed`, carrying `because`.\n```\n\nThe predicate form was refused with `unsupported_gate` through `2.0.16`; on `2.0.22` it runs. **Prefer the config-object form anyway** — `flows check` cannot prove a predicate (docs/SURFACE.md §6), so a named gate is the only kind a preflight can tell you about before you spend a run:\n\n```ts\nconst outdated = await f.run('npm outdated --json 2>/dev/null || true')\n  .gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\"' });   // provable by `flows check`\n\nconst review = await f.agent('review', { task: '…', cli: 'claude' })\n  .gate({ type: 'subprocess_gate', command: 'test -s review.md' });  // checks a file the agent wrote, ignores $INPUT\n```\n\n(Verified for real: `.gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\" && echo \"$INPUT\" | grep -q pkg' })` against a step outputting `{\"pkg\":\"left-pad\"}` passes — `$INPUT`, not `$FLOWS_INPUT`, is what the author's command sees. `FLOWS_INPUT` is an env var the SDK's own generated wrapper reads internally to extract the value before invoking your command; it is never visible to `command` itself.)\n\nAn agent step rarely fails by crashing; it fails by returning something plausible and wrong, which a plain retry-on-error never catches. Validate every `agent`/`llm` result, either directly with a supported gate or in a following deterministic verifier.\n\n**Where to put that check depends on what you want a red result to do.** A config-object or predicate gate directly on the agent/LLM step ends the run when it fails; use it when that failure should be terminal. For repairable failures, the following deterministic verifier must explicitly read the preceding output or workspace, produce its own verification result, and record it for repair. Output-dependent gates inspect the step they guard: moving the same gate unchanged would inspect the verifier's output, not the agent's. Use the record/repair/re-record/assert pattern in `relay-80-100-workflow`, gating the final verification result after repair.\n\n## Helpers: journaled effects, not just Slack\n\n`Ctx extends Helpers`, and `Helpers` is generated from 40+ provider adapters shipped in `@relayflows/surface` — `slack`, `github`, `linear`, `jira`, `notion`, `salesforce`, `postgres`, `s3`, `redis`, `daytona`, `gmail`, `google-calendar`, `hubspot`, and more (`dist/helpers/index.d.ts` lists them all). A helper call — `f.slack.post(channel, text)`, `f.github.comment(...)` — compiles to a journaled effect: the receipt the helper returns *is* the journal record, so a retried step that already posted doesn't double-post; the second attempt is deduped by `(step_id, idempotency_key, surface_path)`.\n\nTwo things every helper call needs:\n\n- **A relayfile mount for that provider**, locally — `flows check` refuses `helper_slack.credential_missing` (or the equivalent for another provider) without one. Cloud provides a mount for every connected provider automatically.\n- **A declared intent** on the flow header: `tools: { slack: true }` in TypeScript, or the equivalent in YAML. Forgetting this is a separate, earlier failure than the mount check.\n\nFor local development without standing up a real provider mount, prefix the run with the provider's mock env var — `RELAYFLOWS_SLACK_MOCK=1 flows run ... --local-agent` records the effect (a real file under the daemon's data dir) instead of sending it. This does not exercise live delivery, and should be called out as such wherever you cite it as verification.\n\n**`tools` means two different things depending on where you write it — do not confuse them:**\n\n- `FlowHeader.tools` (TypeScript) / `FlowSpec` top-level `tools` you're declaring intent on: `Partial<Record<keyof Helpers, boolean>> & { relayfile?: string[]; mcp?: string[] }` — e.g. `{ slack: true }`. This is \"which helpers this flow uses.\"\n- `FlowSpec.tools` in the compiled YAML/JSON spec is instead `{ fs?: string | string[] }` — path-scoped **filesystem** grants, mirroring `workspace` for shell/deterministic steps. Not the same field, despite the identical name.\n- `flows.json` (the project config file) has **no** `tools` field at all — see **`flows.json`**, below. Putting a `tools` key there is refused as `config_invalid`; this is an easy, first-try mistake (made once, personally, writing this refresh).\n\n## `cli` / `model`: what a step actually runs on\n\nBoth YAML and TypeScript agent/llm steps can set `cli` and `model` directly. Resolution order for `cli`, identical regardless of authoring language because both compile to the same `StepSpec`:\n\n1. **step** — `step.cli` (or TS's `options.cli`)\n2. **named** — the flow's `agents[step.agent]` entry, if the step selects one via `agent: <name>` (YAML/JSON only — TypeScript composes reusable flows via `use:` instead, not a per-step named-agent selector; see **Named agents and flow composition**)\n3. **flow** — `FlowSpec.cli` (YAML) — there is no equivalent flow-level `cli` field on the TypeScript `FlowHeader`\n4. **project** — nearest `flows.json`'s `cli`, found by walking up from the flow file's directory\n\nNo resolution found at any level → `REFUSED [cli_unresolved]`, before anything is journaled, e.g.:\n\n```\n$ flows check hello.flow.yaml   # agent step, no cli anywhere\nREFUSED [cli_unresolved] Step \"greeter\" has no CLI at step, flow, or project level. No flows.json was found from \"...\" to the filesystem root.\n```\n\n`model` has **no** flow or project default — only step or named-agent. Omitting it just runs whatever model the resolved CLI defaults to.\n\n### `flows.json`\n\nNearest-wins project config, walking from the flow file's directory to the filesystem root. The shipped SDK type (`@relayflows/sdk`'s `FlowsJson`) is exactly:\n\n```ts\ninterface FlowsJson {\n  cli?: string;\n  executors?: string[];\n  models?: string[];\n  mcp?: Record<string, McpServerConfig>;\n  deploy?: { bucket: string };\n}\n```\n\n- `cli` — the project-wide CLI default (resolution rung 4 above).\n- `executors` — trigger executors this project has registered. A trigger whose `executor` isn't in this list is `no_executor`; a flow that declares `.on(...)` triggers but is invoked directly (not via a webhook) still needs its provider named here — e.g. `{ \"executors\": [\"github\"] }` for a flow with `.on(github.pull_request(...))` handlers, even when you never hit that code path.\n- `models` — **an allowlist, not a default.** Any model declared on any step or named agent anywhere in the flow must appear here, or `flows check`/`flows run` refuses `model_unknown` / `llm_cli_unresolved`. Setting `models` does not select a model for anything.\n- `mcp` — project-owned MCP server connections.\n- `deploy` — a file-bucket target for `flows deploy <flow>@sha256:<digest> --to <bucket-uri>`.\n\n**Verified for real:**\n\n```\n$ flows run hello.flow.ts --local-agent --input '{}'   # step declares model \"claude-opus-5\", flows.json has no models[]\nREFUSED [invalid_spec] llm_cli_unresolved: Step \"llm-1\" declares model \"claude-opus-5\" for CLI \"claude\",\nbut it is not listed in project model registry \"…/flows.json\"; add the exact model only after verifying\nthat project is allowed to use it.\n\n$ flows run pr-reviewer.flow.ts --local-agent --input '{...}'   # flow declares .on(github....) handlers, no executors[]\nREFUSED [no_executor] webhook trigger \"github\" is not registered in flows.json\n```\n\nAny other top-level key — `tools`, `budget`, `identity`, `agents` — is refused as `config_invalid`. Those are `FlowHeader`/`FlowSpec` fields on the *flow itself*, not on the project config.\n\n## Named agents and flow composition\n\n**YAML/JSON**: a named-agent map declares each `{ cli, model }` pair once; a step's `agent:` selector resolves to it at compile time, and `flows check` flags a named agent nobody selects, or one a step overrides without using.\n\n```yaml\nagents:\n  planner: { cli: claude, model: claude-opus-5 }\n  implementer: { cli: codex, model: gpt-5.6-codex }\nsteps:\n  - id: plan\n    type: agent\n    agent: planner\n    instruction: '…'\n```\n\n**TypeScript** has no equivalent `agents:` map key on `FlowHeader` — the closest idiom is a plain object spread reused across calls:\n\n```ts\nconst planner = { cli: 'claude', model: 'claude-opus-5' };\nawait f.agent('plan', { ...planner, task: '…' });\n```\n\nWhat TypeScript *does* have is `FlowHeader.use?: string[]`: relative `.flow.ts` paths to direct child flows the body may call with `f.dispatch`. This is composition of complete flows, not a named-agent map. It executes in `2.0.35` and newer; see **Human approval and direct child flows**.\n\n## Parallel agents\n\nRunning several agent (or any) steps concurrently is first-class, documented authoring — not a workaround:\n\n> \"…`Promise.resolve`, `Promise.all`, `Promise.allSettled`, `Promise.any` and `Promise.race` over authored steps\" are \"ordinary, supported authoring.\" — `docs/SURFACE.md`, the authored operation lifecycle\n\n```ts\nconst LENSES = ['security', 'correctness', 'performance'] as const;\n\nawait Promise.all(\n  LENSES.map((lens) =>\n    f.agent(`${lens}-reviewer`, {\n      task: `Review this diff for ${lens} issues ONLY. Write findings to review/${lens}.json.`,\n      cli: 'claude',\n    }).gate({ type: 'subprocess_gate', command: `test -s review/${lens}.json` }),\n  ),\n);\n\nconst consensus = await f.agent('consensus', {\n  task: 'Read review/*.json. Resolve disagreement between lenses. Write review/consensus.json.',\n}).gate({ type: 'subprocess_gate', command: 'test -s review/consensus.json' });\n```\n\nThis is the exact shape `examples/pr-review-pipeline` in `AgentWorkforce/flows` (and the cookbook's would-be equivalent) uses: fan out, each lane writes its own file, a reconciliation step reads them all. **Disclosure worth knowing before you rely on it**: the flows package replaces the global `Promise.all` intrinsic, process-wide, for the lifetime of any authored flow execution, so the kernel can prove every concurrent step was actually awaited (rather than inferring group membership from callback identity). It delegates to the real intrinsic and restores it when the last concurrent flow closes — but any other code sharing that process sees the replacement during that window.\n\n## Agent-relay transport: dispatch, not live chat\n\n`AgentOptions.transport?: 'direct' | 'relay'` (default `'direct'`, a local subprocess). Setting `transport: 'relay'` dispatches the step to Agent Relay's own task infrastructure instead — per the shipped type's own doc comment: *\"posts to agent-relay so the agent registers as a first-class workspace participant that DMs can steer.\"*\n\nWhat this actually is, per `docs/AGENT-RELAY-TRANSPORT.md`: the step calls `POST /v1/actions/task.run/invoke` against relaycast, then waits for a durable final receipt — spawn readiness and invocation acceptance do **not** complete the step, only a terminal receipt does. It needs a pre-provisioned `RELAY_AGENT_TOKEN` (a workspace API key cannot substitute) and the Relay provider running with `AGENT_RELAY_TASK_PROVIDER=1`. The dispatched worker submits its result via an injected `agent_result` tool.\n\nDon't describe this as \"agents talking to each other\" — there's no documented pattern in this skill's scope for two flow steps to hold a live back-and-forth over Relay channels while both are running. What's real: the step's agent becomes a genuine Agent Relay workspace participant while it runs (so a human, or another agent with the right access, can DM it and potentially steer it — per the type's own wording), and the flow still only sees a request-and-durable-receipt shape, not an open channel. Multi-agent *coordination* inside a flow today means sequential handoff (one step's return value feeds the next) or parallel fan-out (**Parallel agents**, above) — not live messaging.\n\n## Human approval and direct child flows\n\n`f.human` parks a root run on a durable approval. `f.dispatch` executes a statically declared direct child in the same durable tree on `2.0.35` and newer. Both must be awaited.\n\n`f.human` parks the run durably on a kernel `wait.human`, keyed `human-<n>` in the order the body asked. A person answers, and `flows resume` continues the body from that line:\n\n```ts\nconst ok = await f.human(`Ship this?\\n${plan.summary}`, { to: 'khaliq' });\nif (!ok) return f.done('declined');   // a person's \"no\" is declined, never canceled\n```\n\n```\n$ flows answer <run-id> human-1 yes --by khaliq --note 'reviewed the diff'\n$ flows resume <run-id>\n```\n\n`to` names who is asked and is recorded with the question — **it is not a delivery address**; nothing notifies that person for you. The kernel closes a wait once, so the first answer wins, and it records `attribution: \"client_asserted\"` because the daemon socket, not the kernel, authenticated whoever `--by` names. The answer step takes a `.gate(config)` like any other step. One caveat: `f.human` needs a durable root run to park in — under a runner that has none it refuses with `unsupported_verb`, so run it with `flows run`.\n\nFor a composed local run, declare each direct child in the parent's static `use` header, then dispatch by the child's declared `flow(...)` name—not by its file path:\n\n```ts\n// release.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('release', { use: ['./implement.flow.ts'] }, async (f) => {\n  await f.run(\"printf '%s' prepare\");\n  const child = await f.dispatch('implement', { issue: 123 });\n  await f.run(\"printf '%s' publish\");\n  f.done(child.completionReason);\n});\n```\n\n```ts\n// implement.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('implement', async (f, input: { issue: number }) => {\n  await f.run(`printf '%s' ${input.issue}`);\n  f.done('success');\n});\n```\n\n`use` resolves relative `.flow.ts` files before a body runs. Missing or repeated files, duplicate direct-child names, cycles, and undeclared or transitive-only dispatch targets are refused. The child's steps receive qualified IDs such as `dispatch-2--run-1`; the dispatch receipt joins child leaves back to the parent's next step. Parent and child share one root budget and worker-capacity pool, and resume reuses journaled identities rather than repeating completed effects. A successful dispatch returns `{ name, completionReason: 'success', completionDetail? }`; any other child verdict fails the dispatch.\n\nAuthority narrows: a child cannot declare a second budget, require a helper/MCP capability its parent did not grant, or call `f.human`. Static cycles are refused and runtime child depth is capped at three. This is direct authored composition, not arbitrary public-flow invocation.\n\nTo put the **whole local tree** on one Cloud dashboard page, run `flows run --cloud-mirror release.flow.ts --input '{}'` (or affirmatively set `FLOWS_CLOUD_MIRROR=1`). The root, qualified child steps, dispatch receipts, dependency edges, transcripts, source, and output are projected into one connected graph; the local journal remains authoritative. Mirroring uploads that data and is opt-in. A mirror failure cannot fail the local run. The default observer link is separate and does not add the run to Cloud history.\n\nDo not confuse this with **hosted execution**. `flows run --cloud [--sync-code] release.flow.ts --input '{}'` still rejects `use` dependencies with `unsupported_source`: Cloud accepts one self-contained `.flow.ts` source. Use `--cloud-mirror` for the connected child-flow dashboard today; do not promise that Cloud can itself execute a multi-file `use` tree.\n\n**The same \"types accept it, the executor doesn't\" trap applies to `workspace` on an agent step under `--local-agent`.** Neither an annotated (`'acme/api: readonly'`) nor a bare (`'acme/api'`) value works — both fail identically:\n\n```\nREFUSED [invalid_spec] unsupported_workspace_permission: The local agent worker accepts\nstream-only steps. Remove workspace or attach a worker that holds its revision pins.\n```\n\nIt isn't the `: readonly`/`: readwrite` annotation syntax that's rejected — it's that the local-agent worker doesn't hold workspace revision pins at all. Omit `workspace` entirely for a step you intend to run with `--local-agent`; it's a real, working field only against a worker that supports it (Cloud's). Against a worker that does hold pins, the suffix is separately refused, and the remedy the SDK's own message names is `f.agent`'s `permissions` option — which records the scope and does not enforce it.\n\n## Running it: `flows check` / `run` / `deploy` / `schedule`\n\n```\nflows check [--json] [--watch] <flow.ts|flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>\nflows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <run-id>\nflows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]\nflows deployments [--json]\nflows undeploy [--json] <deployment-id>\nflows schedule <flow.ts> --cron \"<expr>\" --tz <tz> --input <inline-json-or-file>\n```\n\n`check` is a pure compile-and-preflight — no daemon, no socket, no data dir. It's the fast, safe way to validate a flow before ever running it, and it does accept `.flow.ts` despite older `--help` text implying only YAML/JSON.\n\n**`--local-agent` is not optional decoration.** Without it, `agent`/`llm` steps have no worker to dispatch to and the run parks indefinitely rather than executing. Every local run in this skill's examples, and every real run in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook), passes it.\n\nA `.flow.ts` run via `flows run` requires `--input <inline-json-or-file>` even when the flow body ignores its input argument.\n\n**`--data-dir` gotcha, learned the hard way.** If a flow does its own git hygiene on the directory you invoke it from — `pr-reviewer`'s and similar examples' `git clean -fdq -e .workforce` when there's nothing to push — that cleanup deletes *anything else untracked in that directory*, including the daemon's own default `.relayflowd/` state if you didn't move it. The symptom is a bizarre `SQLite journal failed: unable to open database file` on the *next* run in the same checkout, because the previous run's own cleanup step deleted the very journal directory the daemon needed. Fix: put the daemon's data outside the checkout:\n\n```bash\nflows run pr-reviewer.flow.ts --local-agent --data-dir /somewhere/outside/the/repo --input '{...}'\n```\n\n**Before `flows deploy` will do anything, two things have to already be true — a correct command still fails without them:**\n\n1. **You (or whoever's driving this) are logged in.** `agent-relay cloud login` once; check with `agent-relay cloud whoami`. There's no separate `flows`-specific login — it shares the `agent-relay` Cloud session.\n2. **The workspace has a GitHub App installation covering `--repo`, and the `--on` provider is actually a connected integration** — not just declared in the command. `flows deploy` looks up the workspace's GitHub installation before it will activate a listener; with none, it refuses `flow_repository_not_connected` rather than deploying a broken one (`prepare-flow-deploy.ts` in `AgentWorkforce/cloud`). Check what's connected with `agent-relay cloud integration connections --workspace <id>` — a provider showing `degraded` instead of `ready` is not deploy-safe, even though the CLI won't tell you that until you try. This is a separate concern from your own local git push access (a personal git/`gh` credential thing, needed only for testing a flow's own `git push`/`gh pr create` steps locally) — don't conflate the two when debugging a refusal.\n\n**`flows deploy`** creates a persistent listener: each matching ticket (`--on github:labels=agent`, `linear:team=ENG`, `jira:project=OPS`, `shortcut:workspace=…`, `slack:channel=#eng`) launches one Cloud run. `flows deployments` lists what's listening; `flows undeploy <id>` stops it — verified for real this session (deployed `software-factory` against a real repo with `--on linear:team=…`, got back `{\"status\":\"listening\", ...}`, then cleanly undeployed).\n\n**`flows schedule`** puts a flow on a cron instead of a ticket trigger — newer (shipped after the `2.0.16` release line) and not yet reflected everywhere in older examples that instead show `flows run --cloud` for the same use case.\n\n**Now fixed, was broken through `2.0.16`** ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), closed): the one-shot `flows run --cloud [--sync-code] <flow.ts> --input <json>` form used to misroute authored TypeScript flows into the declarative-spec loader (`invalid_input: Cannot read or compile the declarative flow`) or refuse with a bare `http_error: HTTP 400`. Root cause: Cloud pinned an older `@relayflows/surface` than the CLI authored against, and refused the version mismatch with those opaque errors instead of naming it. Fixed in `2.0.17` (CLI side) — verified for real: `flows run --cloud --wait <flow.ts> --input '{}'` now submits successfully and returns a real run ID instead of refusing immediately. If you still hit a bare `HTTP 400`/`invalid_input` on this path, you're likely on a CLI older than `2.0.17` — update first before assuming something else is wrong. (Cloud-side reporting of the exact version mismatch, when one still exists, was tracked as a separate follow-up PR at the time of writing — the CLI's own refusal is fixed either way.)\n\n### Watching a local run: observer link vs `--cloud-mirror`\n\nNew in **`2.0.32`**. A local run has two ways to be watched, and they are not the same thing:\n\n- **The observer link is the default.** Every `flows run` mints a read-only `ot_live_` link scoped to that run's own `wf-<runId>` channel and prints `Observer: <url>`. It is free, needs only a workspace key, and carries a step projection. `--no-observer-link` suppresses it.\n- **`--cloud-mirror` additionally puts the run on the Cloud dashboard** — the richer hosted view: the flow source, **every agent step's transcript**, the run graph, the run's own log, and the run sitting in the same history as your hosted ones. `FLOWS_CLOUD_MIRROR=1` turns it on for a whole shell.\n\n```bash\nflows run review.flow.ts --local-agent --input '{}'                  # observer link only\nflows run --cloud-mirror review.flow.ts --local-agent --input '{}'   # ...and the dashboard\n```\n\nThe run prints both, and the dashboard line names Cloud's run id as well as the page:\n\n```\nObserver:  https://agentrelay.com/observer?key=ot_live_...\nDashboard: https://.../dashboard/workflow/<cloud-run-id>/runner  ·  flows status --cloud --watch <cloud-run-id>\n```\n\n**That second id matters and is easy to get wrong.** The report's own `runId` is the *journal's* ULID (`01M3B9...`), while the two hosted verbs that take an id — `flows status --cloud <run-id>` and `flows logs <run-id>` — want Cloud's UUID. Do not pass a journal id to either. Under `--json` both ride in the report as `cloudRunId` and `dashboardUrl`, beside `observerUrl`.\n\n`flows runs` is the odd one out and the way *out* of this problem: it takes no id at all (`flows runs [--limit <n>] [--json]`) and lists the runs the credential can see, newest first, with each one's Cloud UUID — so it is how you find the id the other two want when you no longer have the terminal that printed it.\n\n**Why it is opt-in, not on by default.** Because it is the richer view, it is also the one that *stores* all of that: source, step metadata, agent transcripts, and the CLI's own stderr. Transcripts are whatever the agent printed, including file contents and command output. Everything goes through the same redactor `flows status` uses — but redaction is pattern matching, and pattern matching has a false-negative rate. So the trigger is an explicit request and never the mere presence of a Cloud login. Only an affirmative counts for the env var (`1`/`true`/`on`/`yes`); `0`, empty, and anything nobody meant as a switch all leave the run local.\n\n**What it buys you, concretely:** the three read verbs start answering for *local* runs, which until `2.0.32` only worked for runs Cloud had launched.\n\n```\n$ flows status --cloud <cloud-run-id>\nRUN 27ab5702-...  local-mirror-agent-confirmation  completed  spend 13,088 in / 61 out / $0.01836\n  ✓ ask-claude  agent  1 attempt  3.3s  claude-haiku-4-5-20251001 · 1 turn · $0.01836\n  ✓ ask-codex   agent  1 attempt  7.9s\n$ flows logs <cloud-run-id> --step ask-claude    # that step's transcript, out of Cloud storage\n```\n\nThree behaviours worth knowing before you rely on it:\n\n- **It cannot fail a run.** Every push collapses to a boolean; each poll and the whole finish are bounded. A Cloud outage costs the run its dashboard page and nothing else. If the mirror is refused you get one line naming which switch asked for it, and the run's exit code is untouched.\n- **The dashboard says the run was local.** The row is `dispatchType: \"local\"`, and the run page shows **Ran on: Your machine** instead of a sandbox tile. Cancel is refused for it — Cloud mirrors a local run, it does not control it, so stop it where it is running.\n- **A `--cloud-mirror` resume is a second dashboard row, linked to the first.** Cloud refuses to move a terminal run back to `running` (its own hosted resume mints a fresh id too), so the resumed attempt carries `resumedFromRunId` and the run page links the two — the parked \"Needs review\" row shows what continued it. The mapping lives in `<data-dir>/cloud-runs/`: the Cloud run id and the deployment, no credential, mode 0600, ageing out at 30 days.\n\n**Requires a Cloud login** (`agent-relay cloud login`, or `FLOWS_CLOUD_TOKEN`) — the same credential every other hosted verb uses. Without one, `--cloud-mirror` prints one line saying the run stays local and the run proceeds normally. A local run that joins no workspace is not a defect (RFC-0001 settled decision 7: the journal is the record, the workspace is one view onto it).\n\n### Exit codes and refusal shapes\n\nEvery refusal before a journal write is exit **2**, printed as `REFUSED [<kind>] <message>`. The `<kind>` differs by *how* the flow was checked, not just *what* was wrong:\n\n- `flows check` on a YAML/JSON spec, or the declarative-compiler path in general → the preflight's own kind directly: `cli_unresolved`, `model_unknown`, `cli_missing`, `cli_unauthenticated`, `no_executor`, `config_invalid`, etc.\n- `flows run` on a **TypeScript** `.flow.ts` whose authored `f.agent`/`f.llm` call can't resolve a CLI or model at runtime → wrapped and printed as `REFUSED [invalid_spec] <message>` with the specific reason (`llm_cli_unresolved`, etc.) inside the message text, not as the printed `[kind]` itself.\n\nBoth are real, both are exit 2 — the same underlying problem can print a different `[kind]` depending on whether you hit it via `flows check` on YAML or `flows run` on TypeScript.\n\n## Common mistakes\n\n- **Forgetting `version` in a YAML/JSON `FlowSpec`.** Required, not optional.\n- **Attaching two `.gate()` calls to one step.** `unsupported_gate`: a step takes one. Also note a predicate gate is invisible to `flows check` — prefer a config object when preflight should be able to prove it.\n- **Putting `tools`, `budget`, or any other `FlowHeader` field into `flows.json`.** `flows.json` only accepts `cli`, `executors`, `models`, `mcp`, `deploy` — anything else is `config_invalid`.\n- **Assuming `flows.json`'s `models` sets a default model.** It only validates models already declared elsewhere; it never selects one.\n- **Declaring `.on(...)` trigger handlers without registering the provider in `flows.json`'s `executors`.** Even a flow you only ever run directly (never via a real webhook) needs this, or it's refused `no_executor` before your input is even read.\n- **Calling `f.done('canceled')` for a human's \"no.\"** That's `f.done('declined')` — `canceled` is the kernel's verdict, not an authored body's.\n- **Running an agent/llm-bearing flow without `--local-agent`.** The run parks with nothing attached to do the work.\n- **Letting a git-hygiene flow's cleanup step delete your daemon's own data dir.** Pass `--data-dir` outside the checkout for any flow that runs `git clean`/`git checkout --force` on its own working tree.\n- **Not awaiting a step, or manually `.then()`-chaining one.** Refused (`unawaited_step`) rather than silently ignored.\n- **Running a `.flow.ts` without `--input`.** Required even for flows that don't use their input argument.\n- **Assuming `flows run --cloud` for a one-shot TypeScript flow run is still broken.** It was through `2.0.16` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), now closed) — fixed in `2.0.17`. If you're on an older CLI, update rather than reach for a workaround; `flows deploy` remains the right choice for a persistent listener regardless.\n\n## What this skill does NOT cover\n\n- **Triggers/webhooks** (`.on(github.pull_request(...), ...)`), **memory retrieval**, and the full **helper** catalog's per-provider quirks (`f.mcp`, provider-specific settings) — each is its own surface; see the [Relayflows product docs](https://agentrelay.com/docs/relayflows) and the [flows-cookbook](https://github.com/AgentWorkforce/flows-cookbook) for real, run-verified examples of each.\n- **Named-agent map equivalent in TypeScript beyond `use:`** — `use` composes complete child flows, not named agent configurations.\n- **YAML-only agent step fields with no TypeScript equivalent**: `recoveryMode`, `surfaces`, `output`, the `agent:` named-agent selector, and enforced `workspace` (TypeScript's `workspace` string is accepted by the type but rejected by the local-agent worker — see **Human approval and direct child flows**). `permissions` is **not** on this list — it is a TypeScript option too (see **The real `Ctx` contract**).\n- **Hosted multi-file child-flow execution** — `flows run --cloud` refuses `use` dependencies even with `--sync-code`; `--cloud-mirror` is the supported route for a local child-flow tree on the Cloud dashboard.\n- The **older `@relayflows/core` `WorkflowBuilder`** engine — see `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` in this repo.\n\n## Quick reference\n\n| Verb / field | Language | Notes |\n|---|---|---|\n| `f.run(command, {timeout?})` / `type: deterministic` | both | shell command, implicit `exit_code` gate |\n| `f.llm(...)` / `type: llm` | both | bare model call, no workspace |\n| `f.agent(name, opts)` / `type: agent` | both | harnessed coding agent, returns `{summary, artifacts}` |\n| `f.human(question, {to})` | TS only | parks the run on a durable `wait.human`; `flows answer <run> human-<n> yes\\|no` then `flows resume` |\n| `use: ['./child.flow.ts']` / `f.dispatch(name, input)` | TS only | `2.0.35`+ direct child in one durable tree; dispatch by declared name |\n| `f.done(reason)` | TS / kernel | one of `success \\| step_failed \\| needs_human \\| declined` from an authored body; `canceled \\| budget_exceeded` are kernel-only |\n| `.gate(config)` / `.gate(predicate, because)` | TS | one per step; both run since flows#449, but only a config object is provable by `flows check` |\n| `options.transport: 'relay'` | TS/YAML `agent` step | dispatch to Agent Relay's task infra; request+receipt, not live chat |\n| `Promise.all([...steps])` | TS | first-class supported concurrent fan-out |\n| `flows.json`: `cli, executors, models, mcp, deploy` | project config | exact accepted key set — nothing else |\n| `flows check <file>` | CLI | pure validate + preflight, no daemon |\n| `flows run <file> --local-agent [--input ...]` | CLI | actually executes; `.flow.ts` needs `--input`, agent/llm steps need `--local-agent` |\n| `flows deploy <flow.ts> --repo ... --on ...` | CLI | persistent trigger-based listener; needs `agent-relay cloud login` plus a connected GitHub App + `--on` provider first, or `flow_repository_not_connected` |\n| `flows run --cloud <flow.ts> --input ...` | CLI | fixed in `2.0.17` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461)); update if you still see `http_error`/`invalid_input` |\n| `flows run --cloud-mirror <file> --local-agent` | CLI | `2.0.32`+; local run also on the Cloud dashboard, transcripts included. Opt-in; `FLOWS_CLOUD_MIRROR=1` for a shell. `--json` gains `cloudRunId`/`dashboardUrl` |\n| `flows run --cloud` with `use` | CLI | unsupported: one self-contained `.flow.ts` source only, even with `--sync-code` |\n| `flows status --cloud <run-id>` / `flows logs <run-id>` | CLI | take Cloud's **UUID**, not the journal ULID. Answer for mirrored local runs since `2.0.32` |\n| `flows runs [--limit <n>]` | CLI | takes **no id** — lists runs newest-first, which is how you find the UUID the two above want |\n| `flows schedule <flow.ts> --cron ...` | CLI | cron-based cloud run |\n\n## Verified against\n\n**The `Ctx` and child-flow contracts were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations.** Earlier gate, helper, and agent-option findings below were established on `2.0.22`; the original `--cloud-mirror` verification was on `2.0.32`.\n\nA three-level root → child → grandchild fixture was run locally from published `2.0.35` packages, then mirrored to the production Cloud dashboard. The [mirrored run](https://agentrelay.com/cloud/dashboard/workflow/0d502725-e4c2-4cfd-aed2-ed0dd49bd6ac/runner) completed with `completionReason: success`; its Cloud graph contained seven succeeded work/dispatch nodes, seven runtime dependency edges, both child labels, and no warnings. A separate `flows run --cloud --sync-code` attempt refused the same tree before admission with `unsupported_source`, which is why this skill does not promise hosted child-flow execution. This checks the graph API used by the dashboard, not an authenticated browser screenshot.\n\n**The `--cloud-mirror` section was verified on `2.0.32`, against production, with the published artifact.** `relayflows@2.0.32` was installed from npm into a scratch project — not run from a source tree — and two real local runs were mirrored to `agentrelay.com`:\n\n- a two-step deterministic flow, read back with `flows status --cloud`, `flows logs` (the `runner.log` round-trip) and `flows runs` (the run appearing in history beside hosted ones);\n- a two-agent flow, one `cli: claude` step and one `cli: codex` step, spending a real `$0.01836` — whose **per-step transcripts were fetched back out of Cloud storage** and rendered in each provider's own frame vocabulary. That is the claim worth having evidence for: an echo-only flow exercises none of the transcript path.\n\nTwo things that verification established and that are easy to assume otherwise. **Flows drives exactly two agent CLIs**: `adapters/index.ts` registers `claude` and `codex`, and anything else resolves to `relayflows-wrapper-v1`, which requires the executable to answer `--relayflows-adapter-v1` with a flows-specific token. A real `devin` CLI on `PATH` rejects that flag outright (`error: unexpected argument`), so it cannot be used as a `cli:` for an agent step no matter what is installed — adding one is a new `adapters/<name>.ts` plus a registry entry. And the **observer projection has no retry**: `run-projection.ts` sets `failed = true` on the first error and every later publish is a no-op, so a transient `429 workspace_busy` — observed for real during this verification, while another run was launching in the same workspace — permanently loses the observer view for that run. The dashboard mirror survived the same window because it classifies `429` as transient and retries on its next poll. If an observer link opens an empty channel, that asymmetry is the first thing to check.\n\nThe earlier `2.0.22` refresh settled several contradictions against the published package: `AgentOptions.permissions` exists on the TypeScript call site (added in `2.0.17`, validated and journaled, not enforced — preflight warns `permissions_unenforced`); `run(command, options?)` takes a second `{timeout}` argument; `f.done` takes six `FLOW_COMPLETION_REASONS`; there is no `budget.maxWallclockMs`; predicate `.gate()` and `artifact_exists` ship; and `f.human` executes. Its then-true finding that `f.dispatch` was unsupported was superseded by `2.0.35`. Older real-run recipes are in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook); check their dates when comparing behavior.\n\nThe `flows.json` schema refusal, the `--data-dir` git-hygiene interaction, and the `flows run --cloud` bug were reproduced while building that cookbook past `v2.0.16` (2026-09-17). The `2.0.22` refresh also checked the `workspace: readonly` annotation and the `subprocess_gate` env var name against the real CLI. Child-flow claims above instead rest on the published `2.0.35` run and its production Cloud graph.\n"
 };
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 2eff8cc4..0bd6f807 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -111,7 +111,10 @@ describe('agent signup instructions', () => {
 
   it('reads the sharing mode from the desktop and asks before changing an existing one', async () => {
     const content = await guide('teams');
-    expect(content).toContain("jq -r '.data.sharing_mode'");
+    expect(content).toContain("jq -r '.data.sharing_mode // empty'");
+    // The defaults keep the reported mode unless the human chose another; nothing forces new.
+    expect(content).not.toContain('relay_sharing_mode=new');
+    expect(content).toContain('"${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}"');
     expect(content).toContain('Never change it silently.');
     expect(content).toContain('sharing_mode: .data.sharing_mode');
     expect(content).toContain('Report\n   waiting while the user decides about an existing sharing mode.');
@@ -119,7 +122,8 @@ describe('agent signup instructions', () => {
 
   it('keeps the agent-relay CLI optional and carries the latency and HTTP-client guidance', async () => {
     const content = await guide('teams');
-    expect(content).toContain('do not install or\nupgrade it just for these checks');
+    expect(content).toContain('do not install or upgrade it just for these checks');
+    expect(content).toContain("case \"$relay_cli\" in ''|/usr/bin/agent-relay) relay_cli= ;; esac");
     expect(content).not.toMatch(/npm install -g agent-relay/);
     expect(content).toContain('relay-desktop#333');
     expect(content).toContain('60-second timeout');

From 30d9e4c715104938b374ae537f22d68e77988c09 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 22:57:03 -0700
Subject: [PATCH 4/9] fix(signup): address review on the vendored guides

- Flows progress steps map to the Flows skill's sections 3-5 (connect,
  activate, verify), so completion follows the listener check.
- Local Teams guides rewrite Part 2's desktop commands for the prebuilt Dev
  app (download, app name, bundle id, socket pointer); Linux has no local
  artifact.
- sync-setup-skills --check fails on, and sync removes, vendored copies
  SOURCE.json no longer lists.
- Teams step copy qualifies the new-sessions default; the v2 test also
  rejects side-effect and dynamic imports of @relayflows/core.
- Re-pin to AgentWorkforce/skills@d2e5a3e.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/content/setup-skills/SOURCE.json          |  2 +-
 .../setting-up-agent-relay-desktop.md         | 15 +++++++
 .../setting-up-agent-relay-flows.md           |  7 +++-
 web/lib/agent-signup-progress.ts              |  2 +-
 web/lib/agent-signup.ts                       | 40 ++++++++++++++-----
 web/lib/generated/setup-skills.ts             |  6 +--
 web/lib/test/agent-signup.test.ts             |  8 +++-
 web/scripts/sync-setup-skills.mjs             |  9 ++++-
 8 files changed, 68 insertions(+), 21 deletions(-)

diff --git a/web/content/setup-skills/SOURCE.json b/web/content/setup-skills/SOURCE.json
index 42cffef2..157aa85b 100644
--- a/web/content/setup-skills/SOURCE.json
+++ b/web/content/setup-skills/SOURCE.json
@@ -1,6 +1,6 @@
 {
   "repository": "AgentWorkforce/skills",
-  "commit": "7a636649f914dbe9e6807ee491d556c2f3e7c070",
+  "commit": "d2e5a3ecfbfdd7b64c6775b3c452c99b06e62fd6",
   "skills": [
     "signing-in-to-agent-relay-cloud",
     "setting-up-agent-relay-desktop",
diff --git a/web/content/setup-skills/setting-up-agent-relay-desktop.md b/web/content/setup-skills/setting-up-agent-relay-desktop.md
index f6c066fb..ed2bf2b7 100644
--- a/web/content/setup-skills/setting-up-agent-relay-desktop.md
+++ b/web/content/setup-skills/setting-up-agent-relay-desktop.md
@@ -540,6 +540,21 @@ printf '%s\n' "$registration_status" | jq -e \
    .data.session.registered == true and .data.session.direct_delivery == true'
 ```
 
+**Codex on macOS.** The system `curl` hides a Codex session's identity from the
+socket there, so `/register` is refused `not_a_relay_session` (section 6 says
+the same for subscriptions). In a Codex session on macOS, find `relay_probe`
+with section 6's first block and send the registration through it instead of
+the `curl` line above, then read `/setup/status` as above:
+
+```sh
+register=$(printf '{}' | "$relay_probe" relay socket-request \
+  --socket "$relay_socket" --method POST --path /register)
+```
+
+If `/setup/sign-in` is refused the same way, send its payload through the probe
+the same way. Without a probe, stop and report it rather than registering
+another process.
+
 Direct delivery is checked first so a managed-policy refusal stops setup
 before auto-activation or upload settings are changed. Report that refusal
 clearly; never claim the three-default setup completed.
diff --git a/web/content/setup-skills/setting-up-agent-relay-flows.md b/web/content/setup-skills/setting-up-agent-relay-flows.md
index 952b685f..48b7ef47 100644
--- a/web/content/setup-skills/setting-up-agent-relay-flows.md
+++ b/web/content/setup-skills/setting-up-agent-relay-flows.md
@@ -19,7 +19,9 @@ Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
 
 A signed-in Cloud session: an access token and the `user.id` and
 `currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`
-first, and send `Authorization: Bearer <access_token>` on every request below.
+first. Send `Authorization: Bearer <access_token>` only to the Cloud API
+endpoints below. Never send it to the site's flow catalog or to a catalog
+`source.rawUrl`; fetch those without credentials.
 
 ## API map
 
@@ -128,7 +130,8 @@ verify that readiness separately before activating it.
 
 Do not connect a Claude or Codex subscription yet. The first three runs use
 Cloud's own model key, so no provider login is needed to activate. If the chosen
-flow declares more than one coding agent in inputs.agents, included Cloud runs
+flow declares more than one coding agent (the catalog's `inputs.defaults.agents`,
+which becomes `inputs.agents` in the deploy body), included Cloud runs
 can fund only one of them per run — connect your own subscription for at least
 one declared agent before activating a multi-agent flow. After the included
 runs, activation and launches will ask for your own subscription; only then use
diff --git a/web/lib/agent-signup-progress.ts b/web/lib/agent-signup-progress.ts
index c01d9f9a..e658b151 100644
--- a/web/lib/agent-signup-progress.ts
+++ b/web/lib/agent-signup-progress.ts
@@ -44,7 +44,7 @@ export const signupSteps = {
     { title: 'Sign in', detail: 'Your agent opens Google. You approve access.' },
     { title: 'Install the app', detail: 'Download, verify, and install the Agent Relay desktop app.' },
     { title: 'Connect your workspace', detail: 'Link the app to your account and workspace.' },
-    { title: 'Choose what to share', detail: 'New sessions are shared; your agent asks before changing an existing choice.' },
+    { title: 'Choose what to share', detail: 'New sessions are shared by default; if you already chose a sharing mode, your agent asks before changing it.' },
     { title: 'Check everything works', detail: 'Verify the app, then one live session handoff with a teammate.' },
   ],
   flows: [
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 585c6801..c91076d5 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -112,10 +112,11 @@ ${product === 'teams' ? `Progress steps for Teams:
    live round trip; only then PATCH step: 5, state: complete. A self-verified
    read path without a teammate is not completion.` : `Progress steps for Flows:
 1. Sign in: before Part 1.
-2. Choose the flow/repository: before Part 2's section 1.
-3. Connect tools: before Part 2's section 2.
-4. Activate the flow: before Part 2's section 3.
-5. Verify the listening state: before Part 2's section 4. After its checks
+2. Choose the flow/repository: before Part 2's section 1 (through section 2,
+   and Part 3 for a custom flow).
+3. Connect tools: before Part 2's section 3.
+4. Activate the flow: before Part 2's section 4.
+5. Verify the listening state: before Part 2's section 5. After its checks
    succeed, PATCH step: 5, state: complete.`}
 
 On HTTP 409, GET current progress and reconcile; never overwrite newer progress
@@ -147,23 +148,40 @@ const signupParts: Record<AgentSignupProduct, readonly { label: string; skill: s
 
 const PRODUCTION_SITE = 'https://agentrelay.com';
 
-/** The skills name production; a local stack substitutes its own exact origins. */
+const DESKTOP_RELEASES = 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download';
+
+/**
+ * The skills name production. A local stack substitutes its own exact origins
+ * and, so the desktop commands run as written, the prebuilt Agent Relay Dev
+ * app's download, app name, bundle id and socket paths.
+ */
 function forEnvironment(skill: string | undefined, site: string, cloud: string): string {
   if (skill === undefined) throw new Error('A signup part names a skill that is not vendored');
   if (site === PRODUCTION_SITE && cloud === `${PRODUCTION_SITE}/cloud`) return skill;
-  return skill.replaceAll(`${PRODUCTION_SITE}/cloud`, cloud).replaceAll(PRODUCTION_SITE, site);
+  return skill
+    .replaceAll(DESKTOP_RELEASES, `${site}/cloud/desktop-downloads`)
+    .replaceAll('AgentRelay-macOS-', 'AgentRelay-Dev-macOS-')
+    .replaceAll('Agent Relay.app', 'Agent Relay Dev.app')
+    .replace(/com\.agentrelay\.desktop(?!\.dev)/g, 'com.agentrelay.desktop.dev')
+    .replace(/\.agentworkforce\/desktop\/relay-socket(?!\.dev)/g, '.agentworkforce/desktop/relay-socket.dev')
+    .replaceAll(`${PRODUCTION_SITE}/cloud`, cloud)
+    .replaceAll(PRODUCTION_SITE, site);
 }
 
 function localDevelopmentNote(product: AgentSignupProduct, site: string): string {
   return `
 
 This is a local development stack. The skills' production URLs have been
-replaced with the origins above.${product === 'teams' ? ` For the desktop, use only the prebuilt
-Agent Relay Dev app served by the local stack, in place of the release download:
+replaced with the origins above.${product === 'teams' ? ` Part 2's macOS commands have also been
+rewritten for the prebuilt Agent Relay Dev app served by the local stack, so run
+them as written: they download
 ${site}/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg and the same URL
-plus .sha256 (arm64 or x64). Its bundle id is com.agentrelay.desktop.dev and its
-socket pointer is ~/.agentworkforce/desktop/relay-socket.dev. If the DMG or its
-checksum is unavailable, stop and report the missing prebuilt artifact.
+plus .sha256 (arm64 or x64), install Agent Relay Dev.app, require bundle id
+com.agentrelay.desktop.dev, and use the socket pointer
+~/.agentworkforce/desktop/relay-socket.dev. Use only those Dev paths for every
+socket lookup in Parts 2 and 3. The local stack serves only the macOS Dev app:
+on Linux, stop and report that no local desktop artifact exists. If the DMG or
+its checksum is unavailable, stop and report the missing prebuilt artifact.
 Do not build it, run the development launcher to produce it, or switch to a
 production download.` : ''}`;
 }
diff --git a/web/lib/generated/setup-skills.ts b/web/lib/generated/setup-skills.ts
index 0cc5343e..84627515 100644
--- a/web/lib/generated/setup-skills.ts
+++ b/web/lib/generated/setup-skills.ts
@@ -1,11 +1,11 @@
 // Generated by web/scripts/sync-setup-skills.mjs from the pinned
 // AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.
-export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"7a636649f914dbe9e6807ee491d556c2f3e7c070"} as const;
+export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"d2e5a3ecfbfdd7b64c6775b3c452c99b06e62fd6"} as const;
 
 export const SETUP_SKILLS: Readonly<Record<string, string>> = {
   "signing-in-to-agent-relay-cloud": "# Sign In to Agent Relay Cloud\n\nUse the existing OAuth device flow. No API key, invitation, dashboard wizard,\nor pre-existing Agent Relay account is required. Only the human approves the\nsign-in; never approve access on their behalf, ask for their password, or\noperate the approval page yourself.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix. When a guide names a different Cloud base (for\nexample a local development stack), use that exact base throughout and never\nfall back to production.\n\n## HTTP client\n\nUse `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their\ndefault User-Agent: the device-token endpoint answers them with HTTP 403 and no\nJSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth\nresponse while debugging; on success it contains tokens. Send JSON request\nbodies with `Content-Type: application/json`, set a 30-second request timeout,\nand check every response status before proceeding.\n\n## 1. Start the device grant\n\n`POST /api/v1/auth/device/start` with:\n\n```json\n{\"client_name\":\"My agent setup\"}\n```\n\nAn agent-driven signup guide also passes its product as `signup_source`\n(`\"teams\"` or `\"flows\"`); keep the value the guide names. Omit it otherwise.\n\nExpect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,\n`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep\n`device_code` private. Open `verification_uri_complete` in the person's\nbrowser with the OS URL opener (for example macOS `open`, with the URL passed as\na separate argument, never interpolated into shell code), or give them the link\nif no opener is available. Show the `user_code` so they can compare it. The page\nlets them sign in with Google, review the requesting device, and Approve or\nDeny. A signup marker in the returned URL creates the right account type;\npreserve it through sign-in. Do not call `/auth/device/approve` yourself.\n\nFor a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`\non the same Cloud base first (in production,\n`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of\n`verification_uri_complete`. This opens Google immediately and returns to the\nsame device approval with its code and signup marker intact. Never open the\nproduction URL for a non-production base: that would sign the human in to\nproduction instead.\n\n## 2. Poll for tokens\n\nWhile the browser is open, wait `interval` seconds between POSTs to\n`/api/v1/auth/device/token` with this JSON (substitute the private\n`device_code`):\n\n```json\n{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"<device_code>\"}\n```\n\n- `authorization_pending`: keep waiting; respect a returned interval.\n- `slow_down`: increase the interval by at least 5 seconds.\n- HTTP 429: respect `Retry-After` and increase the interval.\n- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.\n- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start\n  a new grant only if the person still wants to continue. Never poll past\n  expiry.\n\nHTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,\n`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in\nmemory or a private file (directory 0700, file 0600) outside repositories.\nNever echo tokens, put them in chat or URLs, or dump full authentication\nresponses. Use `Authorization: Bearer <access_token>` for subsequent Cloud\nrequests. Reject an `api_url` pointing at another origin; keep using the Cloud\nbase above.\n\n## 3. Refresh before expiry\n\nBefore expiry, `POST /api/v1/auth/token/refresh` with\n`{\"refreshToken\":\"<refresh_token>\"}`. The response uses camelCase:\n`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,\n`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the\nrefresh token rotates and must not be shared between machines. An\ninvalid/expired refresh requires a new device login, not an endless retry.\n\n## 4. Read the account and workspace\n\n`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,\n`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups\ncreate a workspace automatically. Reuse it; do not create duplicate\naccounts/workspaces. If `currentWorkspace` is missing, or an existing account\nis in the wrong workspace, resolve that with the person before connecting or\nactivating anything. Never silently replace an existing connection to another\naccount.\n\n## 5. Hand the session to the official CLI\n\nWhen running a child process, pass these through its environment from your\nprivate session object (never interpolate their values into logged commands):\n\n```text\nCLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>\nCLOUD_API_ACCESS_TOKEN=<access_token>\nCLOUD_API_REFRESH_TOKEN=<refresh_token>\nCLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>\nCLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>\n```\n\nThe official CLI consumes this session. Refresh the parent session before\nstarting a long command; do not concurrently refresh it from parent and child\nprocesses. Do not overwrite an existing CLI auth file or copy a session to\nanother machine. Delete temporary authentication files after the work is\ncomplete.\n",
-  "setting-up-agent-relay-desktop": "# Set Up Agent Relay Desktop\n\nComplete the setup through the private session socket. Do not ask the human to\nclick through the desktop app. The only normal human step is approving one\ndevice-login link when no reusable `agent-relay` CLI login exists.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the current release is installed and running;\n- sign-in is complete;\n- sharing mode is `new` (new sessions upload automatically), unless an existing\n  install already uses another mode and the human chose to keep it (section 4);\n- auto-activate is on, with every existing live session and every future session on the relay;\n- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);\n- this Codex or Claude session is registered and accepts direct delivery;\n- the requested webhook and integration subscriptions work;\n- the human receives the session's `agent@machine` address and verification evidence.\n\nNever put a Cloud token, workspace key, agent token, or webhook secret in a\nRelay message. The webhook secret is returned once to this local calling\nsession; keep it in a mode-0600 temporary file and delete the file after the\ntest.\n\n## Install this skill for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage, then place that unchanged `SKILL.md` where Codex actually loads global\nskills:\n\n```sh\nnpx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y\ncodex_skill=\"$HOME/.codex/skills/setting-up-agent-relay-desktop\"\nmkdir -p \"$codex_skill\"\ninstall -m 0644 \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\ncmp \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\n```\n\nDo not use prpm's `--as codex` conversion for this package. It currently writes\nunder `~/.agents/skills`, which Codex does not load as its global skill folder,\nand its conversion drops explanatory paragraphs from this Markdown workflow.\nConfirm both final paths explicitly before continuing.\n\n## 1. Detect the host and current session\n\nRun setup commands from this agent's own shell tool. Do not run them from an\nunrelated terminal: the app identifies the caller from kernel credentials and\nthe Codex/Claude process ancestry.\n\n```sh\nuname -s\nuname -m\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\nif test \"$(uname -s)\" = Linux; then\n  if command -v dpkg-query >/dev/null; then\n    printf 'linux_install=deb\\n'\n  else\n    printf 'linux_install=per-user-tarball\\n'\n  fi\nfi\ncommand -v systemctl >/dev/null && systemctl --user is-system-running || true\n```\n\nOn Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other\nsystemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball\npath; do not try to install the `.deb`. The app scans same-user process trees\nand TTYs; it does not require the service itself to share the tmux session.\n\n`systemctl --user is-system-running` may report `degraded` because an unrelated\nuser unit failed. That is not a Relay failure when\n`systemctl --user is-active agent-relay.service` reports `active` and the Relay\nsocket passes its status check.\n\nFind an existing socket without printing private files:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test -n \"${XDG_RUNTIME_DIR:-}\"; then\n  relay_socket=\"$XDG_RUNTIME_DIR/agent-relay/relay.sock\"\nfi\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"/run/user/$(id -u)/agent-relay/relay.sock\"\nfi\nc=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Darwin && test -S \"$c\"; then   # pointer file missing: use the app's own socket\n  relay_socket=$c\nfi\ntest -S \"${relay_socket:-/nonexistent}\" && printf 'socket=%s\\n' \"$relay_socket\"\n```\n\nIf the socket exists, inspect it before installing anything:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout\n(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's\n`relay socket-request` can give up sooner with \"Probe could not finish. Check\nyour connection and run setup again\"; on these paths that is the same latency,\nnot a setup problem. Retry the call once before reporting a blocker, and do not\nstart a second install or sign-in because of it.\n\nPreserve a working newer install. When the socket is absent, check for an\ninstalled-but-stopped copy before downloading: use `dpkg-query -W agent-relay`\nwhen `dpkg-query` exists and `systemctl --user status agent-relay.service` on\nLinux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry\nstatus first.\nUpdate an older install only when it lacks the setup contract or reports an\nolder version. A `404` from `/setup/status` means the installed build is too\nold for agent-driven setup and should be updated.\n\n## 2. Install or update with checksum verification\n\nUse a private temporary directory. Never skip the published SHA-256 check.\n\n### Ubuntu LTS, headless `.deb` (preferred)\n\nSelect the release architecture and install:\n\nThis path needs passwordless sudo or one human-approved sudo prompt for the\npackage install and `loginctl enable-linger`. Explain that prerequisite before\nstarting; never capture or relay a sudo password.\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb\" -o \"$relay_tmp/AgentRelay.deb\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb.sha256\" -o \"$relay_tmp/AgentRelay.deb.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#\" AgentRelay.deb.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nsudo apt-get install -y \"$relay_tmp/AgentRelay.deb\"\nsudo loginctl enable-linger \"$USER\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n```\n\nThe unit runs the bundled core headless: no display, X server, or GTK\nwindow is needed. This session's own GitHub subscriptions (section 6) go\nthrough the Desktop and need no CLI. The separate Agent Relay CLI is needed\nonly to subscribe a fleet-spawned or named agent; record whether it is present\nand at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app\ndiscovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:\n\n```sh\nrelay_cli=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay\" \\\n  \"$HOME/.npm-global/bin/agent-relay\" \\\n  \"$HOME/.agentworkforce/relay/bin/agent-relay\"\ndo\n  if test -x \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n    relay_cli=$candidate\n    break\n  fi\ndone\nif test -z \"$relay_cli\"; then\n  for relay_root in \\\n    \"$HOME/.local/share/mise/installs/node\" \\\n    \"$HOME/.nvm/versions/node\"\n  do\n    test -d \"$relay_root\" || continue\n    candidate=$(find -L \"$relay_root\" -mindepth 3 -maxdepth 3 \\\n      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)\n    if test -n \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n      relay_cli=$candidate\n      break\n    fi\n  done\nfi\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" integration subscribe --help >/dev/null\nelse\n  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\\n'\nfi\n```\n\nOn Linux without `dpkg`, use this per-user tarball installation under a\nversioned user directory. It is also the fallback on Ubuntu when `.deb`\ninstallation is unavailable and the human approves a per-user install. The\narchive contains a unit whose `/usr/bin` path is correct for packages, so\nrewrite only that `ExecStart` in the user copy:\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz\" -o \"$relay_tmp/AgentRelay.tar.gz\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256\" -o \"$relay_tmp/AgentRelay.tar.gz.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#\" AgentRelay.tar.gz.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmkdir \"$relay_tmp/extracted\"\ntar -xzf \"$relay_tmp/AgentRelay.tar.gz\" -C \"$relay_tmp/extracted\"\nrelay_tree=\"$relay_tmp/extracted/AgentRelay-linux-$relay_arch\"\ntest -x \"$relay_tree/usr/bin/agent-relay\"\nrelay_version=$(sed -n 's/^__version__ = \"\\([0-9A-Za-z._-]*\\)\"$/\\1/p' \\\n  \"$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py\")\ncase \"$relay_version\" in\n  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\\n' >&2; exit 1 ;;\nesac\nrelay_unit=\"$HOME/.config/systemd/user/agent-relay.service\"\nrelay_installed_version=\nif test -S \"${relay_socket:-/nonexistent}\"; then\n  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)\nfi\nif test -z \"$relay_installed_version\" && test -r \"$relay_unit\"; then\n  relay_installed_version=$(sed -n \\\n    's#^ExecStart=.*/\\.local/lib/agent-relay/\\([^/ ]*\\)/.*#\\1#p' \\\n    \"$relay_unit\")\nfi\ncase \"$relay_installed_version\" in\n  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;\nesac\nif test -n \"$relay_installed_version\" && \\\n   test \"$relay_installed_version\" != \"$relay_version\" && \\\n   test \"$(printf '%s\\n%s\\n' \"$relay_version\" \"$relay_installed_version\" | sort -V | tail -n 1)\" = \"$relay_installed_version\"; then\n  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\\n' \\\n    \"$relay_installed_version\" \"$relay_version\" >&2\n  exit 1\nfi\nrelay_prefix=\"$HOME/.local/lib/agent-relay/$relay_version\"\nmkdir -p \"$relay_prefix\"\ncp -a \"$relay_tree/usr\" \"$relay_prefix/\"\nmkdir -p \"$(dirname \"$relay_unit\")\"\nsed \"s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#\" \\\n  \"$relay_tree/usr/lib/systemd/user/agent-relay.service\" >\"$relay_unit.tmp\"\nchmod 0644 \"$relay_unit.tmp\"\nmv \"$relay_unit.tmp\" \"$relay_unit\"\ngrep -F \"ExecStart=$relay_prefix/usr/\" \"$relay_unit\" | grep -q -- ' --headless$'\nif ! loginctl show-user \"$USER\" -p Linger | grep -qx 'Linger=yes'; then\n  sudo loginctl enable-linger \"$USER\"\nfi\nsystemd-analyze --user verify \"$relay_unit\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n# List the app in the desktop's app launcher (no-op on a headless server).\n# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the\n# entry the first time it is opened.\nif test -x \"$relay_prefix/usr/bin/agent-relay-desktop\"; then\n  \"$relay_prefix/usr/bin/agent-relay-desktop\" --install-launcher || true\nfi\n```\n\nThe unit's `ExecStart` names the archive's own path under `/usr/`, either the\nlauncher or the bundled `agent-relay-probe`; the rewrite moves whichever it is\nunder `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its\nfull path, never the bare `agent-relay`, which is also the CLI's name.\n\nDo not improvise Alpine or RHEL distribution packages. On a compatible\nsystemd host without `dpkg`, use only the verified per-user tarball path above;\nnon-systemd hosts remain unsupported by this Linux workflow.\n\n### macOS DMG\n\n```sh\ncase \"$(uname -m)\" in\n  arm64) relay_arch=arm64 ;;\n  x86_64) relay_arch=x64 ;;\n  *) printf 'Unsupported Mac architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg\" -o \"$relay_tmp/AgentRelay.dmg\"\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg.sha256\" -o \"$relay_tmp/AgentRelay.dmg.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#\" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmount_point=$(hdiutil attach -nobrowse -readonly \"$relay_tmp/AgentRelay.dmg\" | awk '/\\/Volumes\\// {sub(/^.*\\/Volumes\\//,\"/Volumes/\"); print; exit}')\nincoming_id=$(defaults read \"$mount_point/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\nif test \"$incoming_id\" != com.agentrelay.desktop; then\n  hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\\n' \"$incoming_id\" >&2\n  exit 1\nfi\nif test -d \"/Applications/Agent Relay.app\"; then\n  existing_id=$(defaults read \"/Applications/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\n  if test \"$existing_id\" != com.agentrelay.desktop; then\n    hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\\n' \"$existing_id\" >&2\n    exit 1\n  fi\nfi\nosascript -e 'tell application \"Agent Relay\" to quit' 2>/dev/null || true\nditto \"$mount_point/Agent Relay.app\" \"/Applications/Agent Relay.app\"\nhdiutil detach \"$mount_point\"\nopen -a \"Agent Relay\"\n```\n\nIf `/Applications` needs administrator access, use `sudo ditto` only after the\nhuman has authorized installation. Do not remove or overwrite another app with\nan unexpected bundle identity.\n\nAfter either install, wait up to 30 seconds for the pointer:\n\n```sh\napp_sock=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nfor _ in $(seq 1 30); do\n  test -r \"$HOME/.agentworkforce/desktop/relay-socket\" && break\n  test \"$(uname -s)\" = Darwin && test -S \"$app_sock\" && break   # the app is already listening\n  sleep 1\ndone\nrelay_socket=$(sed -n '1p' \"$HOME/.agentworkforce/desktop/relay-socket\" 2>/dev/null)\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Darwin && test -S \"$app_sock\"; then\n  relay_socket=$app_sock\nfi\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock\"\nfi\ntest -S \"$relay_socket\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'\n```\n\n## 3. Sign in by device approval\n\nBefore choosing a workspace, check what the human already has. These commands\nonly read state. The CLI checks run only when section 2 found a `relay_cli`;\nnever call the `.deb`'s `/usr/bin/agent-relay` launcher for them:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'\nif test -n \"${relay_cli:-}\"; then\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nSign in to the workspace they already use. Pick a different or new workspace\nonly when the human explicitly asks for it.\n\nFor a multi-server rollout, obtain the existing enterprise workspace UUID from\nthe human and pass it explicitly on every server. Do not guess it and do not\nuse `{}` when the target workspace is known: that could select a default/free\nworkspace and split the fleet. Use `{}` only for an individual setup where the\nhuman has confirmed that the reusable login's current workspace is intended.\n\n```sh\nrelay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'\nsign_in_payload=$(jq -nc --arg workspace \"$relay_workspace_uuid\" '{workspace:$workspace}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nIf sign-in reports that older upload schedules could not be inspected, first\ninspect the user's legacy cron, launchd, and user-service upload schedules.\nAfter completing that safety check, retry the original request with the\nacknowledgement added; never use it merely to suppress the error:\n\n```sh\nsign_in_payload=$(printf '%s\\n' \"$sign_in_payload\" | \\\n  jq '. + {acknowledge_uninspected_schedules:true}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nPrint a device link and code only when the response actually contains a code:\n\n```sh\nuser_code=$(printf '%s\\n' \"$sign_in\" | jq -r '.data.user_code // empty')\nif test -n \"$user_code\"; then\n  verification_url_complete=$(printf '%s\\n' \"$sign_in\" | \\\n    jq -r '.data.verification_url_complete // empty')\n  if test -n \"$verification_url_complete\"; then\n    printf 'Open %s and approve code %s\\n' \"$verification_url_complete\" \"$user_code\"\n  else\n    verification_url=$(printf '%s\\n' \"$sign_in\" | \\\n      jq -r '.data.verification_url // empty')\n    printf 'Open %s and enter code %s\\n' \"$verification_url\" \"$user_code\"\n  fi\nfi\n```\n\nIf the response is `signed_in` with `reused_login:true`, the app reused an\neligible same-origin CLI or desktop login and intentionally issued no device\ncode. Confirm the returned workspace id and name with the human rather than\nwaiting for a code, then continue only if it is the intended workspace.\n\nFor `pending_approval`, the human can approve from any phone or browser. Do not\ncreate another code while this one is pending. A `preparing` response is also\nnormal: poll `/setup/status` at the reported interval. Preparing local history\ncan take about a minute when the app reuses an existing `agent-relay` CLI login.\nPoll both states until sign-in finishes. The reason for a failure is in\n`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so\nprint it, and map the known messages to their fix instead of dumping raw state:\n\n```sh\nwhile :; do\n  state=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status)\n  phase=$(printf '%s' \"$state\" | jq -r '.data.sign_in // .error.code')\n  case \"$phase\" in\n    signed_in)\n      printf '%s\\n' \"$state\" | jq \\\n        '{sign_in: .data.sign_in, workspace: .data.workspace}'\n      break\n      ;;\n    preparing|pending_approval) ;;\n    denied|expired|error)\n      msg=$(printf '%s' \"$state\" | jq -r '.data.sign_in_message // .error.message // \"no message reported\"')\n      printf 'Sign-in %s: %s\\n' \"$phase\" \"$msg\" >&2\n      case \"$msg\" in\n        *\"older managed history uploader\"*)\n          printf 'See \"Sign-in blocked by a legacy uploader\" under Recovery.\\n' >&2 ;;\n        *\"older upload schedules\"*)\n          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\\n' >&2 ;;\n        *) printf '%s\\n' \"$state\" | jq '.data' >&2 ;;\n      esac\n      exit 1\n      ;;\n  esac\n  sleep \"$(printf '%s' \"$sign_in\" | jq -r '.data.interval // 5')\"\ndone\n```\n\n## 4. Apply the agent-led defaults and register this session\n\nRead the current sharing mode before changing it. `/setup/status` reports it as\n`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is\nuploading yet). The probe reports the same field, `sharing_mode`, in\n`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.\n\n```sh\nrelay_prior_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status | jq -r '.data.sharing_mode // empty')\ncase \"$relay_prior_mode\" in\n  new|all|selected) printf 'sharing_mode=%s\\n' \"$relay_prior_mode\" ;;\n  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\n```\n\nContinue only with a verified `new`, `all`, or `selected`. If the status read\nfails or reports no mode, retry once; if it is still unknown, stop and ask the\nhuman how to proceed rather than sending any sharing request.\n\nOn a fresh install, or when it already reports `new`, keep `new`. When an\nexisting install reports `all` (which also uploads past sessions, so it is\nbroader than this skill's default) or `selected`, tell the human the current\nmode and ask whether to keep it or change it to `new`. Never change it silently.\nOnly when the human explicitly chooses a different mode, set\n`relay_sharing_mode` to that answer at the top of the next block; left unset,\nthe block keeps the mode the app reports, so nothing changes without an answer.\nRemember the chosen mode: section 8 checks it again, and shell variables do not\nsurvive between separate tool calls.\n\nThen set and verify all three agent-led defaults even when the app's `/setup/*`\nbootstrap already applied them. Sharing mode `new` uploads every new session;\nauto-activation puts every existing live session and every future session on\nthe relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:\n\n```sh\n# Unset keeps the current mode; set it only to the human's explicit answer.\nif test -z \"${relay_sharing_mode:-}\"; then\n  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status | jq -r '.data.sharing_mode // empty')\nfi\ncase \"$relay_sharing_mode\" in\n  new|all|selected) ;;\n  *) printf 'Sharing mode unknown; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\ndirect_delivery=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' http://relay/setup/direct-delivery)\nprintf '%s\\n' \"$direct_delivery\" | jq\nif ! printf '%s\\n' \"$direct_delivery\" | jq -e '.ok and .data.direct_delivery'; then\n  if printf '%s\\n' \"$direct_delivery\" | jq -e '.error.code == \"managed_policy\"' >/dev/null; then\n    printf 'Organization-managed Claude settings forbid direct delivery.\\n' >&2\n  fi\n  exit 1\nfi\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d \"$(jq -nc --arg mode \"$relay_sharing_mode\" '{mode:$mode}')\" \\\n  http://relay/setup/sharing | jq\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' \\\n  http://relay/setup/auto-activate | jq\nregister=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/register)\nprintf '%s\\n' \"$register\" | jq\nregistration_status=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status)\nprintf '%s\\n' \"$registration_status\" | \\\n  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'\nprintf '%s\\n' \"$registration_status\" | jq -e \\\n  '.ok and (.data.session.id | type == \"string\" and length > 0) and\n   .data.session.registered == true and .data.session.direct_delivery == true'\n```\n\nDirect delivery is checked first so a managed-policy refusal stops setup\nbefore auto-activation or upload settings are changed. Report that refusal\nclearly; never claim the three-default setup completed.\n\nSharing mode and auto-activate are different settings: the former\ncontrols upload eligibility and the latter controls Relay registration. The\nsetup flow requires both.\n\n`POST /register` discovers the nearest live Codex or Claude ancestor. A session\ninside tmux over SSH is valid. Never pass a session id or token in the body.\nThe default name includes a 128-bit session-derived suffix, so dozens of\nsessions in the same checkout receive distinct `name@direct` addresses. Save\nand report the address from `/setup/status` for each session; never reuse one\nsession's address for another. `/register` may omit the session id or\ndirect-delivery state, so its response alone is not verification. Require the\nstatus response to show this session's non-empty id, `registered:true`, and\n`session.direct_delivery:true` as above. An app fix is expected to add those\nfields to `/register`, but the status check remains authoritative.\n\n## 5. Create and test the webhook\n\nPerform this section only when the human requested a webhook (or explicitly\nasked for the full end-to-end setup). Otherwise skip it; webhook creation is a\npersistent external mutation, not an install prerequisite.\n\nCapture the one-time secret without echoing it:\n\n```sh\numask 077\nhook_file=$(mktemp)\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/webhooks >\"$hook_file\"\njq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' \"$hook_file\"\n```\n\nWhen `created:true`, send a unique marker. Initialize every temporary path so\ncleanup can name and delete exact files without `-f` or globs:\n\n```sh\nhook_config=\nmarker=\nwebhook_post_ok=false\nwebhook_post_status=0\nif test \"$(jq -r '.data.created // false' \"$hook_file\")\" = true && \\\n   test \"$(jq -r '.data.secret // empty' \"$hook_file\")\" != ''; then\n  hook_url=$(jq -r '.data.url' \"$hook_file\")\n  hook_secret=$(jq -r '.data.secret' \"$hook_file\")\n  hook_config=$(mktemp)\n  chmod 600 \"$hook_config\"\n  printf 'header = \"Authorization: Bearer %s\"\\n' \"$hook_secret\" >\"$hook_config\"\n  marker=\"agent-relay-webhook-test-$(date +%s)\"\n  if curl -fsS --config \"$hook_config\" -X POST \"$hook_url\" \\\n      -H 'Content-Type: application/json' \\\n      -d \"{\\\"text\\\":\\\"$marker\\\",\\\"source\\\":\\\"agent-driven-setup\\\"}\"; then\n    webhook_post_ok=true\n  else\n    webhook_post_status=$?\n  fi\nelse\n  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\\n' >&2\nfi\nif test -n \"$hook_config\" && test -e \"$hook_config\"; then\n  rm -- \"$hook_config\"\nfi\nif test -e \"$hook_file\"; then\n  rm -- \"$hook_file\"\nfi\nunset hook_secret\nif test \"$webhook_post_ok\" = true; then\n  printf 'Webhook test sent; end this turn and wait for marker: %s\\n' \"$marker\"\nelif test -n \"$marker\"; then\n  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\\n' \\\n    \"$webhook_post_status\" >&2\n  exit \"$webhook_post_status\"\nfi\n```\n\nDo not claim success merely because the POST returned 2xx, and do not sleep or\npoll for the injected message during the same turn. Relay injects only after\nthe session becomes idle between turns. After the POST and exact-file cleanup,\nend the current turn by saying that setup is waiting for the exact marker. On\nthe next turn, confirm that the injected body contains that marker and its\nAgent Relay header contains a full message id; record that id in the final\nevidence. If a polling consumer is part of the setup, also observe that same id\nthere before declaring the webhook test complete. If the webhook already\nexisted, its secret is correctly returned as null; do not revoke or recreate it\nwithout human authorization. Ask for the existing secret or report that the\ndelivery test could not be repeated.\n\n## 6. Subscribe requested integrations\n\nRequire the provider and repository from the human. A GitHub pull request needs\none resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's\nreviews, review comments, conversation comments and check runs to that glob by\nthe PR they reference, so no other glob is needed: nothing is written under\n`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or\n`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This\nworks on every released Desktop and is the path to use today. If a review or\ncomment then never arrives, read it back in relayfile at its own path (the\ntable in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event\nnever reached relayfile\n([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),\nnot that the subscription is wrong.\n\nFirst find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions\n(below) and it is the client for the one-command form once that ships:\n\n```sh\nrelay_probe=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay-probe\" \\\n  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n  \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"\ndo\n  if test -x \"$candidate\"; then relay_probe=$candidate; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\nprintf 'relay_probe=%s\\n' \"${relay_probe:-none}\"\n```\n\nA running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the\nother candidates are the copies bundled by the `.deb`, the macOS app, and the\nper-user tarball. Then subscribe through the socket. On macOS use the probe\nclient when there is one: the system `curl` hides a Codex session's identity\nthere and is refused `not_a_relay_session`, so a Codex session with no probe\nstops instead. `curl` is correct for Claude Code and on Linux:\n\n```sh\n# One client for every socket request in this section and in undo: the probe\n# on macOS (system curl hides a Codex session there), curl elsewhere.\nrelay_req() {  # METHOD PATH [JSON body]\n  if test \"$(uname -s)\" = Darwin && test -n \"${relay_probe:-}\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\\n' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' -d \"$3\" \"http://relay$2\"\n  else\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n\n# This PR's subscriptions, in whichever form they were made. Fails, rather than\n# answering \"none\", when the status cannot be read: both callers stop then.\npr_url='https://github.com/OWNER/REPO/pull/NUMBER'\npr_resources() {\n  relay_status=$(relay_req GET /setup/status) || return 1\n  # -s reads the whole body as one list, so an empty body is an error too.\n  printf '%s\\n' \"$relay_status\" | jq -rs --arg url \"$pr_url\" \\\n    --arg short 'OWNER/REPO#NUMBER' \\\n    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \\\n    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '\n    if length == 1 and .[0].ok == true\n       and (.[0].data.integrations | type) == \"array\" then\n      .[0].data.integrations[] | select(.provider == \"github\") | .resource\n      | select(. == $url or . == $short or startswith($url + \"/\")\n               or startswith($pulls) or startswith($issues))\n    else\n      error(\"Agent Relay status is unreadable; no subscription was changed.\")\n    end'\n}\n\nheld=$(pr_resources) || exit 1\nif printf '%s\\n' \"$held\" | grep -Fqx -e \"$pr_url\" -e 'OWNER/REPO#NUMBER'; then\n  # The one-command subscription is a single complete request: nothing to add.\n  printf 'Already subscribed:\\n%s\\n' \"$held\"\nelif test -z \"$held\" && test -n \"${relay_probe:-}\" && \\\n     \"$relay_probe\" relay --help 2>&1 | grep -q '^  subscribe'; then\n  # The one-command form (below), only for a PR with no subscription yet and\n  # only when the installed probe has it.\n  \"$relay_probe\" relay subscribe \"$pr_url\" | jq\nelse\n  relay_req POST /integrations/subscribe \\\n    \"$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \\\n      '{provider:\"github\",resource:$resource}')\" | jq\nfi\nrelay_req GET /setup/status | jq -c '.data.integrations'\n```\n\nRequire `.ok` and `.data.subscribed` to be `true`, and the entry in the status\nlist to be `ready: true`. A repeated request returns HTTP 409\n`conflict` (\"already subscribed\"). That is success only for a binding made on\nor after 2026-09-19. Earlier bindings predate PR-identity matching\n(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews\nand comments. If the binding may be older, or you cannot tell, recreate it\nonce: `relay_req DELETE /integrations/subscribe` with the same body, then\nsubscribe again. Verified on\nDesktop 2026.10.6 with both the probe client and `curl`.\n\n**One-command form (not yet released).** `relay-desktop#216` adds\n`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`\n(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription\nthat the Desktop correlates with the PR's reviews, comments, and checks. It is\nabsent from Desktop 2026.10.6, where it fails with `unrecognized subcommand\n'subscribe'`, so do not lead with it. Use it only when the installed probe\nadvertises it. The block above makes that choice, and first checks the\nsession's existing subscriptions. A pull request already subscribed with the\none-command form is left alone. A pull request already holding\nthe number glob answers 409 `conflict` on a repeat; recreate that binding once\nif it may predate 2026-09-19 (see above). Extra `reviews`, `status` or\n`issues/NUMBER/comments` globs from an earlier version of this skill never\ndeliver; unsubscribe them.\n\nOnce released, re-test it before relying on its details; the behavior described\nin that PR (a repeat answering `\"already_subscribed\":true`, `--remove` to end it,\nand a numeric subscription covering reviews, comments and checks) has not been verified here.\n\nRefusals and what they mean:\n\n- `not_a_relay_session`, \"Register this session before subscribing it\": run\n  section 4's `POST /register` first.\n- `not_a_relay_session`, \"already managed by this computer's relay\" from\n  `/register`: this session was started by the Agent Relay fleet broker, not\n  the Desktop. Use the workspace CLI below instead.\n- `refused` or `busy`: an earlier subscription is still being made or cleaned\n  up; repeat the command shortly.\n\nA fleet-spawned session, or an operator subscribing a named agent, uses the\n`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in\n`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let\nthe worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail\nwith `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`\nis set:\n\n```sh\npull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'\nrelay_cli_major=\nif test -n \"${relay_cli:-}\"; then\n  relay_cli_major=$(\"$relay_cli\" --version 2>/dev/null | sed -n 's/^[^0-9]*\\([0-9][0-9]*\\)\\..*/\\1/p' | sed -n '1p')\nfi\nif test -n \"$relay_cli_major\" && test \"$relay_cli_major\" -ge 13; then\n  \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelif test -n \"$relay_cli_major\"; then\n  # 12.x and older: keep the ambient agent token from displacing the key.\n  env -u RELAY_AGENT_TOKEN \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelse\n  # No usable installed CLI: run the fixed release without installing it.\n  npx -y agent-relay@13 integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nfi\n```\n\nUse the `relay_cli` found in section 2, never a bare `agent-relay`: on a\n`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may\nresolve to it or to a different, older CLI than the one whose version was\nchecked.\n\nThe CLI path follows `orchestrating-agent-relay`, which subscribes the same\nsingle `pulls/NUMBER/**` glob. Never put the workspace key in argv.\n\nMake the subscribe step a required post-create step in the agent's PR\nworkflow: whenever it authors a PR, it subscribes its own live session\nimmediately, without waiting for an operator to name the PR. This is the\nauthored-PR pattern from `orchestrating-agent-relay`; it covers every future PR\nthe agent authors without subscribing unrelated repository traffic. The\nDesktop removes the subscription itself after the PR closes or merges.\nFor real GitHub verification, use a harmless event the human authorized\non that PR (for example, a test conversation comment and a requested bot\nreview). After causing the event, do not wait or poll within the active turn:\nend the turn saying which event marker is expected. Confirm the injected event\nand record its full message id on the next turn after Relay has delivered it.\nDo not create a comment, review, or rerun without authorization. A successful\nsubscribe response alone does not prove end-to-end delivery.\n\n## 7. Coexist with a REST-polling MCP\n\nDo not disable an existing polling consumer. Desktop injection acknowledges\nonly this registered agent's delivery queue and does not advance a separate\nworkspace consumer's cursor. A polling MCP should use its own identity/cursor,\nnot this session agent's `/v1/deliveries` token.\n\nInjected text contains both the full Relaycast message id and a short `ref`.\nWhen polling and injection can surface the same workspace message, deduplicate\non the full message id before acting. During verification, leave the poller\nrunning and observe the test message there. Then end the current turn so Relay\ncan inject it, and on the next turn confirm the same full id arrived while the\nagent acted only once.\n\n## 8. Final verification and report\n\nRead status again:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'\n```\n\nRequire all three defaults before declaring setup complete. Set\n`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the\nexisting mode the human kept); the check refuses to guess it:\n\n```sh\n: \"${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -e --arg mode \"$relay_sharing_mode\" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'\n```\n\nReport the exact version, `signed_in`, signed-in workspace id and name, sharing\nmode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,\nuploader health, session address, direct-delivery state, webhook test marker,\nsubscriptions, real GitHub event evidence, and polling-coexistence result.\nSeparate verified facts from steps that still require a human or external\nevent.\n\n## Recovery and undo\n\n- **Socket missing or slow:** check `systemctl --user status agent-relay.service`\n  on Linux or `open -a \"Agent Relay\"` on macOS. Confirm the pointer names a\n  socket. Never delete a live socket; restart the owning service/app. A reply\n  that takes up to about 30 seconds is the known latency in section 1\n  (relay-desktop#333), not a fault: allow 60 seconds and retry once.\n- **`not_a_relay_session`:** the command is not a descendant of a supported\n  live Codex/Claude session, or the session id/process start no longer matches.\n  Run it through this agent's shell tool. In tmux, confirm the agent process and\n  shell share the pane's process tree.\n- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message \"An older\n  managed history uploader is active. Stop it explicitly before enabling this\n  probe.\"): the probe counts any of these legacy `ai-hist push` registrations as\n  active, even when idle: the file\n  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded\n  launchd label `com.ai-hist.push`, or a crontab line containing\n  `# ai-hist push (managed)`. Check each, then with the human's approval unload\n  and move aside (do not delete) what exists. Create the backup directory first,\n  use a unique no-clobber destination, and confirm the move before retrying:\n\n  ```sh\n  # bootout exits non-zero when the label was never loaded; that is fine, so\n  # judge success by whether the label is still loaded, not by its exit code.\n  launchctl bootout \"gui/$(id -u)/com.ai-hist.push\" 2>/dev/null || true\n  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then\n    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2\n    exit 1\n  fi\n  plist=\"$HOME/Library/LaunchAgents/com.ai-hist.push.plist\"\n  if test -e \"$plist\"; then\n    backup_dir=\"$HOME/.agentworkforce/backup\"\n    mkdir -p \"$backup_dir\"\n    mv -n \"$plist\" \"$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)\"\n    test ! -e \"$plist\" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }\n  fi\n  ```\n\n  If instead the marked cron line is the cause, back up the full crontab first\n  and remove only that line, so the change can be reversed with\n  `crontab <backup-file>`:\n\n  ```sh\n  mkdir -p \"$HOME/.agentworkforce/backup\"\n  cron_backup=\"$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)\"\n  crontab -l > \"$cron_backup\" && test -s \"$cron_backup\" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }\n  grep -vF '# ai-hist push (managed)' \"$cron_backup\" | crontab -\n  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }\n  ```\n\n  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run\n  `/setup/sign-in` with the same payload.\n- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the\n  request. Restart after `expired` or `denied` to obtain a new code.\n- **Older schedules could not be inspected:** inspect the user's legacy cron,\n  launchd, or user-service upload schedules first. Only after that inspection,\n  retry `/setup/sign-in` with the original payload plus\n  `\"acknowledge_uninspected_schedules\":true`. This flag records a completed\n  safety check; never send it merely to silence an error.\n- **`not_allowed` from `/register`:** enable the app's self-registration\n  setting. Do not bypass it with workspace credentials.\n- **Managed Claude policy:** if direct delivery reports `managed_policy`, the\n  organization controls `crossSessionInbound`; report the policy block rather\n  than modifying managed settings.\n- **Undo registration:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/register | jq`.\n- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,\n  `relay_req`, and `pr_resources` defined, remove every subscription the\n  session holds for the pull request, in whichever form it was made. On macOS\n  `relay_req` uses the probe, and a Codex session without one stops instead of\n  sending a `curl` request that cannot be identified:\n\n  ```sh\n  held=$(pr_resources) || exit 1\n  printf '%s\\n' \"$held\" | while IFS= read -r resource; do\n    test -n \"$resource\" || continue\n    relay_req DELETE /integrations/subscribe \\\n      \"$(jq -nc --arg resource \"$resource\" '{provider:\"github\",resource:$resource}')\" | jq\n  done\n  relay_req GET /setup/status | jq -c '.data.integrations'\n  ```\n\n  Require the final list to hold none of that pull request's resources.\n- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/webhooks | jq`.\n- **Undo direct delivery:** POST `{\"enabled\":false}` to\n  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed\n  organization policy still wins.\n- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to\n  `/setup/sharing`. Ask before changing it when the earlier value is unknown.\n- **Auto-activate accidentally enabled:** POST `{\"enabled\":false}` to\n  `/setup/auto-activate`. This does not remove existing registrations.\n- **Uninstall:** stop/disable the user service before removing the Linux\n  package, or quit the Mac app before removing it. Do not delete app data or\n  revoke webhooks unless the human explicitly asks for data removal.\n",
+  "setting-up-agent-relay-desktop": "# Set Up Agent Relay Desktop\n\nComplete the setup through the private session socket. Do not ask the human to\nclick through the desktop app. The only normal human step is approving one\ndevice-login link when no reusable `agent-relay` CLI login exists.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the current release is installed and running;\n- sign-in is complete;\n- sharing mode is `new` (new sessions upload automatically), unless an existing\n  install already uses another mode and the human chose to keep it (section 4);\n- auto-activate is on, with every existing live session and every future session on the relay;\n- Claude Code direct delivery is on (`crossSessionInbound` is `accept`);\n- this Codex or Claude session is registered and accepts direct delivery;\n- the requested webhook and integration subscriptions work;\n- the human receives the session's `agent@machine` address and verification evidence.\n\nNever put a Cloud token, workspace key, agent token, or webhook secret in a\nRelay message. The webhook secret is returned once to this local calling\nsession; keep it in a mode-0600 temporary file and delete the file after the\ntest.\n\n## Install this skill for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage, then place that unchanged `SKILL.md` where Codex actually loads global\nskills:\n\n```sh\nnpx prpm install @agent-relay/setting-up-agent-relay-desktop --as claude --global -y\ncodex_skill=\"$HOME/.codex/skills/setting-up-agent-relay-desktop\"\nmkdir -p \"$codex_skill\"\ninstall -m 0644 \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\ncmp \\\n  \"$HOME/.claude/skills/setting-up-agent-relay-desktop/SKILL.md\" \\\n  \"$codex_skill/SKILL.md\"\n```\n\nDo not use prpm's `--as codex` conversion for this package. It currently writes\nunder `~/.agents/skills`, which Codex does not load as its global skill folder,\nand its conversion drops explanatory paragraphs from this Markdown workflow.\nConfirm both final paths explicitly before continuing.\n\n## 1. Detect the host and current session\n\nRun setup commands from this agent's own shell tool. Do not run them from an\nunrelated terminal: the app identifies the caller from kernel credentials and\nthe Codex/Claude process ancestry.\n\n```sh\nuname -s\nuname -m\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\nif test \"$(uname -s)\" = Linux; then\n  if command -v dpkg-query >/dev/null; then\n    printf 'linux_install=deb\\n'\n  else\n    printf 'linux_install=per-user-tarball\\n'\n  fi\nfi\ncommand -v systemctl >/dev/null && systemctl --user is-system-running || true\n```\n\nOn Ubuntu with `dpkg`, prefer the `.deb` path below. On Arch-based and other\nsystemd Linux hosts without `dpkg`, use the checksum-verified per-user tarball\npath; do not try to install the `.deb`. The app scans same-user process trees\nand TTYs; it does not require the service itself to share the tmux session.\n\n`systemctl --user is-system-running` may report `degraded` because an unrelated\nuser unit failed. That is not a Relay failure when\n`systemctl --user is-active agent-relay.service` reports `active` and the Relay\nsocket passes its status check.\n\nFind an existing socket without printing private files:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test -n \"${XDG_RUNTIME_DIR:-}\"; then\n  relay_socket=\"$XDG_RUNTIME_DIR/agent-relay/relay.sock\"\nfi\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"/run/user/$(id -u)/agent-relay/relay.sock\"\nfi\nc=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nif ! test -S \"${relay_socket:-/nonexistent}\" && test \"$(uname -s)\" = Darwin && test -S \"$c\"; then   # pointer file missing: use the app's own socket\n  relay_socket=$c\nfi\ntest -S \"${relay_socket:-/nonexistent}\" && printf 'socket=%s\\n' \"$relay_socket\"\n```\n\nIf the socket exists, inspect it before installing anything:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout\n(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's\n`relay socket-request` can give up sooner with \"Probe could not finish. Check\nyour connection and run setup again\"; on these paths that is the same latency,\nnot a setup problem. Retry the call once before reporting a blocker, and do not\nstart a second install or sign-in because of it.\n\nPreserve a working newer install. When the socket is absent, check for an\ninstalled-but-stopped copy before downloading: use `dpkg-query -W agent-relay`\nwhen `dpkg-query` exists and `systemctl --user status agent-relay.service` on\nLinux, or test `/Applications/Agent Relay.app` on macOS. Start it and retry\nstatus first.\nUpdate an older install only when it lacks the setup contract or reports an\nolder version. A `404` from `/setup/status` means the installed build is too\nold for agent-driven setup and should be updated.\n\n## 2. Install or update with checksum verification\n\nUse a private temporary directory. Never skip the published SHA-256 check.\n\n### Ubuntu LTS, headless `.deb` (preferred)\n\nSelect the release architecture and install:\n\nThis path needs passwordless sudo or one human-approved sudo prompt for the\npackage install and `loginctl enable-linger`. Explain that prerequisite before\nstarting; never capture or relay a sudo password.\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb\" -o \"$relay_tmp/AgentRelay.deb\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.deb.sha256\" -o \"$relay_tmp/AgentRelay.deb.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.deb#AgentRelay.deb#\" AgentRelay.deb.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nsudo apt-get install -y \"$relay_tmp/AgentRelay.deb\"\nsudo loginctl enable-linger \"$USER\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n```\n\nThe unit runs the bundled core headless: no display, X server, or GTK\nwindow is needed. This session's own GitHub subscriptions (section 6) go\nthrough the Desktop and need no CLI. The separate Agent Relay CLI is needed\nonly to subscribe a fleet-spawned or named agent; record whether it is present\nand at least 13.0.0. Find the same user-level npm, mise, or nvm CLI the app\ndiscovers; never run the desktop's `/usr/bin/agent-relay` launcher as a CLI:\n\n```sh\nrelay_cli=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay\" \\\n  \"$HOME/.npm-global/bin/agent-relay\" \\\n  \"$HOME/.agentworkforce/relay/bin/agent-relay\"\ndo\n  if test -x \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n    relay_cli=$candidate\n    break\n  fi\ndone\nif test -z \"$relay_cli\"; then\n  for relay_root in \\\n    \"$HOME/.local/share/mise/installs/node\" \\\n    \"$HOME/.nvm/versions/node\"\n  do\n    test -d \"$relay_root\" || continue\n    candidate=$(find -L \"$relay_root\" -mindepth 3 -maxdepth 3 \\\n      -path '*/bin/agent-relay' -type f -perm -u+x -print -quit 2>/dev/null)\n    if test -n \"$candidate\" && test \"$candidate\" != /usr/bin/agent-relay; then\n      relay_cli=$candidate\n      break\n    fi\n  done\nfi\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" integration subscribe --help >/dev/null\nelse\n  printf 'No Agent Relay CLI found; Desktop subscriptions do not need one.\\n'\nfi\n```\n\nOn Linux without `dpkg`, use this per-user tarball installation under a\nversioned user directory. It is also the fallback on Ubuntu when `.deb`\ninstallation is unavailable and the human approves a per-user install. The\narchive contains a unit whose `/usr/bin` path is correct for packages, so\nrewrite only that `ExecStart` in the user copy:\n\n```sh\ncase \"$(uname -m)\" in\n  x86_64|amd64) relay_arch=x64 ;;\n  aarch64|arm64) relay_arch=arm64 ;;\n  *) printf 'Unsupported Linux architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz\" -o \"$relay_tmp/AgentRelay.tar.gz\"\ncurl -fL \"$release/AgentRelay-Linux-$relay_arch.tar.gz.sha256\" -o \"$relay_tmp/AgentRelay.tar.gz.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-Linux-$relay_arch.tar.gz#AgentRelay.tar.gz#\" AgentRelay.tar.gz.sha256 | sha256sum --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmkdir \"$relay_tmp/extracted\"\ntar -xzf \"$relay_tmp/AgentRelay.tar.gz\" -C \"$relay_tmp/extracted\"\nrelay_tree=\"$relay_tmp/extracted/AgentRelay-linux-$relay_arch\"\ntest -x \"$relay_tree/usr/bin/agent-relay\"\nrelay_version=$(sed -n 's/^__version__ = \"\\([0-9A-Za-z._-]*\\)\"$/\\1/p' \\\n  \"$relay_tree/usr/lib/agent-relay/agent_relay/__init__.py\")\ncase \"$relay_version\" in\n  ''|*[!0-9A-Za-z._-]*) printf 'Invalid Agent Relay version in archive.\\n' >&2; exit 1 ;;\nesac\nrelay_unit=\"$HOME/.config/systemd/user/agent-relay.service\"\nrelay_installed_version=\nif test -S \"${relay_socket:-/nonexistent}\"; then\n  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)\nfi\nif test -z \"$relay_installed_version\" && test -r \"$relay_unit\"; then\n  relay_installed_version=$(sed -n \\\n    's#^ExecStart=.*/\\.local/lib/agent-relay/\\([^/ ]*\\)/.*#\\1#p' \\\n    \"$relay_unit\")\nfi\ncase \"$relay_installed_version\" in\n  ''|*[!0-9A-Za-z._-]*) relay_installed_version= ;;\nesac\nif test -n \"$relay_installed_version\" && \\\n   test \"$relay_installed_version\" != \"$relay_version\" && \\\n   test \"$(printf '%s\\n%s\\n' \"$relay_version\" \"$relay_installed_version\" | sort -V | tail -n 1)\" = \"$relay_installed_version\"; then\n  printf 'Installed Agent Relay %s is newer than archive %s; refusing downgrade.\\n' \\\n    \"$relay_installed_version\" \"$relay_version\" >&2\n  exit 1\nfi\nrelay_prefix=\"$HOME/.local/lib/agent-relay/$relay_version\"\nmkdir -p \"$relay_prefix\"\ncp -a \"$relay_tree/usr\" \"$relay_prefix/\"\nmkdir -p \"$(dirname \"$relay_unit\")\"\nsed \"s#^ExecStart=/usr/#ExecStart=$relay_prefix/usr/#\" \\\n  \"$relay_tree/usr/lib/systemd/user/agent-relay.service\" >\"$relay_unit.tmp\"\nchmod 0644 \"$relay_unit.tmp\"\nmv \"$relay_unit.tmp\" \"$relay_unit\"\ngrep -F \"ExecStart=$relay_prefix/usr/\" \"$relay_unit\" | grep -q -- ' --headless$'\nif ! loginctl show-user \"$USER\" -p Linger | grep -qx 'Linger=yes'; then\n  sudo loginctl enable-linger \"$USER\"\nfi\nsystemd-analyze --user verify \"$relay_unit\"\nsystemctl --user daemon-reload\nsystemctl --user enable agent-relay.service\nsystemctl --user restart agent-relay.service\nsystemctl --user is-active agent-relay.service\nloginctl show-user \"$USER\" -p Linger\n# List the app in the desktop's app launcher (no-op on a headless server).\n# Releases before v2026.10.13 lack agent-relay-desktop; the app then adds the\n# entry the first time it is opened.\nif test -x \"$relay_prefix/usr/bin/agent-relay-desktop\"; then\n  \"$relay_prefix/usr/bin/agent-relay-desktop\" --install-launcher || true\nfi\n```\n\nThe unit's `ExecStart` names the archive's own path under `/usr/`, either the\nlauncher or the bundled `agent-relay-probe`; the rewrite moves whichever it is\nunder `$relay_prefix`. The launcher entry runs `agent-relay-desktop` by its\nfull path, never the bare `agent-relay`, which is also the CLI's name.\n\nDo not improvise Alpine or RHEL distribution packages. On a compatible\nsystemd host without `dpkg`, use only the verified per-user tarball path above;\nnon-systemd hosts remain unsupported by this Linux workflow.\n\n### macOS DMG\n\n```sh\ncase \"$(uname -m)\" in\n  arm64) relay_arch=arm64 ;;\n  x86_64) relay_arch=x64 ;;\n  *) printf 'Unsupported Mac architecture: %s\\n' \"$(uname -m)\" >&2; exit 2 ;;\nesac\nrelay_tmp=$(mktemp -d)\nchmod 700 \"$relay_tmp\"\nrelease=https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg\" -o \"$relay_tmp/AgentRelay.dmg\"\ncurl -fL \"$release/AgentRelay-macOS-$relay_arch.dmg.sha256\" -o \"$relay_tmp/AgentRelay.dmg.sha256\"\nif ! (cd \"$relay_tmp\" && sed \"s#AgentRelay-macOS-$relay_arch.dmg#AgentRelay.dmg#\" AgentRelay.dmg.sha256 | shasum -a 256 --check -); then\n  printf 'Agent Relay checksum verification failed; refusing installation.\\n' >&2\n  exit 1\nfi\nmount_point=$(hdiutil attach -nobrowse -readonly \"$relay_tmp/AgentRelay.dmg\" | awk '/\\/Volumes\\// {sub(/^.*\\/Volumes\\//,\"/Volumes/\"); print; exit}')\nincoming_id=$(defaults read \"$mount_point/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\nif test \"$incoming_id\" != com.agentrelay.desktop; then\n  hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n  printf 'Downloaded app has unexpected bundle id %s; refusing installation.\\n' \"$incoming_id\" >&2\n  exit 1\nfi\nif test -d \"/Applications/Agent Relay.app\"; then\n  existing_id=$(defaults read \"/Applications/Agent Relay.app/Contents/Info\" CFBundleIdentifier 2>/dev/null || true)\n  if test \"$existing_id\" != com.agentrelay.desktop; then\n    hdiutil detach \"$mount_point\" >/dev/null 2>&1 || true\n    printf 'Existing Agent Relay.app has unexpected bundle id %s; refusing overwrite.\\n' \"$existing_id\" >&2\n    exit 1\n  fi\nfi\nosascript -e 'tell application \"Agent Relay\" to quit' 2>/dev/null || true\nditto \"$mount_point/Agent Relay.app\" \"/Applications/Agent Relay.app\"\nhdiutil detach \"$mount_point\"\nopen -a \"Agent Relay\"\n```\n\nIf `/Applications` needs administrator access, use `sudo ditto` only after the\nhuman has authorized installation. Do not remove or overwrite another app with\nan unexpected bundle identity.\n\nAfter either install, wait up to 30 seconds for the pointer:\n\n```sh\napp_sock=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\nfor _ in $(seq 1 30); do\n  test -r \"$HOME/.agentworkforce/desktop/relay-socket\" && break\n  test \"$(uname -s)\" = Darwin && test -S \"$app_sock\" && break   # the app is already listening\n  sleep 1\ndone\nrelay_socket=$(sed -n '1p' \"$HOME/.agentworkforce/desktop/relay-socket\" 2>/dev/null)\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Darwin && test -S \"$app_sock\"; then\n  relay_socket=$app_sock\nfi\nif ! test -S \"$relay_socket\" && test \"$(uname -s)\" = Linux; then\n  relay_socket=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock\"\nfi\ntest -S \"$relay_socket\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'\n```\n\n## 3. Sign in by device approval\n\nBefore choosing a workspace, check what the human already has. These commands\nonly read state. The CLI checks run only when section 2 found a `relay_cli`;\nnever call the `.deb`'s `/usr/bin/agent-relay` launcher for them:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{sign_in: .data.sign_in, workspace: .data.workspace}'\nif test -n \"${relay_cli:-}\"; then\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nSign in to the workspace they already use. Pick a different or new workspace\nonly when the human explicitly asks for it.\n\nFor a multi-server rollout, obtain the existing enterprise workspace UUID from\nthe human and pass it explicitly on every server. Do not guess it and do not\nuse `{}` when the target workspace is known: that could select a default/free\nworkspace and split the fleet. Use `{}` only for an individual setup where the\nhuman has confirmed that the reusable login's current workspace is intended.\n\n```sh\nrelay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'\nsign_in_payload=$(jq -nc --arg workspace \"$relay_workspace_uuid\" '{workspace:$workspace}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nIf sign-in reports that older upload schedules could not be inspected, first\ninspect the user's legacy cron, launchd, and user-service upload schedules.\nAfter completing that safety check, retry the original request with the\nacknowledgement added; never use it merely to suppress the error:\n\n```sh\nsign_in_payload=$(printf '%s\\n' \"$sign_in_payload\" | \\\n  jq '. + {acknowledge_uninspected_schedules:true}')\nsign_in=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$sign_in_payload\" http://relay/setup/sign-in)\nprintf '%s\\n' \"$sign_in\" | jq \\\n  '{ok, data: {\n    status: .data.status,\n    reused_login: .data.reused_login,\n    workspace: .data.workspace\n  }, error}'\n```\n\nPrint a device link and code only when the response actually contains a code:\n\n```sh\nuser_code=$(printf '%s\\n' \"$sign_in\" | jq -r '.data.user_code // empty')\nif test -n \"$user_code\"; then\n  verification_url_complete=$(printf '%s\\n' \"$sign_in\" | \\\n    jq -r '.data.verification_url_complete // empty')\n  if test -n \"$verification_url_complete\"; then\n    printf 'Open %s and approve code %s\\n' \"$verification_url_complete\" \"$user_code\"\n  else\n    verification_url=$(printf '%s\\n' \"$sign_in\" | \\\n      jq -r '.data.verification_url // empty')\n    printf 'Open %s and enter code %s\\n' \"$verification_url\" \"$user_code\"\n  fi\nfi\n```\n\nIf the response is `signed_in` with `reused_login:true`, the app reused an\neligible same-origin CLI or desktop login and intentionally issued no device\ncode. Confirm the returned workspace id and name with the human rather than\nwaiting for a code, then continue only if it is the intended workspace.\n\nFor `pending_approval`, the human can approve from any phone or browser. Do not\ncreate another code while this one is pending. A `preparing` response is also\nnormal: poll `/setup/status` at the reported interval. Preparing local history\ncan take about a minute when the app reuses an existing `agent-relay` CLI login.\nPoll both states until sign-in finishes. The reason for a failure is in\n`.data.sign_in_message`, not in `.data.sign_in` (which only says `error`), so\nprint it, and map the known messages to their fix instead of dumping raw state:\n\n```sh\nwhile :; do\n  state=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status)\n  phase=$(printf '%s' \"$state\" | jq -r '.data.sign_in // .error.code')\n  case \"$phase\" in\n    signed_in)\n      printf '%s\\n' \"$state\" | jq \\\n        '{sign_in: .data.sign_in, workspace: .data.workspace}'\n      break\n      ;;\n    preparing|pending_approval) ;;\n    denied|expired|error)\n      msg=$(printf '%s' \"$state\" | jq -r '.data.sign_in_message // .error.message // \"no message reported\"')\n      printf 'Sign-in %s: %s\\n' \"$phase\" \"$msg\" >&2\n      case \"$msg\" in\n        *\"older managed history uploader\"*)\n          printf 'See \"Sign-in blocked by a legacy uploader\" under Recovery.\\n' >&2 ;;\n        *\"older upload schedules\"*)\n          printf 'Inspect legacy schedules, then retry with acknowledge_uninspected_schedules (see above).\\n' >&2 ;;\n        *) printf '%s\\n' \"$state\" | jq '.data' >&2 ;;\n      esac\n      exit 1\n      ;;\n  esac\n  sleep \"$(printf '%s' \"$sign_in\" | jq -r '.data.interval // 5')\"\ndone\n```\n\n## 4. Apply the agent-led defaults and register this session\n\nRead the current sharing mode before changing it. `/setup/status` reports it as\n`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is\nuploading yet). The probe reports the same field, `sharing_mode`, in\n`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.\n\n```sh\nrelay_prior_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status | jq -r '.data.sharing_mode // empty')\ncase \"$relay_prior_mode\" in\n  new|all|selected) printf 'sharing_mode=%s\\n' \"$relay_prior_mode\" ;;\n  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\n```\n\nContinue only with a verified `new`, `all`, or `selected`. If the status read\nfails or reports no mode, retry once; if it is still unknown, stop and ask the\nhuman how to proceed rather than sending any sharing request.\n\nOn a fresh install, or when it already reports `new`, keep `new`. When an\nexisting install reports `all` (which also uploads past sessions, so it is\nbroader than this skill's default) or `selected`, tell the human the current\nmode and ask whether to keep it or change it to `new`. Never change it silently.\nOnly when the human explicitly chooses a different mode, set\n`relay_sharing_mode` to that answer at the top of the next block; left unset,\nthe block keeps the mode the app reports, so nothing changes without an answer.\nRemember the chosen mode: section 8 checks it again, and shell variables do not\nsurvive between separate tool calls.\n\nThen set and verify all three agent-led defaults even when the app's `/setup/*`\nbootstrap already applied them. Sharing mode `new` uploads every new session;\nauto-activation puts every existing live session and every future session on\nthe relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:\n\n```sh\n# Unset keeps the current mode; set it only to the human's explicit answer.\nif test -z \"${relay_sharing_mode:-}\"; then\n  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n    http://relay/setup/status | jq -r '.data.sharing_mode // empty')\nfi\ncase \"$relay_sharing_mode\" in\n  new|all|selected) ;;\n  *) printf 'Sharing mode unknown; ask the human before changing sharing.\\n' >&2\n     exit 1 ;;\nesac\ndirect_delivery=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' http://relay/setup/direct-delivery)\nprintf '%s\\n' \"$direct_delivery\" | jq\nif ! printf '%s\\n' \"$direct_delivery\" | jq -e '.ok and .data.direct_delivery'; then\n  if printf '%s\\n' \"$direct_delivery\" | jq -e '.error.code == \"managed_policy\"' >/dev/null; then\n    printf 'Organization-managed Claude settings forbid direct delivery.\\n' >&2\n  fi\n  exit 1\nfi\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d \"$(jq -nc --arg mode \"$relay_sharing_mode\" '{mode:$mode}')\" \\\n  http://relay/setup/sharing | jq\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{\"enabled\":true}' \\\n  http://relay/setup/auto-activate | jq\nregister=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/register)\nprintf '%s\\n' \"$register\" | jq\nregistration_status=$(curl -sS --max-time 60 --unix-socket \"$relay_socket\" \\\n  http://relay/setup/status)\nprintf '%s\\n' \"$registration_status\" | \\\n  jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'\nprintf '%s\\n' \"$registration_status\" | jq -e \\\n  '.ok and (.data.session.id | type == \"string\" and length > 0) and\n   .data.session.registered == true and .data.session.direct_delivery == true'\n```\n\n**Codex on macOS.** The system `curl` hides a Codex session's identity from the\nsocket there, so `/register` is refused `not_a_relay_session` (section 6 says\nthe same for subscriptions). In a Codex session on macOS, find `relay_probe`\nwith section 6's first block and send the registration through it instead of\nthe `curl` line above, then read `/setup/status` as above:\n\n```sh\nregister=$(printf '{}' | \"$relay_probe\" relay socket-request \\\n  --socket \"$relay_socket\" --method POST --path /register)\n```\n\nIf `/setup/sign-in` is refused the same way, send its payload through the probe\nthe same way. Without a probe, stop and report it rather than registering\nanother process.\n\nDirect delivery is checked first so a managed-policy refusal stops setup\nbefore auto-activation or upload settings are changed. Report that refusal\nclearly; never claim the three-default setup completed.\n\nSharing mode and auto-activate are different settings: the former\ncontrols upload eligibility and the latter controls Relay registration. The\nsetup flow requires both.\n\n`POST /register` discovers the nearest live Codex or Claude ancestor. A session\ninside tmux over SSH is valid. Never pass a session id or token in the body.\nThe default name includes a 128-bit session-derived suffix, so dozens of\nsessions in the same checkout receive distinct `name@direct` addresses. Save\nand report the address from `/setup/status` for each session; never reuse one\nsession's address for another. `/register` may omit the session id or\ndirect-delivery state, so its response alone is not verification. Require the\nstatus response to show this session's non-empty id, `registered:true`, and\n`session.direct_delivery:true` as above. An app fix is expected to add those\nfields to `/register`, but the status check remains authoritative.\n\n## 5. Create and test the webhook\n\nPerform this section only when the human requested a webhook (or explicitly\nasked for the full end-to-end setup). Otherwise skip it; webhook creation is a\npersistent external mutation, not an install prerequisite.\n\nCapture the one-time secret without echoing it:\n\n```sh\numask 077\nhook_file=$(mktemp)\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" -H 'Content-Type: application/json' \\\n  -d '{}' http://relay/webhooks >\"$hook_file\"\njq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' \"$hook_file\"\n```\n\nWhen `created:true`, send a unique marker. Initialize every temporary path so\ncleanup can name and delete exact files without `-f` or globs:\n\n```sh\nhook_config=\nmarker=\nwebhook_post_ok=false\nwebhook_post_status=0\nif test \"$(jq -r '.data.created // false' \"$hook_file\")\" = true && \\\n   test \"$(jq -r '.data.secret // empty' \"$hook_file\")\" != ''; then\n  hook_url=$(jq -r '.data.url' \"$hook_file\")\n  hook_secret=$(jq -r '.data.secret' \"$hook_file\")\n  hook_config=$(mktemp)\n  chmod 600 \"$hook_config\"\n  printf 'header = \"Authorization: Bearer %s\"\\n' \"$hook_secret\" >\"$hook_config\"\n  marker=\"agent-relay-webhook-test-$(date +%s)\"\n  if curl -fsS --config \"$hook_config\" -X POST \"$hook_url\" \\\n      -H 'Content-Type: application/json' \\\n      -d \"{\\\"text\\\":\\\"$marker\\\",\\\"source\\\":\\\"agent-driven-setup\\\"}\"; then\n    webhook_post_ok=true\n  else\n    webhook_post_status=$?\n  fi\nelse\n  printf 'Webhook already exists; its original secret is required to repeat delivery verification.\\n' >&2\nfi\nif test -n \"$hook_config\" && test -e \"$hook_config\"; then\n  rm -- \"$hook_config\"\nfi\nif test -e \"$hook_file\"; then\n  rm -- \"$hook_file\"\nfi\nunset hook_secret\nif test \"$webhook_post_ok\" = true; then\n  printf 'Webhook test sent; end this turn and wait for marker: %s\\n' \"$marker\"\nelif test -n \"$marker\"; then\n  printf 'Webhook test POST failed with curl status %s; do not wait for delivery.\\n' \\\n    \"$webhook_post_status\" >&2\n  exit \"$webhook_post_status\"\nfi\n```\n\nDo not claim success merely because the POST returned 2xx, and do not sleep or\npoll for the injected message during the same turn. Relay injects only after\nthe session becomes idle between turns. After the POST and exact-file cleanup,\nend the current turn by saying that setup is waiting for the exact marker. On\nthe next turn, confirm that the injected body contains that marker and its\nAgent Relay header contains a full message id; record that id in the final\nevidence. If a polling consumer is part of the setup, also observe that same id\nthere before declaring the webhook test complete. If the webhook already\nexisted, its secret is correctly returned as null; do not revoke or recreate it\nwithout human authorization. Ask for the existing secret or report that the\ndelivery test could not be repeated.\n\n## 6. Subscribe requested integrations\n\nRequire the provider and repository from the human. A GitHub pull request needs\none resource glob, its number (`pulls/NUMBER/**`). Relayfile matches the PR's\nreviews, review comments, conversation comments and check runs to that glob by\nthe PR they reference, so no other glob is needed: nothing is written under\n`pulls/NUMBER/reviews/**`, `pulls/NUMBER/status/**` or\n`issues/NUMBER/comments/**`, and subscriptions on those never deliver. This\nworks on every released Desktop and is the path to use today. If a review or\ncomment then never arrives, read it back in relayfile at its own path (the\ntable in `subscribing-relay-webhooks-and-writebacks`): a 404 means the event\nnever reached relayfile\n([relayfile-cloud#317](https://github.com/AgentWorkforce/relayfile-cloud/issues/317)),\nnot that the subscription is wrong.\n\nFirst find the Desktop's `agent-relay-probe`. macOS needs it for Codex sessions\n(below) and it is the client for the one-command form once that ships:\n\n```sh\nrelay_probe=\nfor candidate in \\\n  \"$HOME/.local/bin/agent-relay-probe\" \\\n  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n  \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"\ndo\n  if test -x \"$candidate\"; then relay_probe=$candidate; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\nprintf 'relay_probe=%s\\n' \"${relay_probe:-none}\"\n```\n\nA running Desktop keeps `~/.local/bin/agent-relay-probe` at its own version; the\nother candidates are the copies bundled by the `.deb`, the macOS app, and the\nper-user tarball. Then subscribe through the socket. On macOS use the probe\nclient when there is one: the system `curl` hides a Codex session's identity\nthere and is refused `not_a_relay_session`, so a Codex session with no probe\nstops instead. `curl` is correct for Claude Code and on Linux:\n\n```sh\n# One client for every socket request in this section and in undo: the probe\n# on macOS (system curl hides a Codex session there), curl elsewhere.\nrelay_req() {  # METHOD PATH [JSON body]\n  if test \"$(uname -s)\" = Darwin && test -n \"${relay_probe:-}\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\\n' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' -d \"$3\" \"http://relay$2\"\n  else\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n\n# This PR's subscriptions, in whichever form they were made. Fails, rather than\n# answering \"none\", when the status cannot be read: both callers stop then.\npr_url='https://github.com/OWNER/REPO/pull/NUMBER'\npr_resources() {\n  relay_status=$(relay_req GET /setup/status) || return 1\n  # -s reads the whole body as one list, so an empty body is an error too.\n  printf '%s\\n' \"$relay_status\" | jq -rs --arg url \"$pr_url\" \\\n    --arg short 'OWNER/REPO#NUMBER' \\\n    --arg pulls '/github/repos/OWNER/REPO/pulls/NUMBER/' \\\n    --arg issues '/github/repos/OWNER/REPO/issues/NUMBER/' '\n    if length == 1 and .[0].ok == true\n       and (.[0].data.integrations | type) == \"array\" then\n      .[0].data.integrations[] | select(.provider == \"github\") | .resource\n      | select(. == $url or . == $short or startswith($url + \"/\")\n               or startswith($pulls) or startswith($issues))\n    else\n      error(\"Agent Relay status is unreadable; no subscription was changed.\")\n    end'\n}\n\nheld=$(pr_resources) || exit 1\nif printf '%s\\n' \"$held\" | grep -Fqx -e \"$pr_url\" -e 'OWNER/REPO#NUMBER'; then\n  # The one-command subscription is a single complete request: nothing to add.\n  printf 'Already subscribed:\\n%s\\n' \"$held\"\nelif test -z \"$held\" && test -n \"${relay_probe:-}\" && \\\n     \"$relay_probe\" relay --help 2>&1 | grep -q '^  subscribe'; then\n  # The one-command form (below), only for a PR with no subscription yet and\n  # only when the installed probe has it.\n  \"$relay_probe\" relay subscribe \"$pr_url\" | jq\nelse\n  relay_req POST /integrations/subscribe \\\n    \"$(jq -nc --arg resource '/github/repos/OWNER/REPO/pulls/NUMBER/**' \\\n      '{provider:\"github\",resource:$resource}')\" | jq\nfi\nrelay_req GET /setup/status | jq -c '.data.integrations'\n```\n\nRequire `.ok` and `.data.subscribed` to be `true`, and the entry in the status\nlist to be `ready: true`. A repeated request returns HTTP 409\n`conflict` (\"already subscribed\"). That is success only for a binding made on\nor after 2026-09-19. Earlier bindings predate PR-identity matching\n(relayfile-cloud#237, relaycast#447), match paths literally and miss reviews\nand comments. If the binding may be older, or you cannot tell, recreate it\nonce: `relay_req DELETE /integrations/subscribe` with the same body, then\nsubscribe again. Verified on\nDesktop 2026.10.6 with both the probe client and `curl`.\n\n**One-command form (not yet released).** `relay-desktop#216` adds\n`agent-relay-probe relay subscribe 'https://github.com/OWNER/REPO/pull/NUMBER'`\n(or `OWNER/REPO#NUMBER`), which makes one numeric `pulls/NUMBER/**` subscription\nthat the Desktop correlates with the PR's reviews, comments, and checks. It is\nabsent from Desktop 2026.10.6, where it fails with `unrecognized subcommand\n'subscribe'`, so do not lead with it. Use it only when the installed probe\nadvertises it. The block above makes that choice, and first checks the\nsession's existing subscriptions. A pull request already subscribed with the\none-command form is left alone. A pull request already holding\nthe number glob answers 409 `conflict` on a repeat; recreate that binding once\nif it may predate 2026-09-19 (see above). Extra `reviews`, `status` or\n`issues/NUMBER/comments` globs from an earlier version of this skill never\ndeliver; unsubscribe them.\n\nOnce released, re-test it before relying on its details; the behavior described\nin that PR (a repeat answering `\"already_subscribed\":true`, `--remove` to end it,\nand a numeric subscription covering reviews, comments and checks) has not been verified here.\n\nRefusals and what they mean:\n\n- `not_a_relay_session`, \"Register this session before subscribing it\": run\n  section 4's `POST /register` first.\n- `not_a_relay_session`, \"already managed by this computer's relay\" from\n  `/register`: this session was started by the Agent Relay fleet broker, not\n  the Desktop. Use the workspace CLI below instead.\n- `refused` or `busy`: an earlier subscription is still being made or cleaned\n  up; repeat the command shortly.\n\nA fleet-spawned session, or an operator subscribing a named agent, uses the\n`agent-relay` CLI with `--to @AGENT_NAME` (a spawned worker's name is in\n`RELAY_AGENT_NAME`). **`agent-relay` 13.0.0 is the minimum.** Older CLIs let\nthe worker's ambient `RELAY_AGENT_TOKEN` displace the workspace key and fail\nwith `Workspace key required (rk_live_...)` even though `RELAY_WORKSPACE_KEY`\nis set:\n\n```sh\npull_glob='/github/repos/OWNER/REPO/pulls/NUMBER/**'\nrelay_cli_major=\nif test -n \"${relay_cli:-}\"; then\n  relay_cli_major=$(\"$relay_cli\" --version 2>/dev/null | sed -n 's/^[^0-9]*\\([0-9][0-9]*\\)\\..*/\\1/p' | sed -n '1p')\nfi\nif test -n \"$relay_cli_major\" && test \"$relay_cli_major\" -ge 13; then\n  \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelif test -n \"$relay_cli_major\"; then\n  # 12.x and older: keep the ambient agent token from displacing the key.\n  env -u RELAY_AGENT_TOKEN \"$relay_cli\" integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nelse\n  # No usable installed CLI: run the fixed release without installing it.\n  npx -y agent-relay@13 integration subscribe github \\\n    --resource \"$pull_glob\" --to '@AGENT_NAME' --no-input\nfi\n```\n\nUse the `relay_cli` found in section 2, never a bare `agent-relay`: on a\n`.deb` host `/usr/bin/agent-relay` is the Desktop launcher, and `PATH` may\nresolve to it or to a different, older CLI than the one whose version was\nchecked.\n\nThe CLI path follows `orchestrating-agent-relay`, which subscribes the same\nsingle `pulls/NUMBER/**` glob. Never put the workspace key in argv.\n\nMake the subscribe step a required post-create step in the agent's PR\nworkflow: whenever it authors a PR, it subscribes its own live session\nimmediately, without waiting for an operator to name the PR. This is the\nauthored-PR pattern from `orchestrating-agent-relay`; it covers every future PR\nthe agent authors without subscribing unrelated repository traffic. The\nDesktop removes the subscription itself after the PR closes or merges.\nFor real GitHub verification, use a harmless event the human authorized\non that PR (for example, a test conversation comment and a requested bot\nreview). After causing the event, do not wait or poll within the active turn:\nend the turn saying which event marker is expected. Confirm the injected event\nand record its full message id on the next turn after Relay has delivered it.\nDo not create a comment, review, or rerun without authorization. A successful\nsubscribe response alone does not prove end-to-end delivery.\n\n## 7. Coexist with a REST-polling MCP\n\nDo not disable an existing polling consumer. Desktop injection acknowledges\nonly this registered agent's delivery queue and does not advance a separate\nworkspace consumer's cursor. A polling MCP should use its own identity/cursor,\nnot this session agent's `/v1/deliveries` token.\n\nInjected text contains both the full Relaycast message id and a short `ref`.\nWhen polling and injection can surface the same workspace message, deduplicate\non the full message id before acting. During verification, leave the poller\nrunning and observe the test message there. Then end the current turn so Relay\ncan inject it, and on the next turn confirm the same full id arrived while the\nagent acted only once.\n\n## 8. Final verification and report\n\nRead status again:\n\n```sh\ncurl -sS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'\n```\n\nRequire all three defaults before declaring setup complete. Set\n`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the\nexisting mode the human kept); the check refuses to guess it:\n\n```sh\n: \"${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}\"\ncurl -fsS --max-time 60 --unix-socket \"$relay_socket\" http://relay/setup/status | \\\n  jq -e --arg mode \"$relay_sharing_mode\" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'\n```\n\nReport the exact version, `signed_in`, signed-in workspace id and name, sharing\nmode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,\nuploader health, session address, direct-delivery state, webhook test marker,\nsubscriptions, real GitHub event evidence, and polling-coexistence result.\nSeparate verified facts from steps that still require a human or external\nevent.\n\n## Recovery and undo\n\n- **Socket missing or slow:** check `systemctl --user status agent-relay.service`\n  on Linux or `open -a \"Agent Relay\"` on macOS. Confirm the pointer names a\n  socket. Never delete a live socket; restart the owning service/app. A reply\n  that takes up to about 30 seconds is the known latency in section 1\n  (relay-desktop#333), not a fault: allow 60 seconds and retry once.\n- **`not_a_relay_session`:** the command is not a descendant of a supported\n  live Codex/Claude session, or the session id/process start no longer matches.\n  Run it through this agent's shell tool. In tmux, confirm the agent process and\n  shell share the pane's process tree.\n- **Sign-in blocked by a legacy uploader** (`sign_in: error`, message \"An older\n  managed history uploader is active. Stop it explicitly before enabling this\n  probe.\"): the probe counts any of these legacy `ai-hist push` registrations as\n  active, even when idle: the file\n  `~/Library/LaunchAgents/com.ai-hist.push.plist` (even if unloaded), a loaded\n  launchd label `com.ai-hist.push`, or a crontab line containing\n  `# ai-hist push (managed)`. Check each, then with the human's approval unload\n  and move aside (do not delete) what exists. Create the backup directory first,\n  use a unique no-clobber destination, and confirm the move before retrying:\n\n  ```sh\n  # bootout exits non-zero when the label was never loaded; that is fine, so\n  # judge success by whether the label is still loaded, not by its exit code.\n  launchctl bootout \"gui/$(id -u)/com.ai-hist.push\" 2>/dev/null || true\n  if launchctl list | awk '{print $NF}' | grep -qx com.ai-hist.push; then\n    echo 'com.ai-hist.push is still loaded; do not retry sign-in' >&2\n    exit 1\n  fi\n  plist=\"$HOME/Library/LaunchAgents/com.ai-hist.push.plist\"\n  if test -e \"$plist\"; then\n    backup_dir=\"$HOME/.agentworkforce/backup\"\n    mkdir -p \"$backup_dir\"\n    mv -n \"$plist\" \"$backup_dir/com.ai-hist.push.plist.bak-$(date +%Y%m%d%H%M%S)\"\n    test ! -e \"$plist\" || { echo 'plist was not moved; do not retry sign-in' >&2; exit 1; }\n  fi\n  ```\n\n  If instead the marked cron line is the cause, back up the full crontab first\n  and remove only that line, so the change can be reversed with\n  `crontab <backup-file>`:\n\n  ```sh\n  mkdir -p \"$HOME/.agentworkforce/backup\"\n  cron_backup=\"$HOME/.agentworkforce/backup/crontab.bak-$(date +%Y%m%d%H%M%S)\"\n  crontab -l > \"$cron_backup\" && test -s \"$cron_backup\" || { echo 'crontab backup failed; do not edit it' >&2; exit 1; }\n  grep -vF '# ai-hist push (managed)' \"$cron_backup\" | crontab -\n  ! crontab -l | grep -qF '# ai-hist push (managed)' || { echo 'cron line still present; do not retry sign-in' >&2; exit 1; }\n  ```\n\n  Leave `com.ai-hist.sync` alone; it is not checked. Then re-run\n  `/setup/sign-in` with the same payload.\n- **`not_signed_in`:** run `/setup/sign-in`; do not paste tokens into the\n  request. Restart after `expired` or `denied` to obtain a new code.\n- **Older schedules could not be inspected:** inspect the user's legacy cron,\n  launchd, or user-service upload schedules first. Only after that inspection,\n  retry `/setup/sign-in` with the original payload plus\n  `\"acknowledge_uninspected_schedules\":true`. This flag records a completed\n  safety check; never send it merely to silence an error.\n- **`not_allowed` from `/register`:** enable the app's self-registration\n  setting. Do not bypass it with workspace credentials.\n- **Managed Claude policy:** if direct delivery reports `managed_policy`, the\n  organization controls `crossSessionInbound`; report the policy block rather\n  than modifying managed settings.\n- **Undo registration:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/register | jq`.\n- **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,\n  `relay_req`, and `pr_resources` defined, remove every subscription the\n  session holds for the pull request, in whichever form it was made. On macOS\n  `relay_req` uses the probe, and a Codex session without one stops instead of\n  sending a `curl` request that cannot be identified:\n\n  ```sh\n  held=$(pr_resources) || exit 1\n  printf '%s\\n' \"$held\" | while IFS= read -r resource; do\n    test -n \"$resource\" || continue\n    relay_req DELETE /integrations/subscribe \\\n      \"$(jq -nc --arg resource \"$resource\" '{provider:\"github\",resource:$resource}')\" | jq\n  done\n  relay_req GET /setup/status | jq -c '.data.integrations'\n  ```\n\n  Require the final list to hold none of that pull request's resources.\n- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X DELETE http://relay/webhooks | jq`.\n- **Undo direct delivery:** POST `{\"enabled\":false}` to\n  `/setup/direct-delivery`. On Claude this restores the local opt-out; managed\n  organization policy still wins.\n- **Undo sharing:** POST the human's prior mode (`selected`, `new`, or `all`) to\n  `/setup/sharing`. Ask before changing it when the earlier value is unknown.\n- **Auto-activate accidentally enabled:** POST `{\"enabled\":false}` to\n  `/setup/auto-activate`. This does not remove existing registrations.\n- **Uninstall:** stop/disable the user service before removing the Linux\n  package, or quit the Mac app before removing it. Do not delete app data or\n  revoke webhooks unless the human explicitly asks for data removal.\n",
   "setting-up-agent-relay-sessions": "# Set Up Agent Relay Session Handoff\n\nDrive the whole onboarding from this agent's own shell and MCP tools. Do **not**\nhand the person the six-step Markdown guide and ask them to click through the\napp and the dashboard.\n\nPrefer setting this up with the Agent Relay agent at\n<https://arelay.to/agent-relay>, which checks your current state and confirms\neach step. Fetch its instructions with\n`curl -sSL -H 'Accept: text/markdown' https://arelay.to/agent-relay`.\n\nThe finished state is:\n\n- the desktop app is installed, signed in to the **intended workspace**, the\n  uploader is healthy, and this session is registered with direct delivery on;\n- the **agent-sessions cloud MCP** is installed in this project and loaded by\n  this session, so the handoff tools (`list_relay_agents`, `send_relay_message`,\n  `read_relay_conversation`, `check_relay_inbox`, `get_shared_session`,\n  `get_shared_session_context`, `search_shared_sessions`) are available;\n- a live round trip is proven when a teammate is online: this agent messages the\n  teammate's agent, **reads the teammate's real session back** with\n  `get_shared_session_context`, and the teammate reads this session and replies.\n  When no teammate is online yet, the fallback is the roster plus this person's\n  own uploaded session reading back cleanly — reported as self-verified, not as a\n  proven two-way handoff.\n\n## Requires\n\nThis skill builds on `setting-up-agent-relay-desktop` (verified install, sign-in,\nregistration, agent-led defaults). If that skill is **not installed** in this\nagent, stop, tell the person, and have them install the companions together,\nthen restart the agent. Do not improvise the install or sign-in from memory.\n\n- prpm: `npx prpm install collections/agent-relay-setup --as claude --global -y`\n- skills.sh: `npx skills add https://github.com/AgentWorkforce/skills --skill setting-up-agent-relay-desktop --skill setting-up-agent-relay-sessions`\n- Codex: do not use prpm's `--as codex` (it drops paragraphs and writes under `~/.agents/skills`, which Codex does not load as its global skill folder). Mirror both installed `SKILL.md` files into `~/.codex/skills/<name>/` with the loop in **Install this skill (and its dependency)** below.\n\n## The only human steps\n\nEverything else is automatable; be honest that these are not. **Ask for all of\nthem up front, before touching anything** — the token in particular is needed\nonly at section 3, but minting it and exporting it into the launching\nenvironment takes the person a few minutes, so have them start it while the\ndesktop install and sign-in run:\n\n1. **Approve one Google device-login link** — only when no reusable `agent-relay`\n   CLI/desktop login exists. A reused login needs zero clicks.\n2. **Provide one Bearer token** minted in the dashboard's **\"Connect your agent\"**\n   card. No setup route returns this token by design. **Do not have the person\n   paste it into this conversation** — the uploader shares this session's prompts\n   with teammates, so a pasted secret would become teammate-readable. Instead the\n   person puts it into the **environment that launches their agent** (or an OS\n   keychain / a mode-0600 file) via a shell *they* run, and this agent references\n   it only by variable name — never by value. See **Token handling** below.\n3. **Same workspace, both sides.** The teammate (or workspace admin) must have\n   invited this person's email to the **shared** workspace — two agents can only\n   reach each other inside one workspace. Confirm the workspace id matches on\n   both machines; do not guess it.\n\nOne structural note so expectations are right: there is **no automatic ack** to\nthe sender when a handoff is picked up, and **no partial session sharing** — a\nsession is on-or-off on the relay. Confirm a handoff by activity, not a push.\n\n## How this composes with `setting-up-agent-relay-desktop`\n\nThis skill is a thin layer on a working desktop. The desktop skill owns install,\nsign-in, defaults and self-registration; this one owns only the agent-sessions\ncloud MCP and the live handoff. Section 2 checks the desktop prerequisite and,\nif it is not met, invokes `/setting-up-agent-relay-desktop` to completion and\nreturns here. Keep the `/setup/*` details in that one skill so a contract change\nupdates it once.\n\n## Install this skill (and its dependency) for Codex and Claude Code\n\nWhen the task includes installing this skill, install its canonical Claude\npackage **and** the desktop skill it depends on, then mirror both unchanged\n`SKILL.md` files where Codex loads global skills:\n\n```sh\nfor pkg in setting-up-agent-relay-sessions setting-up-agent-relay-desktop; do\n  npx prpm install \"@agent-relay/$pkg\" --as claude --global -y\n  codex_skill=\"$HOME/.codex/skills/$pkg\"\n  mkdir -p \"$codex_skill\"\n  install -m 0644 \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\n  cmp \"$HOME/.claude/skills/$pkg/SKILL.md\" \"$codex_skill/SKILL.md\"\ndone\n```\n\nWith skills.sh instead, use the command under **Requires**; it installs into each agent's skills folder directly, so the manual Codex mirror below is only for the prpm route.\n\nDo not use prpm's `--as codex` conversion for these packages: it writes under\n`~/.agents/skills`, which Codex does not load as its global skill folder, and it\ndrops explanatory paragraphs from the Markdown workflow. Confirm both final\npaths explicitly before continuing.\n\n## Why ordering matters\n\nMCPs load at agent **startup**. The agent-sessions MCP must be installed\n**before** the session that will use it starts. A session already running when\nthe MCP was added has no handoff tools and must be **restarted**. Install the\nMCP (section 3) before relying on the tools (sections 4–5); if this very session\npredates the MCP, say so and restart it rather than reporting missing tools as a\nfailure.\n\n## Token handling\n\nThe token must never land in the agent conversation, in a Relay message, in\nprocess argv, or in the repo. Three places leak it, and this skill avoids all\nthree:\n\n- **The chat** — this session is uploaded and teammate-readable, so a token\n  pasted to the agent leaks to the workspace. The person sets it themselves (see\n  below); the agent only ever sees the variable **name**.\n- **Process argv** — a token interpolated into `claude mcp add --header\n  \"... Bearer $TOKEN\"` is visible to `ps` and gets written literally into\n  `~/.claude.json`. Pass the unexpanded placeholder `${AGENT_RELAY_SESSIONS_TOKEN}`\n  instead; Claude Code expands `${VAR}` in MCP headers from the environment at\n  launch, so the stored config holds only a reference and argv holds only the\n  literal `${…}`. **This expansion exists only in Claude Code ≥ 2.1.119** — an\n  older client sends the placeholder literally and auth fails, so check the\n  version first (section 3) and update Claude rather than inlining the token.\n- **The launching environment** — both CLIs read the token from an environment\n  variable (`${VAR}` for Claude, `--bearer-token-env-var` for Codex), so the\n  variable must exist in the environment that **launches the agent**, not in a\n  transient shell-tool subprocess (which cannot alter its parent or a later\n  process).\n\nUse the single variable name `AGENT_RELAY_SESSIONS_TOKEN` throughout. Keep the\none-time entry separate from durable supply:\n\n- **One-time, into the current shell** (non-echoing, run by the person, never\n  the agent): `read -rs AGENT_RELAY_SESSIONS_TOKEN && export AGENT_RELAY_SESSIONS_TOKEN`,\n  then launch the agent from *that* shell. Do **not** add this `read` to a shell\n  profile — every shell that sources the profile would block waiting for input.\n- **Durable across restarts:** store the token in the OS keychain or a mode-0600\n  file, and have the launcher export it **non-interactively**, e.g.\n  `export AGENT_RELAY_SESSIONS_TOKEN=\"$(security find-generic-password -s agent-relay-sessions -w)\"`\n  (macOS keychain) or from a 0600 file. Put that line in a dedicated launcher the\n  person starts the agent from — not an interactive prompt in the profile.\n\nThe agent never prints the value; verify presence only with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"`.\n\n## 0. Preflight: collect the human inputs first\n\nBefore section 1, tell the person what they need and ask for it in one message:\n\n1. the **shared workspace id** (or the teammate/admin who invited them);\n2. a **Bearer token** minted in the dashboard's \"Connect your agent\" card for\n   that workspace, stored by *them* as `AGENT_RELAY_SESSIONS_TOKEN` in the\n   environment that launches their agent (see **Token handling** — never pasted\n   into this chat);\n3. the **teammate's relay address** for the round trip, if one will be online.\n\nBefore sending that message, check what this machine already has. If an Agent\nRelay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not\nthe `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only\nchecks. Without one, section 2 reads the signed-in workspace from\n`/setup/status` instead. The CLI is optional for this skill: detect it as\nbelow, which skips the Desktop launcher that `command -v agent-relay` finds on\na `.deb` install, and do not install or upgrade it just for these checks.\n\n```sh\nrelay_cli=$(command -v agent-relay || true)\ncase \"$relay_cli\" in ''|/usr/bin/agent-relay) relay_cli= ;; esac\nif test -n \"$relay_cli\"; then\n  \"$relay_cli\" --version\n  \"$relay_cli\" cloud whoami       # signed in, and as whom\n  \"$relay_cli\" workspace active   # the active Cloud workspace (keys stay masked)\n  \"$relay_cli\" cloud workspaces   # every workspace this login can use, with ids\n  \"$relay_cli\" status             # workspace, cloud login and local broker\nfi\n```\n\nIf the active workspace is already the shared one, confirm it with the person\ninstead of asking them to look it up. Never switch to or create another\nworkspace unless they explicitly ask.\n\nCheck presence without printing the value:\n\n```sh\ntest -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\" && echo token=present || echo token=missing\n```\n\nA missing token does **not** block sections 1–3: the MCP config stores only a\n`${AGENT_RELAY_SESSIONS_TOKEN}` reference, never the value, so it can be added\nnow. Do the desktop work and add the MCP, then have the person restart the agent\n**once**, from an environment that exports the token, so that single restart both\nloads the MCP and supplies the credential. Sections 4–5 are gated on that\nrestart. If the person would rather not defer, they can export the token and\nrestart first, which then costs a second restart only if the MCP was added after.\n\n## 1. Confirm the host and this session\n\nRun every command from this agent's own shell tool, and only from a **genuine\ninteractive** Claude Code or Codex session. The app identifies the caller from\nkernel credentials and resolves its process ancestry against discovered live\nsessions, so a command from an unrelated terminal — or from a non-interactive\n`codex exec` / `claude -p` run — is rejected with `not_a_relay_session`. (This\nis verified: a plain SSH shell and a `codex exec` invocation are both refused;\nan interactive session is admitted.)\n\n```sh\nuname -s; uname -m\ntest -n \"${SSH_CONNECTION:-}\" && printf 'transport=ssh\\n' || true\ntest -n \"${TMUX:-}\" && printf 'session=tmux\\n' || true\n```\n\nDefine the request helper once per shell. It finds the private setup socket\nwithout printing private files and uses the desktop's `agent-relay-probe` on\nmacOS (the system `curl` hides a Codex session's identity there and is refused\n`not_a_relay_session`), `curl` elsewhere, and stops with a message for a macOS\nCodex session that has no probe:\n\n```sh\npointer=\"$HOME/.agentworkforce/desktop/relay-socket\"\nif test -r \"$pointer\"; then relay_socket=$(sed -n '1p' \"$pointer\"); fi\nif test -n \"${relay_socket:-}\" && ! test -S \"$relay_socket\"; then unset relay_socket; fi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Linux; then\n  for c in \"${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock\" \"/run/user/$(id -u)/agent-relay/relay.sock\"; do\n    if test -S \"$c\"; then relay_socket=$c; break; fi\n  done\nfi\nif test -z \"${relay_socket:-}\" && test \"$(uname -s)\" = Darwin; then   # pointer file missing: use the app's own socket\n  c=\"$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock\"\n  if test -S \"$c\"; then relay_socket=$c; fi\nfi\nrelay_probe=\nfor c in \"$HOME/.local/bin/agent-relay-probe\" \\\n         /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \\\n         \"/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe\"; do\n  if test -x \"$c\"; then relay_probe=$c; break; fi\ndone\nif test -z \"$relay_probe\" && test -d \"$HOME/.local/lib/agent-relay\"; then   # per-user tarball\n  relay_probe=$(find \"$HOME/.local/lib/agent-relay\" -type f -perm -u+x \\\n    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)\nfi\n# relay_req METHOD PATH [JSON-BODY]\nrelay_req() {\n  if ! test -S \"${relay_socket:-/nonexistent}\"; then\n    echo 'No Agent Relay socket found; start Agent Relay (the desktop) and retry.' >&2\n    return 1\n  fi\n  if test \"$(uname -s)\" = Darwin && test -n \"$relay_probe\"; then\n    printf '%s' \"${3:-}\" | \"$relay_probe\" relay socket-request \\\n      --socket \"$relay_socket\" --method \"$1\" --path \"$2\"\n  elif test \"$(uname -s)\" = Darwin && test -n \"${CODEX_THREAD_ID:-}\"; then\n    echo 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.' >&2\n    return 1\n  elif test -n \"${3:-}\"; then\n    # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename\n    printf '%s' \"$3\" | curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \\\n      -H 'Content-Type: application/json' --data-binary @- \"http://relay$2\"\n  else\n    curl -sS --max-time 60 --unix-socket \"$relay_socket\" -X \"$1\" \"http://relay$2\"\n  fi\n}\n```\n\n**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can\ntake about 30 seconds on a busy Desktop (tracked in\nAgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add\n`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a\nfailure. The probe's `relay socket-request` can give up sooner with \"Probe\ncould not finish. Check your connection and run setup again\"; on these paths\nthat is the same latency, not a setup problem. Retry once before reporting a\nblocker, and do not rerun desktop setup because of it.\n\n## 2. Make sure the desktop is set up first\n\nSession handoff needs a signed-in, healthy desktop underneath it. If the socket\nis missing, or `/setup/status` returns `404`, or sign-in/uploader/registration\nare not in the finished state below, **invoke the `setting-up-agent-relay-desktop`\nskill** (`/setting-up-agent-relay-desktop`; if it is not installed, see **Requires**), let it run to completion, and then\nreturn to section 2's verification. Do not re-implement its install, sign-in, or\n`/setup/*` steps here — that skill is the single source of truth for them, and\nthis skill resumes once it reports a registered, signed-in session.\n\nVerify the desktop state this skill depends on:\n\n```sh\nrelay_req GET /setup/status | jq '{\n  version: .data.version,\n  sign_in: .data.sign_in,\n  workspace: .data.workspace,\n  sharing_mode: .data.sharing_mode,\n  uploader: .data.uploader,\n  direct_delivery: .data.direct_delivery,\n  session: .data.session,\n  defaults_error: .data.defaults_error\n}'\n```\n\nRequire all of these before continuing, and stop with a clear message if any\nfails. `/setup/status` reports sign-in as the string `sign_in` (match the desktop\nskill), and the flag that actually governs whether **this** session's handoff\nreplies arrive live is the session-level `session.direct_delivery`, not the\ntop-level default — require both:\n\n```sh\nrelay_req GET /setup/status | jq -e '\n  .ok\n  and .data.sign_in == \"signed_in\"\n  and (.data.workspace.id | type == \"string\" and length > 0)\n  and .data.uploader.healthy == true\n  and .data.direct_delivery == true\n  and (.data.session.id | type == \"string\" and length > 0)\n  and .data.session.registered == true\n  and .data.session.direct_delivery == true'\n```\n\nConfirm `workspace.id` is the **shared** workspace both sides agreed on. A\nhealthy uploader is the one non-obvious prerequisite: for a teammate's agent to\nread **this** person's session, this machine must have uploaded it. If\n`uploader.healthy` is false (paused, or a failed cycle), fix it before promising\nanyone can read this session — this is the single most common reason a live\nhandoff silently fails.\n\n`sharing_mode` decides which sessions upload at all, and a healthy uploader\ndoes not prove that **this** session is among them. `all` includes it. `new`\nincludes sessions that started after `new` was enabled, so a session that was\nalready running when the desktop was set up may not be uploaded. Under\n`selected`, only the sessions the person chose upload. Unless the mode is\n`all`, tell the person that this session may not be shared yet, and ask them to\nselect it in the app or to continue from a new session; do not change the\nsharing mode or select sessions on their behalf. Section 5's round trip is the\nproof: if the teammate cannot read this session there, this is the first\nthing to check.\n\n## 3. Install the agent-sessions cloud MCP (before the session uses it)\n\nCheck whether the token is present in the environment **without printing it**\n(see **Token handling**). It is not required to *add* the MCP, since only a\nreference is stored, but it is required for the tools to authenticate after the\nrestart. If it is missing, add the MCP anyway, tell the person plainly that the\ntools will fail auth until they restart the agent from an environment that\nexports `AGENT_RELAY_SESSIONS_TOKEN`, and do not report setup complete:\n\n```sh\nif ! test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"; then\n  echo 'AGENT_RELAY_SESSIONS_TOKEN is not set here; the MCP will be added by reference, but the agent must be restarted from an environment that exports it.' >&2\nfi\n```\n\nDetect which agent CLI this session runs and install accordingly.\n\nClaude Code — pass the **unexpanded** placeholder so the token stays out of argv\nand out of `~/.claude.json`; Claude expands `${VAR}` in MCP headers from the\nenvironment at launch. This expansion requires **Claude Code ≥ 2.1.119**, so\nverify the version first and update rather than inlining the token on an older\nclient. Single-quote the header so the shell does not expand it here. Default\nscope is `local` (this project only), which is what you want:\n\n```sh\nclaude_ver=$(claude --version 2>/dev/null | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1)\nif test -z \"$claude_ver\" || test \"$(printf '%s\\n2.1.119\\n' \"$claude_ver\" | sort -V | head -1)\" != 2.1.119; then\n  echo \"Claude Code $claude_ver does not expand \\${VAR} in MCP headers (need >= 2.1.119); update Claude Code before adding this server.\" >&2\n  exit 1\nfi\nclaude mcp add --transport http agent-relay-sessions \\\n  https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --header 'Authorization: Bearer ${AGENT_RELAY_SESSIONS_TOKEN}'\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nCodex — `codex mcp add` records the **variable name**, not the value, and writes\nto user-level `~/.codex/config.toml`, so the server is enabled for **all** Codex\nprojects (Codex has no project-scoped MCP). Confirm the person is OK with\nuser-wide access before adding it:\n\n```sh\ncodex mcp add agent-relay-sessions \\\n  --url https://agentrelay.com/cloud/api/v1/mcp/shared-sessions \\\n  --bearer-token-env-var AGENT_RELAY_SESSIONS_TOKEN\ncodex mcp list | grep -F agent-relay-sessions\n```\n\nBecause MCPs load at startup, the running session must be **restarted** to pick\nup the server — and because both CLIs read the token from the environment at\nlaunch, the restarted process must **inherit** `AGENT_RELAY_SESSIONS_TOKEN`.\nThat is why the variable belongs in the shell profile / launcher, not a transient\nshell-tool subprocess: an `export` in this agent's shell tool cannot reach the\nparent or a freshly launched session. After the restart, re-verify presence with\n`test -n \"${AGENT_RELAY_SESSIONS_TOKEN:-}\"` before using the tools, and do not\nreport the tools as missing without first confirming the session started *after*\nthe MCP was added and with the variable set.\n\n## 4. Confirm the handoff tools loaded\n\nIn the session that started after the MCP was added, confirm the tools are\npresent before using them. List this session's MCP tools and check for the\nagent-sessions set; the authoritative check is that the tools actually appear to\nthis agent:\n\n```sh\n# Claude Code: the tools surface as mcp__agent-relay-sessions__*\nclaude mcp list | grep -F agent-relay-sessions\n```\n\nThen call `list_relay_agents` through the MCP (an MCP tool call, not a shell\ncommand). A successful call that returns the workspace roster proves the MCP is\nloaded, the token is valid, and this session can see the shared workspace. If\nthe call errors with auth, the token is wrong or for another workspace — have\nthe person re-mint it from the correct workspace's dashboard.\n\n## 5. Prove one live round trip\n\nThe real proof is agent-to-agent, so it needs a counterpart. Pick the path that\nmatches what is available:\n\n**A teammate's agent is online (full round trip).** Ask the person for the\nteammate's relay address (e.g. `@manav`), then:\n\n1. `list_relay_agents` — confirm the teammate's address is listed.\n2. **Prove the reverse read path first:** call `get_shared_session_context` on\n   the teammate's session and confirm it returns their **real** content (prompts/\n   events + a dashboard citation link). If it errors or is empty, their uploader\n   is unhealthy — stop and have them fix it; do not declare GREEN, because this\n   side cannot actually read their work yet.\n3. `send_relay_message` — send a short, uniquely-marked message to that address.\n4. The teammate's agent reads this session with `get_shared_session_context` and\n   continues; have them reply through the relay.\n5. GREEN requires **both directions**: this agent read the teammate's real\n   content (step 2) **and** the teammate's reply lands here. There is no\n   automatic ack — confirm by the reply/activity, not a push. Because Relay\n   injects an inbound message only when the session is idle between turns, **end\n   the turn** after sending and confirm the reply on the next turn; do not sleep\n   or poll inside one turn.\n\n**No teammate online yet (self-verify the read path).** Prove the machinery\nwithout a second person:\n\n1. `list_relay_agents` returns the roster — MCP + token + workspace are good.\n2. `search_shared_sessions` / `get_shared_session_context` return this person's\n   **own** recently uploaded session (real prompts/events plus a dashboard\n   citation link) — the uploader→read path works.\n3. Record that the two-party round trip still needs the teammate online, and\n   name it as the remaining step rather than claiming the handoff is proven.\n   Setup is not complete until the full round trip succeeds.\n\nNever paste the Bearer token or any session token into a `send_relay_message`\nbody or any artifact.\n\n## 6. Report\n\nSeparate verified facts from what still needs a human or a second machine:\n\n- app version, `signed_in`, the signed-in **workspace id and name**;\n- uploader `healthy`, this session's `agent@machine` address, direct delivery on;\n- agent-sessions MCP installed and its tools confirmed loaded in this session;\n- `list_relay_agents` roster seen; and either the full round-trip evidence (the\n  teammate's real content + reply) or the self-verified read path plus the named\n  remaining step (teammate online).\n\nDo not call the setup complete on a 2xx from `claude mcp add` alone, and do not\ncount a roster listing as a proven handoff.\n\n## Recovery\n\n- **`not_a_relay_session` from `/setup/*`:** the caller is not inside a discovered\n  interactive session. Run it from this agent's own shell inside an **interactive**\n  Claude Code or Codex session — a non-interactive `codex exec` or `claude -p` run\n  is not admitted, and neither is an unrelated terminal. In tmux/SSH, confirm the\n  agent process and shell share the pane's process tree.\n- **No handoff tools in the session:** the MCP was added after the session\n  started, or at the wrong scope. Reinstall at project scope (section 3) and\n  **restart** the session; MCPs load only at startup.\n- **`list_relay_agents` auth error:** the token is wrong, expired, or from a\n  different workspace. Because the MCP config stores only a **reference** to\n  `AGENT_RELAY_SESSIONS_TOKEN`, fixing it means updating the **value in the\n  launch environment** (keychain / 0600 file) and **restarting** the agent so it\n  re-reads it — re-running `claude mcp add` / `codex mcp add` alone changes\n  nothing. Re-mint from the intended workspace's \"Connect your agent\" card if the\n  token itself is bad. On Claude, also confirm the client is ≥ 2.1.119 (older\n  clients send the `${VAR}` placeholder literally).\n- **Teammate's address missing from the roster:** they are not on the **same**\n  workspace, or their session is not on the relay. Have them register their\n  session and confirm the shared workspace id.\n- **Can't read the teammate's session:** their **uploader** is not healthy\n  (paused or a failed cycle). Have them check `/setup/status` shows\n  `uploader.healthy == true`, not \"Sync paused/offline\".\n- **Message arrives held, not live:** direct delivery is off for the recipient —\n  POST `{\"enabled\":true}` to `/setup/direct-delivery` on their machine (Codex\n  delivers directly by default). A managed Claude policy can block this; report\n  it rather than editing managed settings.\n- **Remove the MCP:** `claude mcp remove agent-relay-sessions` /\n  `codex mcp remove agent-relay-sessions`. This removes only the handoff tools;\n  it does not sign the desktop out or stop uploads.\n\n## Relationship to the other skills\n\n- **`setting-up-agent-relay-desktop`** — the layer below this one: install,\n  sign-in, agent-led defaults, self-registration. Use it when section 2 is not\n  yet satisfied.\n- **`relay-connect`** — a lighter, account-free, time-boxed way for two agents to\n  share one session via a hand-over link. Prefer it for an ad-hoc pairing;\n  prefer this skill for durable teammate-to-teammate handoff inside a shared\n  workspace.\n",
-  "setting-up-agent-relay-flows": "# Set Up Agent Relay Flows\n\nDrive the setup through the documented Cloud APIs and the official CLI. Do not\nuse computer use, browser automation, or the dashboard UI. The human approves\nsign-in, tool consent, and provider logins on their own approval pages; open\nthose links with the OS URL opener (or give them the link), then verify by\npolling the API, never by inspecting the browser.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix; the site is `https://agentrelay.com`. The flow\ncatalog is the one exception: it is a site API, served from the site origin\nwithout `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a\nguide names a different site and Cloud base (for example a local development\nstack), use those exact origins throughout, including for the catalog, the\nCLI's `--api-url` and the dashboard links, and never fall back to production.\nFlows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.\n\n## Requires\n\nA signed-in Cloud session: an access token and the `user.id` and\n`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`\nfirst, and send `Authorization: Bearer <access_token>` on every request below.\n\n## API map\n\n- Flow catalog (site origin, not under `/cloud`):\n  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.\n- Tool consent links: `POST /api/v1/integrations/connect-link`; poll\n  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.\n- Coding-agent credentials: the official CLI's `cloud connect` (section 3);\n  `GET /api/v1/cloud-agents` inspects existing connections.\n- Activation: `POST /api/v1/flows/deploy` with the body in section 4.\n- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`\n  reports whether it is available.\n- Verification: `GET /api/v1/flows/listeners/<agentId>`.\n\n## 1. Prebuilt or custom?\n\nAsk the human first, unless their request already says: a **prebuilt** flow\nfrom the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**\nflow of their own? In an agent-driven signup, ask through that guide's\nweb-input protocol on the signup page, not in chat.\n\n- Prebuilt: continue with section 2.\n- Custom: follow **Custom flow: deploy journey** below. A custom flow is\n  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and\n  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is\n  no separate custom API.\n\n## 2. Choose the flow and repository\n\nAsk the human for missing product choices: repository, desired\nworkflow/trigger, and approver. In an agent-driven signup, ask through that\nguide's web-input protocol on the signup page, not in chat. Ask for the approver's\nGitHub username in plain language (for example, \"octocat\" or \"@octocat\"),\nnot an internal provider-address format or their Google email. Normalize the\nanswer to github:@handle when constructing the deploy API request. Human-gate\nreplies are matched to that provider identity. Infer choices from the user's request and current\nrepository where clear.\nDo not invent a repository or enable automation on an unrelated project.\n\nGET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.\nGET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's\nkind before doing anything executable: only an entry with kind: flow (or a\nlegacy entry with kind omitted) is deployable through the direct-source API\nbelow. An entry with kind: extension is discoverable metadata, not a standalone\nlistener. Do not download or deploy its source, even when it declares trigger\nand input fields. Inspect baseFlowId and extension.activation instead. If the\nextension is blocked, report the unmet dependencies and that it can only be\nadded to its base flow after a supported extension activation path is available;\nnever substitute a standalone flow deployment.\n\nFor a deployable flow, use the catalog's\nsupportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and\ninputs.allowedAgents. Name a model per harness in inputs.models when the house\ndefault is wrong (for example {\"claude\": \"claude-sonnet-4\"}); omit it to fund\nthe house default for each declared agent. Download source.rawUrl, verify its bytes against\nsource.sha256, and use that source text unchanged for a recommended flow.\nThe source is TypeScript, not the source URL. Do not guess a template or hash.\n\n## Custom flow: deploy journey\n\nThere is no journey API. A `journey_id` (for example in a\n`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it\nthrough unchanged where you received it, and never call an endpoint with it or\nwait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`\nas a prebuilt one; only where the source comes from differs.\n\n1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,\n   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that\n   skill for the flow's shape and checks; Flows are always v2. Cloud's\n   prompt generator is an optional shortcut: use it only when\n   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it\n   reports unavailable, refuses your session (403 `session_required`), or\n   fails, author with `writing-relayflows` instead; do not retry into it.\n2. Choose its repository, trigger and approver as in section 2.\n3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the\n   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent\n   only when the prompt generator produced one. `base` and `extensions` are\n   optional and only for a flow that names them.\n\nThe human-only steps are the same for both paths: Google sign-in and device\napproval, GitHub and trigger-app OAuth including the repository grants,\nmodel-provider login when section 3 calls for one (not for an ordinary first\nactivation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.\n\n## 3. Connect the required tools and coding agents\n\nUse bearer-authenticated POST /api/v1/integrations/connect-link:\n\n```json\n{\"provider\":\"github\",\"workspaceId\":\"<currentWorkspace.id>\"}\n```\n\nOpen the returned connectUrl for the user to approve. Keep token/sessionToken\nprivate. Connect only the repository and tools the chosen flow requires.\nFor GitHub the user must grant repository access. Repeat with the chosen trigger\nprovider if different. Reuse existing ready connections rather than relinking.\nCheck GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status\nuntil oauth.connected is true (poll with backoff and a bounded timeout); a\nreturned connect link or a closed popup alone does not prove the connection.\nFor the GitHub-triggered Software Garden flow, activation separately checks\nthat the connected GitHub App covers the selected repository. Its trigger\ndoes not require background data indexing, so do not block solely because\nthe broader status.ready is false from queued syncs.\nIf a different flow declares Relayfile data that requires synced records,\nverify that readiness separately before activating it.\n\nDo not connect a Claude or Codex subscription yet. The first three runs use\nCloud's own model key, so no provider login is needed to activate. If the chosen\nflow declares more than one coding agent in inputs.agents, included Cloud runs\ncan fund only one of them per run — connect your own subscription for at least\none declared agent before activating a multi-agent flow. After the included\nruns, activation and launches will ask for your own subscription; only then use\nthe official Relay CLI with the private credential environment from\n`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:\n\nThis promotion depends on Cloud's internal house-key proxy and account\nenrollment. If local activation returns flow_credentials_unavailable or\nflow_model_not_connected before the three promotional runs, treat it as an\ninternal configuration or eligibility issue. Do not ask the user to connect\nClaude/Codex, provide an API key, or choose an inactive draft as a workaround.\nReport the blocker (in a signup, through its Progress API) and have an internal developer\nverify the proxy, promotion flag, provider readiness, and enrollment. Never\ncopy a house key into the agent environment or expose it in this guide.\n\n```sh\nnpx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'\n```\n\nUse anthropic for Claude or openai for Codex, according to the selected flow.\nThe command drives provider login; open its authorization URL for the user,\nand keep the process alive until it confirms the credential is connected.\nGoogle approval does not grant GitHub or model-provider access: those services\nmay require their own consent. Never fabricate credentials or claim consent\nhappened. GET /api/v1/cloud-agents lets you inspect the account's credential\nstate without reconnecting.\n\n## 4. Activate through the same API as web onboarding\n\nPOST /api/v1/flows/deploy with Content-Type: application/json and the bearer\nsession. The token must be the device-flow session from\n`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with\n`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the\nbrowser onboarding handoff: source is TypeScript text, repository is singular,\nand sources contains provider/settings objects. The catalog supplies the source\nreference and defaults; it is not itself a deploy request. The current endpoint\ndoes not accept a flowId/repositories-only catalog activation request or fetch\nthe source for you. For multiple repositories, submit one deployment per\nrepository with a distinct name and handoffId.\n\nFor the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the\nworkspace, verified source, repository, GitHub approver and a new UUID:\n\n```json\n{\n  \"workspaceId\": \"<currentWorkspace.id>\",\n  \"name\": \"Software Garden\",\n  \"workflow\": \"software-factory\",\n  \"source\": \"<verified TypeScript source text>\",\n  \"handoffId\": \"<one UUID generated for this setup>\",\n  \"inputs\": {\"approver\": \"github:@octocat\", \"agents\": [\"claude\"]},\n  \"mode\": \"activate\",\n  \"repository\": {\"owner\": \"acme\", \"name\": \"api\"},\n  \"sources\": [{\"provider\": \"github\", \"settings\": {\"repository\": \"acme/api\"}}]\n}\n```\n\nFor another deployable kind: flow catalog entry use its id as workflow, allowed agents, and\ndefaultTrigger for sources, then apply the user's trigger settings. Scope a\nGitHub issue trigger with settings.repository set to the chosen owner/name;\nfor GitLab use settings.project. Cloud does not derive this filter from the\ndeployment repository. An empty filter can trigger on other repositories in\nthe workspace. Only use a different trigger scope when explicitly requested.\nGive each repository its own trigger filter for multi-repository setup. Do not send\nthe example acme repository or octocat approver unchanged. The workflow field\nis a label, not a source lookup; keep the verified source in the request.\nFor GitLab set repository.host to gitlab and use the namespace path\nas owner. Reuse the handoffId on retry. Before retrying an ambiguous network\nfailure, GET /api/v1/flows/listeners and check whether the flow already exists;\ndo not create a new ID/name on every retry. Activation subscribes to matching\nfuture events and can run work; confirm the intended repository and trigger\nwith the user if they have not specified them.\n\nHTTP 201 must contain agentId and status: listening. A draft is not completion.\nFor a 409 workspace_mismatch, verify the active workspace; for connection\npreflight failures, fix the indicated connection before retrying. If the user\nwants to save incomplete work, use mode: draft explicitly and report that it\nis inactive. Never mask activation failures by silently falling back to draft.\n\n## 5. Verify\n\nGET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and\nverify its repository and sources match the request. Open\nhttps://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,\nworkspace, repository, trigger, and verified listening state. This proves\nactivation; only an actual completed run proves execution. Do not create a\nreal issue or launch paid work merely to make the onboarding check turn green.\nDelete temporary authentication files after the work is complete.\n\nThe desktop app is optional for Flows. If the user also wants local session\nsharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`\nwith the same account (an agent-driven signup can follow\nhttps://agentrelay.com/signup/agent/teams).\n",
+  "setting-up-agent-relay-flows": "# Set Up Agent Relay Flows\n\nDrive the setup through the documented Cloud APIs and the official CLI. Do not\nuse computer use, browser automation, or the dashboard UI. The human approves\nsign-in, tool consent, and provider logins on their own approval pages; open\nthose links with the OS URL opener (or give them the link), then verify by\npolling the API, never by inspecting the browser.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix; the site is `https://agentrelay.com`. The flow\ncatalog is the one exception: it is a site API, served from the site origin\nwithout `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a\nguide names a different site and Cloud base (for example a local development\nstack), use those exact origins throughout, including for the catalog, the\nCLI's `--api-url` and the dashboard links, and never fall back to production.\nFlows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.\n\n## Requires\n\nA signed-in Cloud session: an access token and the `user.id` and\n`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`\nfirst. Send `Authorization: Bearer <access_token>` only to the Cloud API\nendpoints below. Never send it to the site's flow catalog or to a catalog\n`source.rawUrl`; fetch those without credentials.\n\n## API map\n\n- Flow catalog (site origin, not under `/cloud`):\n  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.\n- Tool consent links: `POST /api/v1/integrations/connect-link`; poll\n  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.\n- Coding-agent credentials: the official CLI's `cloud connect` (section 3);\n  `GET /api/v1/cloud-agents` inspects existing connections.\n- Activation: `POST /api/v1/flows/deploy` with the body in section 4.\n- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`\n  reports whether it is available.\n- Verification: `GET /api/v1/flows/listeners/<agentId>`.\n\n## 1. Prebuilt or custom?\n\nAsk the human first, unless their request already says: a **prebuilt** flow\nfrom the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**\nflow of their own? In an agent-driven signup, ask through that guide's\nweb-input protocol on the signup page, not in chat.\n\n- Prebuilt: continue with section 2.\n- Custom: follow **Custom flow: deploy journey** below. A custom flow is\n  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and\n  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is\n  no separate custom API.\n\n## 2. Choose the flow and repository\n\nAsk the human for missing product choices: repository, desired\nworkflow/trigger, and approver. In an agent-driven signup, ask through that\nguide's web-input protocol on the signup page, not in chat. Ask for the approver's\nGitHub username in plain language (for example, \"octocat\" or \"@octocat\"),\nnot an internal provider-address format or their Google email. Normalize the\nanswer to github:@handle when constructing the deploy API request. Human-gate\nreplies are matched to that provider identity. Infer choices from the user's request and current\nrepository where clear.\nDo not invent a repository or enable automation on an unrelated project.\n\nGET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.\nGET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's\nkind before doing anything executable: only an entry with kind: flow (or a\nlegacy entry with kind omitted) is deployable through the direct-source API\nbelow. An entry with kind: extension is discoverable metadata, not a standalone\nlistener. Do not download or deploy its source, even when it declares trigger\nand input fields. Inspect baseFlowId and extension.activation instead. If the\nextension is blocked, report the unmet dependencies and that it can only be\nadded to its base flow after a supported extension activation path is available;\nnever substitute a standalone flow deployment.\n\nFor a deployable flow, use the catalog's\nsupportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and\ninputs.allowedAgents. Name a model per harness in inputs.models when the house\ndefault is wrong (for example {\"claude\": \"claude-sonnet-4\"}); omit it to fund\nthe house default for each declared agent. Download source.rawUrl, verify its bytes against\nsource.sha256, and use that source text unchanged for a recommended flow.\nThe source is TypeScript, not the source URL. Do not guess a template or hash.\n\n## Custom flow: deploy journey\n\nThere is no journey API. A `journey_id` (for example in a\n`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it\nthrough unchanged where you received it, and never call an endpoint with it or\nwait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`\nas a prebuilt one; only where the source comes from differs.\n\n1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,\n   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that\n   skill for the flow's shape and checks; Flows are always v2. Cloud's\n   prompt generator is an optional shortcut: use it only when\n   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it\n   reports unavailable, refuses your session (403 `session_required`), or\n   fails, author with `writing-relayflows` instead; do not retry into it.\n2. Choose its repository, trigger and approver as in section 2.\n3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the\n   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent\n   only when the prompt generator produced one. `base` and `extensions` are\n   optional and only for a flow that names them.\n\nThe human-only steps are the same for both paths: Google sign-in and device\napproval, GitHub and trigger-app OAuth including the repository grants,\nmodel-provider login when section 3 calls for one (not for an ordinary first\nactivation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.\n\n## 3. Connect the required tools and coding agents\n\nUse bearer-authenticated POST /api/v1/integrations/connect-link:\n\n```json\n{\"provider\":\"github\",\"workspaceId\":\"<currentWorkspace.id>\"}\n```\n\nOpen the returned connectUrl for the user to approve. Keep token/sessionToken\nprivate. Connect only the repository and tools the chosen flow requires.\nFor GitHub the user must grant repository access. Repeat with the chosen trigger\nprovider if different. Reuse existing ready connections rather than relinking.\nCheck GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status\nuntil oauth.connected is true (poll with backoff and a bounded timeout); a\nreturned connect link or a closed popup alone does not prove the connection.\nFor the GitHub-triggered Software Garden flow, activation separately checks\nthat the connected GitHub App covers the selected repository. Its trigger\ndoes not require background data indexing, so do not block solely because\nthe broader status.ready is false from queued syncs.\nIf a different flow declares Relayfile data that requires synced records,\nverify that readiness separately before activating it.\n\nDo not connect a Claude or Codex subscription yet. The first three runs use\nCloud's own model key, so no provider login is needed to activate. If the chosen\nflow declares more than one coding agent (the catalog's `inputs.defaults.agents`,\nwhich becomes `inputs.agents` in the deploy body), included Cloud runs\ncan fund only one of them per run — connect your own subscription for at least\none declared agent before activating a multi-agent flow. After the included\nruns, activation and launches will ask for your own subscription; only then use\nthe official Relay CLI with the private credential environment from\n`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:\n\nThis promotion depends on Cloud's internal house-key proxy and account\nenrollment. If local activation returns flow_credentials_unavailable or\nflow_model_not_connected before the three promotional runs, treat it as an\ninternal configuration or eligibility issue. Do not ask the user to connect\nClaude/Codex, provide an API key, or choose an inactive draft as a workaround.\nReport the blocker (in a signup, through its Progress API) and have an internal developer\nverify the proxy, promotion flag, provider readiness, and enrollment. Never\ncopy a house key into the agent environment or expose it in this guide.\n\n```sh\nnpx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'\n```\n\nUse anthropic for Claude or openai for Codex, according to the selected flow.\nThe command drives provider login; open its authorization URL for the user,\nand keep the process alive until it confirms the credential is connected.\nGoogle approval does not grant GitHub or model-provider access: those services\nmay require their own consent. Never fabricate credentials or claim consent\nhappened. GET /api/v1/cloud-agents lets you inspect the account's credential\nstate without reconnecting.\n\n## 4. Activate through the same API as web onboarding\n\nPOST /api/v1/flows/deploy with Content-Type: application/json and the bearer\nsession. The token must be the device-flow session from\n`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with\n`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the\nbrowser onboarding handoff: source is TypeScript text, repository is singular,\nand sources contains provider/settings objects. The catalog supplies the source\nreference and defaults; it is not itself a deploy request. The current endpoint\ndoes not accept a flowId/repositories-only catalog activation request or fetch\nthe source for you. For multiple repositories, submit one deployment per\nrepository with a distinct name and handoffId.\n\nFor the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the\nworkspace, verified source, repository, GitHub approver and a new UUID:\n\n```json\n{\n  \"workspaceId\": \"<currentWorkspace.id>\",\n  \"name\": \"Software Garden\",\n  \"workflow\": \"software-factory\",\n  \"source\": \"<verified TypeScript source text>\",\n  \"handoffId\": \"<one UUID generated for this setup>\",\n  \"inputs\": {\"approver\": \"github:@octocat\", \"agents\": [\"claude\"]},\n  \"mode\": \"activate\",\n  \"repository\": {\"owner\": \"acme\", \"name\": \"api\"},\n  \"sources\": [{\"provider\": \"github\", \"settings\": {\"repository\": \"acme/api\"}}]\n}\n```\n\nFor another deployable kind: flow catalog entry use its id as workflow, allowed agents, and\ndefaultTrigger for sources, then apply the user's trigger settings. Scope a\nGitHub issue trigger with settings.repository set to the chosen owner/name;\nfor GitLab use settings.project. Cloud does not derive this filter from the\ndeployment repository. An empty filter can trigger on other repositories in\nthe workspace. Only use a different trigger scope when explicitly requested.\nGive each repository its own trigger filter for multi-repository setup. Do not send\nthe example acme repository or octocat approver unchanged. The workflow field\nis a label, not a source lookup; keep the verified source in the request.\nFor GitLab set repository.host to gitlab and use the namespace path\nas owner. Reuse the handoffId on retry. Before retrying an ambiguous network\nfailure, GET /api/v1/flows/listeners and check whether the flow already exists;\ndo not create a new ID/name on every retry. Activation subscribes to matching\nfuture events and can run work; confirm the intended repository and trigger\nwith the user if they have not specified them.\n\nHTTP 201 must contain agentId and status: listening. A draft is not completion.\nFor a 409 workspace_mismatch, verify the active workspace; for connection\npreflight failures, fix the indicated connection before retrying. If the user\nwants to save incomplete work, use mode: draft explicitly and report that it\nis inactive. Never mask activation failures by silently falling back to draft.\n\n## 5. Verify\n\nGET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and\nverify its repository and sources match the request. Open\nhttps://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,\nworkspace, repository, trigger, and verified listening state. This proves\nactivation; only an actual completed run proves execution. Do not create a\nreal issue or launch paid work merely to make the onboarding check turn green.\nDelete temporary authentication files after the work is complete.\n\nThe desktop app is optional for Flows. If the user also wants local session\nsharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`\nwith the same account (an agent-driven signup can follow\nhttps://agentrelay.com/signup/agent/teams).\n",
   "writing-relayflows": "# Writing Relayflows\n\n## Overview\n\nRelayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real — a journal write that fails fails the step, with no silent fallback.\n\n**Name collision warning.** This repo also has skills for an older, unrelated engine that is *also* casually called \"Relayflow\" (singular) — `@relayflows/core`'s `WorkflowBuilder`, a chained builder (`workflow('name').pattern('dag').agent(...).step(...).run()`). That's `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`'s territory. This skill is the **v2** engine: `@relayflows/surface`'s `flow()` function and the YAML/JSON dialect compiled by `@relayflows/sdk`. If you see `.pattern(`, `.agent(` as a chained builder call, or `ctx.workflow.run()`, you're in the other engine — stop and use one of those skills instead.\n\n## When to use this skill\n\n- Writing a new `.flow.ts` or `.flow.yaml`/`.flow.json` for the `flows` CLI (package `@relayflows/sdk`, binary name `flows`).\n- Deciding whether a step needs `run` (shell), `llm` (bare model call), or `agent` (harnessed coding agent in a workspace).\n- Choosing a verification gate that will actually run — a wrong choice here compiles fine and fails at `flows run` time, not authoring time.\n- Wiring up `cli`/`model` for an `agent` or `llm` step, in either language.\n- Debugging a `REFUSED [...]` message from `flows check` or `flows run`.\n- Deciding between running a flow locally, deploying it to listen for tickets, or scheduling it on a cron.\n\n## The ladder\n\nThree step verbs, one per rung (`@relayflows/sdk`'s `StepType = 'deterministic' | 'llm' | 'agent'`):\n\n1. **`run` / `deterministic`** — a shell command. No model. Implicit gate is `exit_code == 0`.\n2. **`llm` / `llm`** — a bare model call. Prompt in, verified output out. No workspace, no tool use.\n3. **`agent` / `agent`** — a harnessed coding agent in a workspace. Returns `{ summary, artifacts }`, not raw text.\n\nPlus resident verbs that aren't ladder rungs: `human` (durable approval), `dispatch` (a direct child flow declared in `use`), and `done` (typed finish). `dispatch` executes in `2.0.35` and newer; see **Human approval and direct child flows**. The generated **helper** namespace (`f.slack`, `f.github`, `f.linear`, `f.notion`, `f.jira`, and 30+ others — see **Helpers**) and YAML `on`/triggers are separate surfaces.\n\nMost flows only need `run` and `llm`. Climb to `agent` once a step needs hands on a real workspace.\n\n## Two ways to author the same thing\n\n**YAML/JSON** is data: `flows check` or CI can validate it without running anything. **TypeScript** calls the same primitives imperatively as ordinary async code. Both compile to the same journal.\n\n### TypeScript\n\n```ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('hello', { budget: { wallclock: '10m' } }, async (f) => {\n  const greeting = await f.run('echo \"Hello from Relayflows\"');\n  console.log(greeting.trim());\n\n  const answer = await f.agent('greeter', {\n    task: 'Reply with one short hello sentence. Do not use tools or modify files.',\n    cli: 'claude',\n    model: 'claude-sonnet-4-6',\n  });\n  console.log(answer.summary);\n\n  f.done('success');\n});\n```\n\n### YAML\n\n```yaml\nversion: '0.1.0'\nname: hello\nsteps:\n  - id: greeting\n    type: deterministic\n    command: 'echo \"Hello from Relayflows\"'\n  - id: greeter\n    type: agent\n    dependsOn: [greeting]\n    instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'\n    cli: claude\n    model: claude-sonnet-4-6\n```\n\n**Version note.** The contracts below were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations. Direct `use`/`f.dispatch` composition requires `2.0.35` or newer. `AgentOptions.permissions` landed in `2.0.17`; predicate `.gate()` and `artifact_exists` landed with [flows#449](https://github.com/AgentWorkforce/flows/pull/449); `f.human` was already executable in `2.0.22`.\n\n## The real `Ctx` contract (TypeScript)\n\nFrom the shipped `@relayflows/surface@2.0.35` `.d.ts` files (`dist/context.d.ts`, `dist/step.d.ts`, `dist/flow.d.ts`, `dist/completion.d.ts`):\n\n```ts\nexport interface AgentResult {\n  summary: string;\n  artifacts: string[];\n}\n\nexport interface PermissionsSpec {     // exported from the package root\n  fileGlobs?: string[];\n  networkAllowlist?: string[];\n  accessPreset?: 'readonly' | 'readwrite';\n}\n\nexport interface AgentOptions {\n  task: string;\n  workspace?: string;\n  permissions?: PermissionsSpec;         // since 2.0.17 — declared and journaled, NOT enforced\n  cli?: string;\n  model?: string;\n  cwd?: string;                          // working dir for the CLI subprocess; defaults to the flow-runner's cwd\n  transport?: 'direct' | 'relay';        // see Agent-relay transport, below\n}\n\nexport interface LlmOptions {\n  output: Record<string, unknown>;       // JSON Schema, checked before the journal accepts the result\n  cli?: string;\n  model?: string;\n}\n\nexport interface DispatchResult {\n  name: string;\n  completionReason: 'success';\n  completionDetail?: string;\n}\n\nexport interface Ctx extends Helpers {   // Helpers = f.slack, f.github, f.linear, f.notion, ... — see Helpers\n  readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;\n  run(command: string, options?: { timeout?: string | number }): Step<string>;\n  llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;\n  llm(prompt: string, options: LlmOptions): Step<unknown>;\n  agent(name: string, options: AgentOptions): Step<AgentResult>;\n  human(question: string, options: { to: string }): Step<boolean>;\n  dispatch(flow: string, input: unknown): Step<DispatchResult>;\n  done(reason: FlowCompletionReason): void;\n  cloud: CloudHelper;\n  memory: MemoryHelper;\n}\n```\n\nDo not add fields to `AgentOptions`/`Ctx` that aren't in this list — they don't exist in the shipped SDK. In particular: **no flow-level named-agent selector on `f.agent`, no `recoveryMode`/`surfaces`/`output`** on the TypeScript call site. Those stay YAML/JSON step fields. `FlowHeader` (`dist/flow.d.ts`) allows `use`, `identity`, `memory`, `budget`, `tools`, `workspace` — no bare `agents` map key (TypeScript composes reusable flows via `use: string[]` instead — see **Named agents and flow composition**). An unknown *header* field throws a `TypeError` at authoring time, before anything is journaled; an unknown `AgentOptions` field is caught by `tsc`, not at runtime.\n\n**`permissions` is a real TypeScript option and it does not sandbox anything.** Since `2.0.17` it is on `AgentOptions`, validated by the SDK, lowered to `file_globs`/`network_allowlist`/`access_preset` and journaled with the step — and nothing reads it to gate a file or a network call. `flows check` warns `permissions_unenforced` on any declaration, including `{}`. Enforcement is [flows#442](https://github.com/AgentWorkforce/flows/issues/442). Declare it to record intent; do not rely on it to contain an agent.\n\n`run()`'s second argument is a real, current option: `{ timeout?: string | number }` — a duration string (`\"15m\"`) or milliseconds. Every real cookbook example that runs something slower than a few seconds sets this explicitly.\n\n### `f.done()`'s closed set is six values, not four\n\n```ts\nexport const FLOW_COMPLETION_REASONS = ['success', 'step_failed', 'canceled', 'budget_exceeded', 'needs_human', 'declined'] as const;\n```\n\nAn authored body can meaningfully call `f.done('success')`, `f.done('step_failed')`, `f.done('needs_human')` (parks the run — it's not a kernel cancellation), or `f.done('declined')` (a deliberate decision not to act — also not a cancellation). `'canceled'` and `'budget_exceeded'` exist in the same closed set but are the **kernel's** to record; a body calling them itself is calling the wrong verdict for what actually happened. The verdict for a human declining a durable approval is `f.done('declined')`, not `f.done('canceled')` — a human declining is a decision, not the kernel calling off the run.\n\n`Step<T>` (`dist/step.d.ts`) is a `PromiseLike<T>` with one extra method, `.gate(...)` — see **Verification gates**. Every awaited step must actually be awaited — an unawaited or manually-`.then()`-chained step is refused (`unawaited_step` / a manual `.then()` is not an await), not silently dropped.\n\n## Verification gates\n\nVerification is control flow, not decoration — a gate decides whether a step actually completed, not just whether the process exited cleanly.\n\n### YAML/JSON (`@relayflows/sdk`'s `VerificationSpec`)\n\n```ts\nexport type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate | NamedDataGate;\n// NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate\n//              | ArtifactExistsGate\n```\n\n- `exit_code` — implicit default for `deterministic` steps. Not configurable; writing it explicitly is allowed and compiles to the same thing as omitting it.\n- `output_contains` — step output (stdout tail, or the LLM value stringified) contains `value`.\n- `json_schema` — step output validates against a JSON Schema (`boolean | Record<string, unknown>`). Used for structured LLM/agent output; `output?: JsonOutputSchema` on an `llm`/`agent` step is sugar that compiles to this.\n- `subprocess_gate` — runs `command` under `/bin/sh`, judged on its exit code. The gate that actually works for \"check a file the agent wrote\": `{ type: 'subprocess_gate', command: 'test -s review.md' }`. If you also need to inspect the step's own output (via `from_output`), the SDK's generated wrapper reads its internal `FLOWS_INPUT` env var, extracts the value, and passes it to *your* command as `$INPUT` — `FLOWS_INPUT` itself is never visible to the author's command, only `$INPUT` is: `{ type: 'subprocess_gate', command: 'echo \"$INPUT\" | grep -q PASSED', from_output: ['summary'] }`.\n- `regex_match` — the step's output (or a value at `in_output_at`) matches `pattern`, evaluated by a non-backtracking RE2 engine (only `i`, `m`, `s` flags).\n- `artifact_exists` — passes when the step's journaled `artifacts` list contains `path` (working-directory-relative POSIX). It reads the journal, not the disk, so it sees exactly what the worker measured at `step.completed`; a path the worker never journaled reads as missing even when the file is there.\n- `word_count_bounds`, `references_input` — narrower named gates; see `packages/sdk/src/named-gates.ts` in the flows repo for the exact contract.\n\n```yaml\n- id: classify\n  type: llm\n  prompt: 'Classify this ticket as bug, feature, or question: \"the export button does nothing\"'\n  cli: claude\n  model: claude-sonnet-4-6\n  verification:\n    type: output_contains\n    value: bug\n```\n\n### TypeScript (`Step<T>.gate(...)`) — read this before you write one\n\n`Step<T>` has **two** overloads, and **one `.gate()` per step** — a second throws `unsupported_gate`:\n\n```ts\ngate(config: NamedGate): Step<T>;\n// NamedGate = ReferencesInputNamedGate | SubprocessNamedGate | WordCountBoundsNamedGate\n//           | RegexMatchNamedGate | ArtifactExistsNamedGate\n// — the surface-visible subset of NamedDataGate above. Data, not code: `flows check` can prove it.\n\ngate(predicate: (value: T) => boolean, because?: string): Step<T>;\n// Runs since flows#449. The executor calls the closure once, on the journaled value, and\n// journals the VERDICT as a lowered `<step>.gate` step — so resume and replay read the\n// recorded verdict and never re-run the function. A false verdict fails the run as\n// `gate_failed`, carrying `because`.\n```\n\nThe predicate form was refused with `unsupported_gate` through `2.0.16`; on `2.0.22` it runs. **Prefer the config-object form anyway** — `flows check` cannot prove a predicate (docs/SURFACE.md §6), so a named gate is the only kind a preflight can tell you about before you spend a run:\n\n```ts\nconst outdated = await f.run('npm outdated --json 2>/dev/null || true')\n  .gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\"' });   // provable by `flows check`\n\nconst review = await f.agent('review', { task: '…', cli: 'claude' })\n  .gate({ type: 'subprocess_gate', command: 'test -s review.md' });  // checks a file the agent wrote, ignores $INPUT\n```\n\n(Verified for real: `.gate({ type: 'subprocess_gate', command: 'test -n \"$INPUT\" && echo \"$INPUT\" | grep -q pkg' })` against a step outputting `{\"pkg\":\"left-pad\"}` passes — `$INPUT`, not `$FLOWS_INPUT`, is what the author's command sees. `FLOWS_INPUT` is an env var the SDK's own generated wrapper reads internally to extract the value before invoking your command; it is never visible to `command` itself.)\n\nAn agent step rarely fails by crashing; it fails by returning something plausible and wrong, which a plain retry-on-error never catches. Validate every `agent`/`llm` result, either directly with a supported gate or in a following deterministic verifier.\n\n**Where to put that check depends on what you want a red result to do.** A config-object or predicate gate directly on the agent/LLM step ends the run when it fails; use it when that failure should be terminal. For repairable failures, the following deterministic verifier must explicitly read the preceding output or workspace, produce its own verification result, and record it for repair. Output-dependent gates inspect the step they guard: moving the same gate unchanged would inspect the verifier's output, not the agent's. Use the record/repair/re-record/assert pattern in `relay-80-100-workflow`, gating the final verification result after repair.\n\n## Helpers: journaled effects, not just Slack\n\n`Ctx extends Helpers`, and `Helpers` is generated from 40+ provider adapters shipped in `@relayflows/surface` — `slack`, `github`, `linear`, `jira`, `notion`, `salesforce`, `postgres`, `s3`, `redis`, `daytona`, `gmail`, `google-calendar`, `hubspot`, and more (`dist/helpers/index.d.ts` lists them all). A helper call — `f.slack.post(channel, text)`, `f.github.comment(...)` — compiles to a journaled effect: the receipt the helper returns *is* the journal record, so a retried step that already posted doesn't double-post; the second attempt is deduped by `(step_id, idempotency_key, surface_path)`.\n\nTwo things every helper call needs:\n\n- **A relayfile mount for that provider**, locally — `flows check` refuses `helper_slack.credential_missing` (or the equivalent for another provider) without one. Cloud provides a mount for every connected provider automatically.\n- **A declared intent** on the flow header: `tools: { slack: true }` in TypeScript, or the equivalent in YAML. Forgetting this is a separate, earlier failure than the mount check.\n\nFor local development without standing up a real provider mount, prefix the run with the provider's mock env var — `RELAYFLOWS_SLACK_MOCK=1 flows run ... --local-agent` records the effect (a real file under the daemon's data dir) instead of sending it. This does not exercise live delivery, and should be called out as such wherever you cite it as verification.\n\n**`tools` means two different things depending on where you write it — do not confuse them:**\n\n- `FlowHeader.tools` (TypeScript) / `FlowSpec` top-level `tools` you're declaring intent on: `Partial<Record<keyof Helpers, boolean>> & { relayfile?: string[]; mcp?: string[] }` — e.g. `{ slack: true }`. This is \"which helpers this flow uses.\"\n- `FlowSpec.tools` in the compiled YAML/JSON spec is instead `{ fs?: string | string[] }` — path-scoped **filesystem** grants, mirroring `workspace` for shell/deterministic steps. Not the same field, despite the identical name.\n- `flows.json` (the project config file) has **no** `tools` field at all — see **`flows.json`**, below. Putting a `tools` key there is refused as `config_invalid`; this is an easy, first-try mistake (made once, personally, writing this refresh).\n\n## `cli` / `model`: what a step actually runs on\n\nBoth YAML and TypeScript agent/llm steps can set `cli` and `model` directly. Resolution order for `cli`, identical regardless of authoring language because both compile to the same `StepSpec`:\n\n1. **step** — `step.cli` (or TS's `options.cli`)\n2. **named** — the flow's `agents[step.agent]` entry, if the step selects one via `agent: <name>` (YAML/JSON only — TypeScript composes reusable flows via `use:` instead, not a per-step named-agent selector; see **Named agents and flow composition**)\n3. **flow** — `FlowSpec.cli` (YAML) — there is no equivalent flow-level `cli` field on the TypeScript `FlowHeader`\n4. **project** — nearest `flows.json`'s `cli`, found by walking up from the flow file's directory\n\nNo resolution found at any level → `REFUSED [cli_unresolved]`, before anything is journaled, e.g.:\n\n```\n$ flows check hello.flow.yaml   # agent step, no cli anywhere\nREFUSED [cli_unresolved] Step \"greeter\" has no CLI at step, flow, or project level. No flows.json was found from \"...\" to the filesystem root.\n```\n\n`model` has **no** flow or project default — only step or named-agent. Omitting it just runs whatever model the resolved CLI defaults to.\n\n### `flows.json`\n\nNearest-wins project config, walking from the flow file's directory to the filesystem root. The shipped SDK type (`@relayflows/sdk`'s `FlowsJson`) is exactly:\n\n```ts\ninterface FlowsJson {\n  cli?: string;\n  executors?: string[];\n  models?: string[];\n  mcp?: Record<string, McpServerConfig>;\n  deploy?: { bucket: string };\n}\n```\n\n- `cli` — the project-wide CLI default (resolution rung 4 above).\n- `executors` — trigger executors this project has registered. A trigger whose `executor` isn't in this list is `no_executor`; a flow that declares `.on(...)` triggers but is invoked directly (not via a webhook) still needs its provider named here — e.g. `{ \"executors\": [\"github\"] }` for a flow with `.on(github.pull_request(...))` handlers, even when you never hit that code path.\n- `models` — **an allowlist, not a default.** Any model declared on any step or named agent anywhere in the flow must appear here, or `flows check`/`flows run` refuses `model_unknown` / `llm_cli_unresolved`. Setting `models` does not select a model for anything.\n- `mcp` — project-owned MCP server connections.\n- `deploy` — a file-bucket target for `flows deploy <flow>@sha256:<digest> --to <bucket-uri>`.\n\n**Verified for real:**\n\n```\n$ flows run hello.flow.ts --local-agent --input '{}'   # step declares model \"claude-opus-5\", flows.json has no models[]\nREFUSED [invalid_spec] llm_cli_unresolved: Step \"llm-1\" declares model \"claude-opus-5\" for CLI \"claude\",\nbut it is not listed in project model registry \"…/flows.json\"; add the exact model only after verifying\nthat project is allowed to use it.\n\n$ flows run pr-reviewer.flow.ts --local-agent --input '{...}'   # flow declares .on(github....) handlers, no executors[]\nREFUSED [no_executor] webhook trigger \"github\" is not registered in flows.json\n```\n\nAny other top-level key — `tools`, `budget`, `identity`, `agents` — is refused as `config_invalid`. Those are `FlowHeader`/`FlowSpec` fields on the *flow itself*, not on the project config.\n\n## Named agents and flow composition\n\n**YAML/JSON**: a named-agent map declares each `{ cli, model }` pair once; a step's `agent:` selector resolves to it at compile time, and `flows check` flags a named agent nobody selects, or one a step overrides without using.\n\n```yaml\nagents:\n  planner: { cli: claude, model: claude-opus-5 }\n  implementer: { cli: codex, model: gpt-5.6-codex }\nsteps:\n  - id: plan\n    type: agent\n    agent: planner\n    instruction: '…'\n```\n\n**TypeScript** has no equivalent `agents:` map key on `FlowHeader` — the closest idiom is a plain object spread reused across calls:\n\n```ts\nconst planner = { cli: 'claude', model: 'claude-opus-5' };\nawait f.agent('plan', { ...planner, task: '…' });\n```\n\nWhat TypeScript *does* have is `FlowHeader.use?: string[]`: relative `.flow.ts` paths to direct child flows the body may call with `f.dispatch`. This is composition of complete flows, not a named-agent map. It executes in `2.0.35` and newer; see **Human approval and direct child flows**.\n\n## Parallel agents\n\nRunning several agent (or any) steps concurrently is first-class, documented authoring — not a workaround:\n\n> \"…`Promise.resolve`, `Promise.all`, `Promise.allSettled`, `Promise.any` and `Promise.race` over authored steps\" are \"ordinary, supported authoring.\" — `docs/SURFACE.md`, the authored operation lifecycle\n\n```ts\nconst LENSES = ['security', 'correctness', 'performance'] as const;\n\nawait Promise.all(\n  LENSES.map((lens) =>\n    f.agent(`${lens}-reviewer`, {\n      task: `Review this diff for ${lens} issues ONLY. Write findings to review/${lens}.json.`,\n      cli: 'claude',\n    }).gate({ type: 'subprocess_gate', command: `test -s review/${lens}.json` }),\n  ),\n);\n\nconst consensus = await f.agent('consensus', {\n  task: 'Read review/*.json. Resolve disagreement between lenses. Write review/consensus.json.',\n}).gate({ type: 'subprocess_gate', command: 'test -s review/consensus.json' });\n```\n\nThis is the exact shape `examples/pr-review-pipeline` in `AgentWorkforce/flows` (and the cookbook's would-be equivalent) uses: fan out, each lane writes its own file, a reconciliation step reads them all. **Disclosure worth knowing before you rely on it**: the flows package replaces the global `Promise.all` intrinsic, process-wide, for the lifetime of any authored flow execution, so the kernel can prove every concurrent step was actually awaited (rather than inferring group membership from callback identity). It delegates to the real intrinsic and restores it when the last concurrent flow closes — but any other code sharing that process sees the replacement during that window.\n\n## Agent-relay transport: dispatch, not live chat\n\n`AgentOptions.transport?: 'direct' | 'relay'` (default `'direct'`, a local subprocess). Setting `transport: 'relay'` dispatches the step to Agent Relay's own task infrastructure instead — per the shipped type's own doc comment: *\"posts to agent-relay so the agent registers as a first-class workspace participant that DMs can steer.\"*\n\nWhat this actually is, per `docs/AGENT-RELAY-TRANSPORT.md`: the step calls `POST /v1/actions/task.run/invoke` against relaycast, then waits for a durable final receipt — spawn readiness and invocation acceptance do **not** complete the step, only a terminal receipt does. It needs a pre-provisioned `RELAY_AGENT_TOKEN` (a workspace API key cannot substitute) and the Relay provider running with `AGENT_RELAY_TASK_PROVIDER=1`. The dispatched worker submits its result via an injected `agent_result` tool.\n\nDon't describe this as \"agents talking to each other\" — there's no documented pattern in this skill's scope for two flow steps to hold a live back-and-forth over Relay channels while both are running. What's real: the step's agent becomes a genuine Agent Relay workspace participant while it runs (so a human, or another agent with the right access, can DM it and potentially steer it — per the type's own wording), and the flow still only sees a request-and-durable-receipt shape, not an open channel. Multi-agent *coordination* inside a flow today means sequential handoff (one step's return value feeds the next) or parallel fan-out (**Parallel agents**, above) — not live messaging.\n\n## Human approval and direct child flows\n\n`f.human` parks a root run on a durable approval. `f.dispatch` executes a statically declared direct child in the same durable tree on `2.0.35` and newer. Both must be awaited.\n\n`f.human` parks the run durably on a kernel `wait.human`, keyed `human-<n>` in the order the body asked. A person answers, and `flows resume` continues the body from that line:\n\n```ts\nconst ok = await f.human(`Ship this?\\n${plan.summary}`, { to: 'khaliq' });\nif (!ok) return f.done('declined');   // a person's \"no\" is declined, never canceled\n```\n\n```\n$ flows answer <run-id> human-1 yes --by khaliq --note 'reviewed the diff'\n$ flows resume <run-id>\n```\n\n`to` names who is asked and is recorded with the question — **it is not a delivery address**; nothing notifies that person for you. The kernel closes a wait once, so the first answer wins, and it records `attribution: \"client_asserted\"` because the daemon socket, not the kernel, authenticated whoever `--by` names. The answer step takes a `.gate(config)` like any other step. One caveat: `f.human` needs a durable root run to park in — under a runner that has none it refuses with `unsupported_verb`, so run it with `flows run`.\n\nFor a composed local run, declare each direct child in the parent's static `use` header, then dispatch by the child's declared `flow(...)` name—not by its file path:\n\n```ts\n// release.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('release', { use: ['./implement.flow.ts'] }, async (f) => {\n  await f.run(\"printf '%s' prepare\");\n  const child = await f.dispatch('implement', { issue: 123 });\n  await f.run(\"printf '%s' publish\");\n  f.done(child.completionReason);\n});\n```\n\n```ts\n// implement.flow.ts\nimport { flow } from '@relayflows/surface';\n\nexport default flow('implement', async (f, input: { issue: number }) => {\n  await f.run(`printf '%s' ${input.issue}`);\n  f.done('success');\n});\n```\n\n`use` resolves relative `.flow.ts` files before a body runs. Missing or repeated files, duplicate direct-child names, cycles, and undeclared or transitive-only dispatch targets are refused. The child's steps receive qualified IDs such as `dispatch-2--run-1`; the dispatch receipt joins child leaves back to the parent's next step. Parent and child share one root budget and worker-capacity pool, and resume reuses journaled identities rather than repeating completed effects. A successful dispatch returns `{ name, completionReason: 'success', completionDetail? }`; any other child verdict fails the dispatch.\n\nAuthority narrows: a child cannot declare a second budget, require a helper/MCP capability its parent did not grant, or call `f.human`. Static cycles are refused and runtime child depth is capped at three. This is direct authored composition, not arbitrary public-flow invocation.\n\nTo put the **whole local tree** on one Cloud dashboard page, run `flows run --cloud-mirror release.flow.ts --input '{}'` (or affirmatively set `FLOWS_CLOUD_MIRROR=1`). The root, qualified child steps, dispatch receipts, dependency edges, transcripts, source, and output are projected into one connected graph; the local journal remains authoritative. Mirroring uploads that data and is opt-in. A mirror failure cannot fail the local run. The default observer link is separate and does not add the run to Cloud history.\n\nDo not confuse this with **hosted execution**. `flows run --cloud [--sync-code] release.flow.ts --input '{}'` still rejects `use` dependencies with `unsupported_source`: Cloud accepts one self-contained `.flow.ts` source. Use `--cloud-mirror` for the connected child-flow dashboard today; do not promise that Cloud can itself execute a multi-file `use` tree.\n\n**The same \"types accept it, the executor doesn't\" trap applies to `workspace` on an agent step under `--local-agent`.** Neither an annotated (`'acme/api: readonly'`) nor a bare (`'acme/api'`) value works — both fail identically:\n\n```\nREFUSED [invalid_spec] unsupported_workspace_permission: The local agent worker accepts\nstream-only steps. Remove workspace or attach a worker that holds its revision pins.\n```\n\nIt isn't the `: readonly`/`: readwrite` annotation syntax that's rejected — it's that the local-agent worker doesn't hold workspace revision pins at all. Omit `workspace` entirely for a step you intend to run with `--local-agent`; it's a real, working field only against a worker that supports it (Cloud's). Against a worker that does hold pins, the suffix is separately refused, and the remedy the SDK's own message names is `f.agent`'s `permissions` option — which records the scope and does not enforce it.\n\n## Running it: `flows check` / `run` / `deploy` / `schedule`\n\n```\nflows check [--json] [--watch] <flow.ts|flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.yaml|spec.json>\nflows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>\nflows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--data-dir <dir>] [--local-agent] <run-id>\nflows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]\nflows deployments [--json]\nflows undeploy [--json] <deployment-id>\nflows schedule <flow.ts> --cron \"<expr>\" --tz <tz> --input <inline-json-or-file>\n```\n\n`check` is a pure compile-and-preflight — no daemon, no socket, no data dir. It's the fast, safe way to validate a flow before ever running it, and it does accept `.flow.ts` despite older `--help` text implying only YAML/JSON.\n\n**`--local-agent` is not optional decoration.** Without it, `agent`/`llm` steps have no worker to dispatch to and the run parks indefinitely rather than executing. Every local run in this skill's examples, and every real run in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook), passes it.\n\nA `.flow.ts` run via `flows run` requires `--input <inline-json-or-file>` even when the flow body ignores its input argument.\n\n**`--data-dir` gotcha, learned the hard way.** If a flow does its own git hygiene on the directory you invoke it from — `pr-reviewer`'s and similar examples' `git clean -fdq -e .workforce` when there's nothing to push — that cleanup deletes *anything else untracked in that directory*, including the daemon's own default `.relayflowd/` state if you didn't move it. The symptom is a bizarre `SQLite journal failed: unable to open database file` on the *next* run in the same checkout, because the previous run's own cleanup step deleted the very journal directory the daemon needed. Fix: put the daemon's data outside the checkout:\n\n```bash\nflows run pr-reviewer.flow.ts --local-agent --data-dir /somewhere/outside/the/repo --input '{...}'\n```\n\n**Before `flows deploy` will do anything, two things have to already be true — a correct command still fails without them:**\n\n1. **You (or whoever's driving this) are logged in.** `agent-relay cloud login` once; check with `agent-relay cloud whoami`. There's no separate `flows`-specific login — it shares the `agent-relay` Cloud session.\n2. **The workspace has a GitHub App installation covering `--repo`, and the `--on` provider is actually a connected integration** — not just declared in the command. `flows deploy` looks up the workspace's GitHub installation before it will activate a listener; with none, it refuses `flow_repository_not_connected` rather than deploying a broken one (`prepare-flow-deploy.ts` in `AgentWorkforce/cloud`). Check what's connected with `agent-relay cloud integration connections --workspace <id>` — a provider showing `degraded` instead of `ready` is not deploy-safe, even though the CLI won't tell you that until you try. This is a separate concern from your own local git push access (a personal git/`gh` credential thing, needed only for testing a flow's own `git push`/`gh pr create` steps locally) — don't conflate the two when debugging a refusal.\n\n**`flows deploy`** creates a persistent listener: each matching ticket (`--on github:labels=agent`, `linear:team=ENG`, `jira:project=OPS`, `shortcut:workspace=…`, `slack:channel=#eng`) launches one Cloud run. `flows deployments` lists what's listening; `flows undeploy <id>` stops it — verified for real this session (deployed `software-factory` against a real repo with `--on linear:team=…`, got back `{\"status\":\"listening\", ...}`, then cleanly undeployed).\n\n**`flows schedule`** puts a flow on a cron instead of a ticket trigger — newer (shipped after the `2.0.16` release line) and not yet reflected everywhere in older examples that instead show `flows run --cloud` for the same use case.\n\n**Now fixed, was broken through `2.0.16`** ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), closed): the one-shot `flows run --cloud [--sync-code] <flow.ts> --input <json>` form used to misroute authored TypeScript flows into the declarative-spec loader (`invalid_input: Cannot read or compile the declarative flow`) or refuse with a bare `http_error: HTTP 400`. Root cause: Cloud pinned an older `@relayflows/surface` than the CLI authored against, and refused the version mismatch with those opaque errors instead of naming it. Fixed in `2.0.17` (CLI side) — verified for real: `flows run --cloud --wait <flow.ts> --input '{}'` now submits successfully and returns a real run ID instead of refusing immediately. If you still hit a bare `HTTP 400`/`invalid_input` on this path, you're likely on a CLI older than `2.0.17` — update first before assuming something else is wrong. (Cloud-side reporting of the exact version mismatch, when one still exists, was tracked as a separate follow-up PR at the time of writing — the CLI's own refusal is fixed either way.)\n\n### Watching a local run: observer link vs `--cloud-mirror`\n\nNew in **`2.0.32`**. A local run has two ways to be watched, and they are not the same thing:\n\n- **The observer link is the default.** Every `flows run` mints a read-only `ot_live_` link scoped to that run's own `wf-<runId>` channel and prints `Observer: <url>`. It is free, needs only a workspace key, and carries a step projection. `--no-observer-link` suppresses it.\n- **`--cloud-mirror` additionally puts the run on the Cloud dashboard** — the richer hosted view: the flow source, **every agent step's transcript**, the run graph, the run's own log, and the run sitting in the same history as your hosted ones. `FLOWS_CLOUD_MIRROR=1` turns it on for a whole shell.\n\n```bash\nflows run review.flow.ts --local-agent --input '{}'                  # observer link only\nflows run --cloud-mirror review.flow.ts --local-agent --input '{}'   # ...and the dashboard\n```\n\nThe run prints both, and the dashboard line names Cloud's run id as well as the page:\n\n```\nObserver:  https://agentrelay.com/observer?key=ot_live_...\nDashboard: https://.../dashboard/workflow/<cloud-run-id>/runner  ·  flows status --cloud --watch <cloud-run-id>\n```\n\n**That second id matters and is easy to get wrong.** The report's own `runId` is the *journal's* ULID (`01M3B9...`), while the two hosted verbs that take an id — `flows status --cloud <run-id>` and `flows logs <run-id>` — want Cloud's UUID. Do not pass a journal id to either. Under `--json` both ride in the report as `cloudRunId` and `dashboardUrl`, beside `observerUrl`.\n\n`flows runs` is the odd one out and the way *out* of this problem: it takes no id at all (`flows runs [--limit <n>] [--json]`) and lists the runs the credential can see, newest first, with each one's Cloud UUID — so it is how you find the id the other two want when you no longer have the terminal that printed it.\n\n**Why it is opt-in, not on by default.** Because it is the richer view, it is also the one that *stores* all of that: source, step metadata, agent transcripts, and the CLI's own stderr. Transcripts are whatever the agent printed, including file contents and command output. Everything goes through the same redactor `flows status` uses — but redaction is pattern matching, and pattern matching has a false-negative rate. So the trigger is an explicit request and never the mere presence of a Cloud login. Only an affirmative counts for the env var (`1`/`true`/`on`/`yes`); `0`, empty, and anything nobody meant as a switch all leave the run local.\n\n**What it buys you, concretely:** the three read verbs start answering for *local* runs, which until `2.0.32` only worked for runs Cloud had launched.\n\n```\n$ flows status --cloud <cloud-run-id>\nRUN 27ab5702-...  local-mirror-agent-confirmation  completed  spend 13,088 in / 61 out / $0.01836\n  ✓ ask-claude  agent  1 attempt  3.3s  claude-haiku-4-5-20251001 · 1 turn · $0.01836\n  ✓ ask-codex   agent  1 attempt  7.9s\n$ flows logs <cloud-run-id> --step ask-claude    # that step's transcript, out of Cloud storage\n```\n\nThree behaviours worth knowing before you rely on it:\n\n- **It cannot fail a run.** Every push collapses to a boolean; each poll and the whole finish are bounded. A Cloud outage costs the run its dashboard page and nothing else. If the mirror is refused you get one line naming which switch asked for it, and the run's exit code is untouched.\n- **The dashboard says the run was local.** The row is `dispatchType: \"local\"`, and the run page shows **Ran on: Your machine** instead of a sandbox tile. Cancel is refused for it — Cloud mirrors a local run, it does not control it, so stop it where it is running.\n- **A `--cloud-mirror` resume is a second dashboard row, linked to the first.** Cloud refuses to move a terminal run back to `running` (its own hosted resume mints a fresh id too), so the resumed attempt carries `resumedFromRunId` and the run page links the two — the parked \"Needs review\" row shows what continued it. The mapping lives in `<data-dir>/cloud-runs/`: the Cloud run id and the deployment, no credential, mode 0600, ageing out at 30 days.\n\n**Requires a Cloud login** (`agent-relay cloud login`, or `FLOWS_CLOUD_TOKEN`) — the same credential every other hosted verb uses. Without one, `--cloud-mirror` prints one line saying the run stays local and the run proceeds normally. A local run that joins no workspace is not a defect (RFC-0001 settled decision 7: the journal is the record, the workspace is one view onto it).\n\n### Exit codes and refusal shapes\n\nEvery refusal before a journal write is exit **2**, printed as `REFUSED [<kind>] <message>`. The `<kind>` differs by *how* the flow was checked, not just *what* was wrong:\n\n- `flows check` on a YAML/JSON spec, or the declarative-compiler path in general → the preflight's own kind directly: `cli_unresolved`, `model_unknown`, `cli_missing`, `cli_unauthenticated`, `no_executor`, `config_invalid`, etc.\n- `flows run` on a **TypeScript** `.flow.ts` whose authored `f.agent`/`f.llm` call can't resolve a CLI or model at runtime → wrapped and printed as `REFUSED [invalid_spec] <message>` with the specific reason (`llm_cli_unresolved`, etc.) inside the message text, not as the printed `[kind]` itself.\n\nBoth are real, both are exit 2 — the same underlying problem can print a different `[kind]` depending on whether you hit it via `flows check` on YAML or `flows run` on TypeScript.\n\n## Common mistakes\n\n- **Forgetting `version` in a YAML/JSON `FlowSpec`.** Required, not optional.\n- **Attaching two `.gate()` calls to one step.** `unsupported_gate`: a step takes one. Also note a predicate gate is invisible to `flows check` — prefer a config object when preflight should be able to prove it.\n- **Putting `tools`, `budget`, or any other `FlowHeader` field into `flows.json`.** `flows.json` only accepts `cli`, `executors`, `models`, `mcp`, `deploy` — anything else is `config_invalid`.\n- **Assuming `flows.json`'s `models` sets a default model.** It only validates models already declared elsewhere; it never selects one.\n- **Declaring `.on(...)` trigger handlers without registering the provider in `flows.json`'s `executors`.** Even a flow you only ever run directly (never via a real webhook) needs this, or it's refused `no_executor` before your input is even read.\n- **Calling `f.done('canceled')` for a human's \"no.\"** That's `f.done('declined')` — `canceled` is the kernel's verdict, not an authored body's.\n- **Running an agent/llm-bearing flow without `--local-agent`.** The run parks with nothing attached to do the work.\n- **Letting a git-hygiene flow's cleanup step delete your daemon's own data dir.** Pass `--data-dir` outside the checkout for any flow that runs `git clean`/`git checkout --force` on its own working tree.\n- **Not awaiting a step, or manually `.then()`-chaining one.** Refused (`unawaited_step`) rather than silently ignored.\n- **Running a `.flow.ts` without `--input`.** Required even for flows that don't use their input argument.\n- **Assuming `flows run --cloud` for a one-shot TypeScript flow run is still broken.** It was through `2.0.16` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461), now closed) — fixed in `2.0.17`. If you're on an older CLI, update rather than reach for a workaround; `flows deploy` remains the right choice for a persistent listener regardless.\n\n## What this skill does NOT cover\n\n- **Triggers/webhooks** (`.on(github.pull_request(...), ...)`), **memory retrieval**, and the full **helper** catalog's per-provider quirks (`f.mcp`, provider-specific settings) — each is its own surface; see the [Relayflows product docs](https://agentrelay.com/docs/relayflows) and the [flows-cookbook](https://github.com/AgentWorkforce/flows-cookbook) for real, run-verified examples of each.\n- **Named-agent map equivalent in TypeScript beyond `use:`** — `use` composes complete child flows, not named agent configurations.\n- **YAML-only agent step fields with no TypeScript equivalent**: `recoveryMode`, `surfaces`, `output`, the `agent:` named-agent selector, and enforced `workspace` (TypeScript's `workspace` string is accepted by the type but rejected by the local-agent worker — see **Human approval and direct child flows**). `permissions` is **not** on this list — it is a TypeScript option too (see **The real `Ctx` contract**).\n- **Hosted multi-file child-flow execution** — `flows run --cloud` refuses `use` dependencies even with `--sync-code`; `--cloud-mirror` is the supported route for a local child-flow tree on the Cloud dashboard.\n- The **older `@relayflows/core` `WorkflowBuilder`** engine — see `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` in this repo.\n\n## Quick reference\n\n| Verb / field | Language | Notes |\n|---|---|---|\n| `f.run(command, {timeout?})` / `type: deterministic` | both | shell command, implicit `exit_code` gate |\n| `f.llm(...)` / `type: llm` | both | bare model call, no workspace |\n| `f.agent(name, opts)` / `type: agent` | both | harnessed coding agent, returns `{summary, artifacts}` |\n| `f.human(question, {to})` | TS only | parks the run on a durable `wait.human`; `flows answer <run> human-<n> yes\\|no` then `flows resume` |\n| `use: ['./child.flow.ts']` / `f.dispatch(name, input)` | TS only | `2.0.35`+ direct child in one durable tree; dispatch by declared name |\n| `f.done(reason)` | TS / kernel | one of `success \\| step_failed \\| needs_human \\| declined` from an authored body; `canceled \\| budget_exceeded` are kernel-only |\n| `.gate(config)` / `.gate(predicate, because)` | TS | one per step; both run since flows#449, but only a config object is provable by `flows check` |\n| `options.transport: 'relay'` | TS/YAML `agent` step | dispatch to Agent Relay's task infra; request+receipt, not live chat |\n| `Promise.all([...steps])` | TS | first-class supported concurrent fan-out |\n| `flows.json`: `cli, executors, models, mcp, deploy` | project config | exact accepted key set — nothing else |\n| `flows check <file>` | CLI | pure validate + preflight, no daemon |\n| `flows run <file> --local-agent [--input ...]` | CLI | actually executes; `.flow.ts` needs `--input`, agent/llm steps need `--local-agent` |\n| `flows deploy <flow.ts> --repo ... --on ...` | CLI | persistent trigger-based listener; needs `agent-relay cloud login` plus a connected GitHub App + `--on` provider first, or `flow_repository_not_connected` |\n| `flows run --cloud <flow.ts> --input ...` | CLI | fixed in `2.0.17` ([flows#461](https://github.com/AgentWorkforce/flows/issues/461)); update if you still see `http_error`/`invalid_input` |\n| `flows run --cloud-mirror <file> --local-agent` | CLI | `2.0.32`+; local run also on the Cloud dashboard, transcripts included. Opt-in; `FLOWS_CLOUD_MIRROR=1` for a shell. `--json` gains `cloudRunId`/`dashboardUrl` |\n| `flows run --cloud` with `use` | CLI | unsupported: one self-contained `.flow.ts` source only, even with `--sync-code` |\n| `flows status --cloud <run-id>` / `flows logs <run-id>` | CLI | take Cloud's **UUID**, not the journal ULID. Answer for mirrored local runs since `2.0.32` |\n| `flows runs [--limit <n>]` | CLI | takes **no id** — lists runs newest-first, which is how you find the UUID the two above want |\n| `flows schedule <flow.ts> --cron ...` | CLI | cron-based cloud run |\n\n## Verified against\n\n**The `Ctx` and child-flow contracts were checked against the published `@relayflows/surface@2.0.35` / `@relayflows/sdk@2.0.35` declarations.** Earlier gate, helper, and agent-option findings below were established on `2.0.22`; the original `--cloud-mirror` verification was on `2.0.32`.\n\nA three-level root → child → grandchild fixture was run locally from published `2.0.35` packages, then mirrored to the production Cloud dashboard. The [mirrored run](https://agentrelay.com/cloud/dashboard/workflow/0d502725-e4c2-4cfd-aed2-ed0dd49bd6ac/runner) completed with `completionReason: success`; its Cloud graph contained seven succeeded work/dispatch nodes, seven runtime dependency edges, both child labels, and no warnings. A separate `flows run --cloud --sync-code` attempt refused the same tree before admission with `unsupported_source`, which is why this skill does not promise hosted child-flow execution. This checks the graph API used by the dashboard, not an authenticated browser screenshot.\n\n**The `--cloud-mirror` section was verified on `2.0.32`, against production, with the published artifact.** `relayflows@2.0.32` was installed from npm into a scratch project — not run from a source tree — and two real local runs were mirrored to `agentrelay.com`:\n\n- a two-step deterministic flow, read back with `flows status --cloud`, `flows logs` (the `runner.log` round-trip) and `flows runs` (the run appearing in history beside hosted ones);\n- a two-agent flow, one `cli: claude` step and one `cli: codex` step, spending a real `$0.01836` — whose **per-step transcripts were fetched back out of Cloud storage** and rendered in each provider's own frame vocabulary. That is the claim worth having evidence for: an echo-only flow exercises none of the transcript path.\n\nTwo things that verification established and that are easy to assume otherwise. **Flows drives exactly two agent CLIs**: `adapters/index.ts` registers `claude` and `codex`, and anything else resolves to `relayflows-wrapper-v1`, which requires the executable to answer `--relayflows-adapter-v1` with a flows-specific token. A real `devin` CLI on `PATH` rejects that flag outright (`error: unexpected argument`), so it cannot be used as a `cli:` for an agent step no matter what is installed — adding one is a new `adapters/<name>.ts` plus a registry entry. And the **observer projection has no retry**: `run-projection.ts` sets `failed = true` on the first error and every later publish is a no-op, so a transient `429 workspace_busy` — observed for real during this verification, while another run was launching in the same workspace — permanently loses the observer view for that run. The dashboard mirror survived the same window because it classifies `429` as transient and retries on its next poll. If an observer link opens an empty channel, that asymmetry is the first thing to check.\n\nThe earlier `2.0.22` refresh settled several contradictions against the published package: `AgentOptions.permissions` exists on the TypeScript call site (added in `2.0.17`, validated and journaled, not enforced — preflight warns `permissions_unenforced`); `run(command, options?)` takes a second `{timeout}` argument; `f.done` takes six `FLOW_COMPLETION_REASONS`; there is no `budget.maxWallclockMs`; predicate `.gate()` and `artifact_exists` ship; and `f.human` executes. Its then-true finding that `f.dispatch` was unsupported was superseded by `2.0.35`. Older real-run recipes are in [`AgentWorkforce/flows-cookbook`](https://github.com/AgentWorkforce/flows-cookbook); check their dates when comparing behavior.\n\nThe `flows.json` schema refusal, the `--data-dir` git-hygiene interaction, and the `flows run --cloud` bug were reproduced while building that cookbook past `v2.0.16` (2026-09-17). The `2.0.22` refresh also checked the `workspace: readonly` annotation and the `subprocess_gate` env var name against the real CLI. Child-flow claims above instead rest on the published `2.0.35` run and its production Cloud graph.\n"
 };
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 0bd6f807..68c80ad4 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -81,7 +81,7 @@ describe('agent signup instructions', () => {
   it('keeps Flows on the v2 engine: it may warn about @relayflows/core but never imports or installs it', async () => {
     const content = await guide('flows');
     expect(content).toContain('@relayflows/surface');
-    expect(content).not.toMatch(/from\s+['"]@relayflows\/core['"]/);
+    expect(content).not.toMatch(/\b(?:from\s+|import\s*(?:\(\s*)?)['"]@relayflows\/core['"]/);
     expect(content).not.toMatch(/(?:npm|pnpm|yarn|bun)\s+(?:i|install|add)\b[^\n]*@relayflows\/core/);
     expect(content).not.toMatch(/require\(\s*['"]@relayflows\/core['"]\s*\)/);
     // The only mentions are writing-relayflows' warning against the older engine.
@@ -139,6 +139,12 @@ describe('agent signup instructions', () => {
     expect(content).toContain('Cloud API base: http://127.0.0.1:3199/cloud');
     expect(content).toContain('http://127.0.0.1:3199/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg');
     expect(content).toContain('relay-socket.dev');
+    // Part 2's executable desktop commands target the Dev app, not production.
+    expect(content).not.toContain('relay-desktop-releases');
+    expect(content).not.toMatch(/com\.agentrelay\.desktop(?!\.dev)/);
+    expect(content).not.toMatch(/relay-socket(?!\.dev)"/);
+    expect(content).not.toContain('Agent Relay.app');
+    expect(content).toContain('"$release/AgentRelay-Dev-macOS-$relay_arch.dmg"');
     expect(content).toContain('http://127.0.0.1:3199/cloud/api/v1/mcp/shared-sessions');
     expect(content).not.toContain('https://agentrelay.com/cloud');
     expect(agentSignupPrompt('teams', 'http://127.0.0.1:3199')).toContain('http://127.0.0.1:3199/signup/agent/teams');
diff --git a/web/scripts/sync-setup-skills.mjs b/web/scripts/sync-setup-skills.mjs
index d8d7bf4d..05b23466 100644
--- a/web/scripts/sync-setup-skills.mjs
+++ b/web/scripts/sync-setup-skills.mjs
@@ -8,7 +8,7 @@
 //   node web/scripts/sync-setup-skills.mjs --check  # fail when the copies differ from the pin
 //
 // To move the pin, change "commit" in SOURCE.json and run without --check.
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 
 const contentDir = new URL('../content/setup-skills/', import.meta.url);
@@ -61,8 +61,12 @@ async function main() {
   const expected = new Map(source.skills.map(name => [new URL(`${name}.md`, contentDir), skills[name]]));
   expected.set(generatedUrl, renderModule(source, skills));
 
+  // A vendored copy that SOURCE.json no longer lists is stale too.
+  const pinned = new Set(source.skills.map(name => `${name}.md`));
+  const unlisted = (await readdir(contentDir)).filter(file => file.endsWith('.md') && !pinned.has(file));
+
   if (check) {
-    const stale = [];
+    const stale = unlisted.map(file => new URL(file, contentDir).pathname);
     for (const [url, text] of expected) {
       const existing = await readFile(url, 'utf8').catch(() => null);
       if (existing !== text) stale.push(url.pathname);
@@ -77,6 +81,7 @@ async function main() {
   }
   await mkdir(new URL('.', generatedUrl), { recursive: true });
   for (const [url, text] of expected) await writeFile(url, text);
+  for (const file of unlisted) await rm(new URL(file, contentDir));
   console.log(`Vendored ${source.skills.length} setup skills from AgentWorkforce/skills@${source.commit}.`);
 }
 

From 37cea5ae67962896b5b7f74b57d413520dc45770 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 23:15:56 -0700
Subject: [PATCH 5/9] fix(signup): rewrite desktop commands for the Dev app
 only on the local stack

An HTTPS preview or staging host keeps the release app; only the plain-HTTP
local stack serves the Dev DMG.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/lib/agent-signup.ts           | 13 ++++++++-----
 web/lib/test/agent-signup.test.ts |  8 ++++++++
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index d776a6cd..11a52f7a 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -158,19 +158,22 @@ const PRODUCTION_SITE = 'https://agentrelay.com';
 const DESKTOP_RELEASES = 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download';
 
 /**
- * The skills name production. A local stack substitutes its own exact origins
- * and, so the desktop commands run as written, the prebuilt Agent Relay Dev
- * app's download, app name, bundle id and socket paths.
+ * The skills name production. Another host substitutes its own exact origins;
+ * the plain-HTTP local stack also substitutes, so the desktop commands run as
+ * written, the prebuilt Agent Relay Dev app's download, app name, bundle id
+ * and socket paths.
  */
 function forEnvironment(skill: string | undefined, site: string, cloud: string): string {
   if (skill === undefined) throw new Error('A signup part names a skill that is not vendored');
   if (site === PRODUCTION_SITE && cloud === `${PRODUCTION_SITE}/cloud`) return skill;
-  return skill
+  // Only the plain-HTTP local stack serves the Dev app; any HTTPS host keeps the release app.
+  const local = site.startsWith('http:') ? skill
     .replaceAll(DESKTOP_RELEASES, `${site}/cloud/desktop-downloads`)
     .replaceAll('AgentRelay-macOS-', 'AgentRelay-Dev-macOS-')
     .replaceAll('Agent Relay.app', 'Agent Relay Dev.app')
     .replace(/com\.agentrelay\.desktop(?!\.dev)/g, 'com.agentrelay.desktop.dev')
-    .replace(/\.agentworkforce\/desktop\/relay-socket(?!\.dev)/g, '.agentworkforce/desktop/relay-socket.dev')
+    .replace(/\.agentworkforce\/desktop\/relay-socket(?!\.dev)/g, '.agentworkforce/desktop/relay-socket.dev') : skill;
+  return local
     .replaceAll(`${PRODUCTION_SITE}/cloud`, cloud)
     .replaceAll(PRODUCTION_SITE, site);
 }
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index d041e423..6b78885a 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -155,6 +155,14 @@ describe('agent signup instructions', () => {
     expect(agentSignupPrompt('teams', 'http://127.0.0.1:3199')).toContain('http://127.0.0.1:3199/signup/agent/teams');
   });
 
+  it('keeps the release desktop app for an HTTPS host other than production', async () => {
+    const content = await guide('teams', 'https://preview.example.com/signup/agent/teams');
+    expect(content).toContain('relay-desktop-releases/releases/latest/download');
+    expect(content).toContain('"$release/AgentRelay-macOS-$relay_arch.dmg"');
+    expect(content).not.toContain('Agent Relay Dev.app');
+    expect(content).not.toContain('com.agentrelay.desktop.dev');
+  });
+
   it('uses the browser local hostname when Next normalizes the request URL', async () => {
     vi.stubEnv('NEXT_PUBLIC_CLOUD_URL', '/cloud');
     const content = await (await GET(new Request('http://localhost:3100/signup/agent/flows', { headers: { host: '127.0.0.1:3100' } }), {

From 7806187ff91fd1ffa1b5598d865be2ec0ca9b2e1 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 23:26:33 -0700
Subject: [PATCH 6/9] fix(signup): treat only http://localhost and 127.0.0.1 as
 the local stack

The Dev-app rewrite and the local note now share one check, so an HTTP
staging or self-hosted guide keeps the release app.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 web/lib/agent-signup.ts           | 14 ++++++++++----
 web/lib/test/agent-signup.test.ts |  4 ++--
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 11a52f7a..18ecffc7 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -73,7 +73,7 @@ Setup is complete only in Part 3's finished state: a proven live round trip.` :
 Part 1 creates the account with signup_source "flows". Part 2 uses its access
 token and its user.id and currentWorkspace.id. Part 3 is writing-relayflows,
 the authoring guide Part 2's custom-flow path defers to; skip it for a
-prebuilt flow.`}${site.startsWith('http:') ? localDevelopmentNote(product, site) : ''}
+prebuilt flow.`}${isLocalStack(site) ? localDevelopmentNote(product, site) : ''}
 
 ## Live progress (when the user's prompt includes a progress session)
 
@@ -155,19 +155,25 @@ const signupParts: Record<AgentSignupProduct, readonly { label: string; skill: s
 
 const PRODUCTION_SITE = 'https://agentrelay.com';
 
+/** The paired local stack: plain HTTP on localhost or 127.0.0.1, the hosts the route keeps. */
+function isLocalStack(site: string): boolean {
+  const { protocol, hostname } = new URL(site);
+  return protocol === 'http:' && (hostname === 'localhost' || hostname === '127.0.0.1');
+}
+
 const DESKTOP_RELEASES = 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download';
 
 /**
  * The skills name production. Another host substitutes its own exact origins;
- * the plain-HTTP local stack also substitutes, so the desktop commands run as
+ * the local stack (http://localhost or http://127.0.0.1) also substitutes, so the desktop commands run as
  * written, the prebuilt Agent Relay Dev app's download, app name, bundle id
  * and socket paths.
  */
 function forEnvironment(skill: string | undefined, site: string, cloud: string): string {
   if (skill === undefined) throw new Error('A signup part names a skill that is not vendored');
   if (site === PRODUCTION_SITE && cloud === `${PRODUCTION_SITE}/cloud`) return skill;
-  // Only the plain-HTTP local stack serves the Dev app; any HTTPS host keeps the release app.
-  const local = site.startsWith('http:') ? skill
+  // Only the local stack serves the Dev app; every other host keeps the release app.
+  const local = isLocalStack(site) ? skill
     .replaceAll(DESKTOP_RELEASES, `${site}/cloud/desktop-downloads`)
     .replaceAll('AgentRelay-macOS-', 'AgentRelay-Dev-macOS-')
     .replaceAll('Agent Relay.app', 'Agent Relay Dev.app')
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 6b78885a..29eff5fb 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -155,8 +155,8 @@ describe('agent signup instructions', () => {
     expect(agentSignupPrompt('teams', 'http://127.0.0.1:3199')).toContain('http://127.0.0.1:3199/signup/agent/teams');
   });
 
-  it('keeps the release desktop app for an HTTPS host other than production', async () => {
-    const content = await guide('teams', 'https://preview.example.com/signup/agent/teams');
+  it.each(['https://preview.example.com', 'http://staging.example.com'])('keeps the release desktop app for %s, which is not the local stack', async (origin) => {
+    const content = await guide('teams', `${origin}/signup/agent/teams`);
     expect(content).toContain('relay-desktop-releases/releases/latest/download');
     expect(content).toContain('"$release/AgentRelay-macOS-$relay_arch.dmg"');
     expect(content).not.toContain('Agent Relay Dev.app');

From 36d728dda34e69e8fc40fe3fbfd85a2dee6d3669 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Wed, 7 Oct 2026 23:54:35 -0700
Subject: [PATCH 7/9] build(signup): install the setup skills with prpm instead
 of a custom sync

- prpm.lock pins the @agent-relay setup skills; prpm install writes them to
  .claude/skills/<name>/SKILL.md, as in the relay repo.
- web/scripts/generate-setup-skills.mjs reads the lock and the installed
  files and generates web/lib/generated/setup-skills.ts (prebuild and
  precf:build run it); --check fails when the module drifts.
- CI reinstalls with prpm install --frozen-lockfile and fails if that
  changes prpm.lock or .claude/skills, then runs the check.
- Removes web/scripts/sync-setup-skills.mjs and web/content/setup-skills.

Blocked on publish: signing-in-to-agent-relay-cloud and
setting-up-agent-relay-flows are not on the registry yet, and desktop
1.1.5 / sessions 0.2.5 are unpublished. Once AgentWorkforce/skills#145 merges
and they publish, run prpm install for the two new packages, prpm update,
and npm run skills:generate.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../setting-up-agent-relay-desktop/SKILL.md   | 129 +++-------
 .../setting-up-agent-relay-sessions/SKILL.md  |  48 +---
 .../skills/writing-relayflows/SKILL.md        |   5 +
 .github/workflows/test.yml                    |  10 +
 package.json                                  |   2 +
 prpm.lock                                     |  37 +++
 web/content/setup-skills/SOURCE.json          |  11 -
 .../setting-up-agent-relay-flows.md           | 227 ------------------
 .../signing-in-to-agent-relay-cloud.md        | 113 ---------
 web/lib/agent-signup.ts                       |   4 +-
 web/lib/test/agent-signup.test.ts             |  30 ++-
 web/package.json                              |   2 +
 web/scripts/generate-setup-skills.mjs         |  97 ++++++++
 web/scripts/sync-setup-skills.mjs             |  88 -------
 14 files changed, 216 insertions(+), 587 deletions(-)
 rename web/content/setup-skills/setting-up-agent-relay-desktop.md => .claude/skills/setting-up-agent-relay-desktop/SKILL.md (86%)
 rename web/content/setup-skills/setting-up-agent-relay-sessions.md => .claude/skills/setting-up-agent-relay-sessions/SKILL.md (91%)
 rename web/content/setup-skills/writing-relayflows.md => .claude/skills/writing-relayflows/SKILL.md (98%)
 create mode 100644 prpm.lock
 delete mode 100644 web/content/setup-skills/SOURCE.json
 delete mode 100644 web/content/setup-skills/setting-up-agent-relay-flows.md
 delete mode 100644 web/content/setup-skills/signing-in-to-agent-relay-cloud.md
 create mode 100644 web/scripts/generate-setup-skills.mjs
 delete mode 100644 web/scripts/sync-setup-skills.mjs

diff --git a/web/content/setup-skills/setting-up-agent-relay-desktop.md b/.claude/skills/setting-up-agent-relay-desktop/SKILL.md
similarity index 86%
rename from web/content/setup-skills/setting-up-agent-relay-desktop.md
rename to .claude/skills/setting-up-agent-relay-desktop/SKILL.md
index ed2bf2b7..883cf664 100644
--- a/web/content/setup-skills/setting-up-agent-relay-desktop.md
+++ b/.claude/skills/setting-up-agent-relay-desktop/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: setting-up-agent-relay-desktop
+description: Set up or repair Agent Relay Desktop end-to-end from a running Codex or Claude session on macOS or Linux, including verified installation, headless systemd service, device sign-in, new-session uploads, self-registration, direct delivery, webhooks, GitHub subscriptions, and delivery verification. Use when a human asks an agent to install, configure, or finish desktop relay setup without walking through the app UI.
+---
+
 # Set Up Agent Relay Desktop
 
 Complete the setup through the private session socket. Do not ask the human to
@@ -13,8 +18,7 @@ The finished state is:
 
 - the current release is installed and running;
 - sign-in is complete;
-- sharing mode is `new` (new sessions upload automatically), unless an existing
-  install already uses another mode and the human chose to keep it (section 4);
+- sharing mode is `new` (new sessions upload automatically);
 - auto-activate is on, with every existing live session and every future session on the relay;
 - Claude Code direct delivery is on (`crossSessionInbound` is `accept`);
 - this Codex or Claude session is registered and accepts direct delivery;
@@ -102,18 +106,9 @@ test -S "${relay_socket:-/nonexistent}" && printf 'socket=%s\n' "$relay_socket"
 If the socket exists, inspect it before installing anything:
 
 ```sh
-curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq
+curl -sS --unix-socket "$relay_socket" http://relay/setup/status | jq
 ```
 
-**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
-take about 30 seconds on a busy Desktop (tracked in
-AgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout
-(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's
-`relay socket-request` can give up sooner with "Probe could not finish. Check
-your connection and run setup again"; on these paths that is the same latency,
-not a setup problem. Retry the call once before reporting a blocker, and do not
-start a second install or sign-in because of it.
-
 Preserve a working newer install. When the socket is absent, check for an
 installed-but-stopped copy before downloading: use `dpkg-query -W agent-relay`
 when `dpkg-query` exists and `systemctl --user status agent-relay.service` on
@@ -233,7 +228,7 @@ esac
 relay_unit="$HOME/.config/systemd/user/agent-relay.service"
 relay_installed_version=
 if test -S "${relay_socket:-/nonexistent}"; then
-  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket "$relay_socket" \
+  relay_installed_version=$(curl -fsS --unix-socket "$relay_socket" \
     http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)
 fi
 if test -z "$relay_installed_version" && test -r "$relay_unit"; then
@@ -345,7 +340,7 @@ if ! test -S "$relay_socket" && test "$(uname -s)" = Linux; then
   relay_socket="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock"
 fi
 test -S "$relay_socket"
-curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
+curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
 ```
 
 ## 3. Sign in by device approval
@@ -355,7 +350,7 @@ only read state. The CLI checks run only when section 2 found a `relay_cli`;
 never call the `.deb`'s `/usr/bin/agent-relay` launcher for them:
 
 ```sh
-curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{sign_in: .data.sign_in, workspace: .data.workspace}'
 if test -n "${relay_cli:-}"; then
   "$relay_cli" cloud whoami       # signed in, and as whom
@@ -377,7 +372,7 @@ human has confirmed that the reusable login's current workspace is intended.
 ```sh
 relay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'
 sign_in_payload=$(jq -nc --arg workspace "$relay_workspace_uuid" '{workspace:$workspace}')
-sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -396,7 +391,7 @@ acknowledgement added; never use it merely to suppress the error:
 ```sh
 sign_in_payload=$(printf '%s\n' "$sign_in_payload" | \
   jq '. + {acknowledge_uninspected_schedules:true}')
-sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -439,7 +434,7 @@ print it, and map the known messages to their fix instead of dumping raw state:
 
 ```sh
 while :; do
-  state=$(curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status)
+  state=$(curl -sS --unix-socket "$relay_socket" http://relay/setup/status)
   phase=$(printf '%s' "$state" | jq -r '.data.sign_in // .error.code')
   case "$phase" in
     signed_in)
@@ -467,52 +462,13 @@ done
 
 ## 4. Apply the agent-led defaults and register this session
 
-Read the current sharing mode before changing it. `/setup/status` reports it as
-`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is
-uploading yet). The probe reports the same field, `sharing_mode`, in
-`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.
-
-```sh
-relay_prior_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
-  http://relay/setup/status | jq -r '.data.sharing_mode // empty')
-case "$relay_prior_mode" in
-  new|all|selected) printf 'sharing_mode=%s\n' "$relay_prior_mode" ;;
-  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\n' >&2
-     exit 1 ;;
-esac
-```
-
-Continue only with a verified `new`, `all`, or `selected`. If the status read
-fails or reports no mode, retry once; if it is still unknown, stop and ask the
-human how to proceed rather than sending any sharing request.
-
-On a fresh install, or when it already reports `new`, keep `new`. When an
-existing install reports `all` (which also uploads past sessions, so it is
-broader than this skill's default) or `selected`, tell the human the current
-mode and ask whether to keep it or change it to `new`. Never change it silently.
-Only when the human explicitly chooses a different mode, set
-`relay_sharing_mode` to that answer at the top of the next block; left unset,
-the block keeps the mode the app reports, so nothing changes without an answer.
-Remember the chosen mode: section 8 checks it again, and shell variables do not
-survive between separate tool calls.
-
-Then set and verify all three agent-led defaults even when the app's `/setup/*`
+Set and verify all three agent-led defaults even when the app's `/setup/*`
 bootstrap already applied them. Sharing mode `new` uploads every new session;
 auto-activation puts every existing live session and every future session on
 the relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:
 
 ```sh
-# Unset keeps the current mode; set it only to the human's explicit answer.
-if test -z "${relay_sharing_mode:-}"; then
-  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
-    http://relay/setup/status | jq -r '.data.sharing_mode // empty')
-fi
-case "$relay_sharing_mode" in
-  new|all|selected) ;;
-  *) printf 'Sharing mode unknown; ask the human before changing sharing.\n' >&2
-     exit 1 ;;
-esac
-direct_delivery=$(curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+direct_delivery=$(curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' http://relay/setup/direct-delivery)
 printf '%s\n' "$direct_delivery" | jq
 if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; then
@@ -521,17 +477,16 @@ if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; t
   fi
   exit 1
 fi
-curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
-  -d "$(jq -nc --arg mode "$relay_sharing_mode" '{mode:$mode}')" \
-  http://relay/setup/sharing | jq
-curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d '{"mode":"new"}' http://relay/setup/sharing | jq
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' \
   http://relay/setup/auto-activate | jq
-register=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+register=$(curl -sS --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d '{}' http://relay/register)
 printf '%s\n' "$register" | jq
-registration_status=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+registration_status=$(curl -sS --unix-socket "$relay_socket" \
   http://relay/setup/status)
 printf '%s\n' "$registration_status" | \
   jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'
@@ -540,26 +495,11 @@ printf '%s\n' "$registration_status" | jq -e \
    .data.session.registered == true and .data.session.direct_delivery == true'
 ```
 
-**Codex on macOS.** The system `curl` hides a Codex session's identity from the
-socket there, so `/register` is refused `not_a_relay_session` (section 6 says
-the same for subscriptions). In a Codex session on macOS, find `relay_probe`
-with section 6's first block and send the registration through it instead of
-the `curl` line above, then read `/setup/status` as above:
-
-```sh
-register=$(printf '{}' | "$relay_probe" relay socket-request \
-  --socket "$relay_socket" --method POST --path /register)
-```
-
-If `/setup/sign-in` is refused the same way, send its payload through the probe
-the same way. Without a probe, stop and report it rather than registering
-another process.
-
 Direct delivery is checked first so a managed-policy refusal stops setup
 before auto-activation or upload settings are changed. Report that refusal
 clearly; never claim the three-default setup completed.
 
-Sharing mode and auto-activate are different settings: the former
+Sharing mode `new` and auto-activate are different settings: the former
 controls upload eligibility and the latter controls Relay registration. The
 setup flow requires both.
 
@@ -585,7 +525,7 @@ Capture the one-time secret without echoing it:
 ```sh
 umask 077
 hook_file=$(mktemp)
-curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{}' http://relay/webhooks >"$hook_file"
 jq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' "$hook_file"
 ```
@@ -696,10 +636,10 @@ relay_req() {  # METHOD PATH [JSON body]
     printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\n' >&2
     return 1
   elif test -n "${3:-}"; then
-    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
+    curl -sS --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' -d "$3" "http://relay$2"
   else
-    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 
@@ -846,22 +786,19 @@ agent acted only once.
 Read status again:
 
 ```sh
-curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'
 ```
 
-Require all three defaults before declaring setup complete. Set
-`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the
-existing mode the human kept); the check refuses to guess it:
+Require all three defaults before declaring setup complete:
 
 ```sh
-: "${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}"
-curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
-  jq -e --arg mode "$relay_sharing_mode" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'
+curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq -e '.ok and .data.sharing_mode == "new" and .data.auto_activate == true and .data.direct_delivery == true'
 ```
 
 Report the exact version, `signed_in`, signed-in workspace id and name, sharing
-mode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,
+mode `new`, auto-activate `true`, direct-delivery `true`,
 uploader health, session address, direct-delivery state, webhook test marker,
 subscriptions, real GitHub event evidence, and polling-coexistence result.
 Separate verified facts from steps that still require a human or external
@@ -871,9 +808,7 @@ event.
 
 - **Socket missing or slow:** check `systemctl --user status agent-relay.service`
   on Linux or `open -a "Agent Relay"` on macOS. Confirm the pointer names a
-  socket. Never delete a live socket; restart the owning service/app. A reply
-  that takes up to about 30 seconds is the known latency in section 1
-  (relay-desktop#333), not a fault: allow 60 seconds and retry once.
+  socket. Never delete a live socket; restart the owning service/app.
 - **`not_a_relay_session`:** the command is not a descendant of a supported
   live Codex/Claude session, or the session id/process start no longer matches.
   Run it through this agent's shell tool. In tmux, confirm the agent process and
@@ -931,7 +866,7 @@ event.
 - **Managed Claude policy:** if direct delivery reports `managed_policy`, the
   organization controls `crossSessionInbound`; report the policy block rather
   than modifying managed settings.
-- **Undo registration:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
+- **Undo registration:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
 - **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,
   `relay_req`, and `pr_resources` defined, remove every subscription the
   session holds for the pull request, in whichever form it was made. On macOS
@@ -949,7 +884,7 @@ event.
   ```
 
   Require the final list to hold none of that pull request's resources.
-- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
+- **Undo a webhook:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
 - **Undo direct delivery:** POST `{"enabled":false}` to
   `/setup/direct-delivery`. On Claude this restores the local opt-out; managed
   organization policy still wins.
diff --git a/web/content/setup-skills/setting-up-agent-relay-sessions.md b/.claude/skills/setting-up-agent-relay-sessions/SKILL.md
similarity index 91%
rename from web/content/setup-skills/setting-up-agent-relay-sessions.md
rename to .claude/skills/setting-up-agent-relay-sessions/SKILL.md
index 4ca07728..331b4933 100644
--- a/web/content/setup-skills/setting-up-agent-relay-sessions.md
+++ b/.claude/skills/setting-up-agent-relay-sessions/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: setting-up-agent-relay-sessions
+description: Get a person set up for live agent-to-agent session handoff on Agent Relay end-to-end from a running Codex or Claude session, so their agent and a teammate's agent can message each other and read each other's real sessions (prompts, events, tool calls, file edits). Covers verifying desktop setup, installing the agent-sessions cloud MCP before the session starts, confirming the handoff tools loaded, and proving one live round trip. Use when a human asks an agent to "set me up for session handoff", "connect my agent to <teammate>", or finish the onboarding we send new teammates — instead of walking them through the app and the dashboard by hand.
+---
+
 # Set Up Agent Relay Session Handoff
 
 Drive the whole onboarding from this agent's own shell and MCP tools. Do **not**
@@ -156,20 +161,13 @@ Before sending that message, check what this machine already has. If an Agent
 Relay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not
 the `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only
 checks. Without one, section 2 reads the signed-in workspace from
-`/setup/status` instead. The CLI is optional for this skill: detect it as
-below, which skips the Desktop launcher that `command -v agent-relay` finds on
-a `.deb` install, and do not install or upgrade it just for these checks.
+`/setup/status` instead.
 
 ```sh
-relay_cli=$(command -v agent-relay || true)
-case "$relay_cli" in ''|/usr/bin/agent-relay) relay_cli= ;; esac
-if test -n "$relay_cli"; then
-  "$relay_cli" --version
-  "$relay_cli" cloud whoami       # signed in, and as whom
-  "$relay_cli" workspace active   # the active Cloud workspace (keys stay masked)
-  "$relay_cli" cloud workspaces   # every workspace this login can use, with ids
-  "$relay_cli" status             # workspace, cloud login and local broker
-fi
+agent-relay cloud whoami       # signed in, and as whom
+agent-relay workspace active   # the active Cloud workspace (keys stay masked)
+agent-relay cloud workspaces   # every workspace this login can use, with ids
+agent-relay status             # workspace, cloud login and local broker
 ```
 
 If the active workspace is already the shared one, confirm it with the person
@@ -249,23 +247,14 @@ relay_req() {
     return 1
   elif test -n "${3:-}"; then
     # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename
-    printf '%s' "$3" | curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
+    printf '%s' "$3" | curl -sS --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' --data-binary @- "http://relay$2"
   else
-    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 ```
 
-**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
-take about 30 seconds on a busy Desktop (tracked in
-AgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add
-`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a
-failure. The probe's `relay socket-request` can give up sooner with "Probe
-could not finish. Check your connection and run setup again"; on these paths
-that is the same latency, not a setup problem. Retry once before reporting a
-blocker, and do not rerun desktop setup because of it.
-
 ## 2. Make sure the desktop is set up first
 
 Session handoff needs a signed-in, healthy desktop underneath it. If the socket
@@ -283,7 +272,6 @@ relay_req GET /setup/status | jq '{
   version: .data.version,
   sign_in: .data.sign_in,
   workspace: .data.workspace,
-  sharing_mode: .data.sharing_mode,
   uploader: .data.uploader,
   direct_delivery: .data.direct_delivery,
   session: .data.session,
@@ -316,17 +304,6 @@ read **this** person's session, this machine must have uploaded it. If
 anyone can read this session — this is the single most common reason a live
 handoff silently fails.
 
-`sharing_mode` decides which sessions upload at all, and a healthy uploader
-does not prove that **this** session is among them. `all` includes it. `new`
-includes sessions that started after `new` was enabled, so a session that was
-already running when the desktop was set up may not be uploaded. Under
-`selected`, only the sessions the person chose upload. Unless the mode is
-`all`, tell the person that this session may not be shared yet, and ask them to
-select it in the app or to continue from a new session; do not change the
-sharing mode or select sessions on their behalf. Section 5's round trip is the
-proof: if the teammate cannot read this session there, this is the first
-thing to check.
-
 ## 3. Install the agent-sessions cloud MCP (before the session uses it)
 
 Check whether the token is present in the environment **without printing it**
@@ -436,7 +413,6 @@ without a second person:
    citation link) — the uploader→read path works.
 3. Record that the two-party round trip still needs the teammate online, and
    name it as the remaining step rather than claiming the handoff is proven.
-   Setup is not complete until the full round trip succeeds.
 
 Never paste the Bearer token or any session token into a `send_relay_message`
 body or any artifact.
diff --git a/web/content/setup-skills/writing-relayflows.md b/.claude/skills/writing-relayflows/SKILL.md
similarity index 98%
rename from web/content/setup-skills/writing-relayflows.md
rename to .claude/skills/writing-relayflows/SKILL.md
index 2ebed493..4c027076 100644
--- a/web/content/setup-skills/writing-relayflows.md
+++ b/.claude/skills/writing-relayflows/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: writing-relayflows
+description: Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the journal-based v2 engine — the CLI is `flows`, package versions 2.0.x) in TypeScript or YAML/JSON. Covers the run/llm/agent ladder, direct child flows with use/dispatch, verification gates, cli/model selection, flows.json, parallel agents, Cloud dashboard mirroring, and `flows check`/`run`/`deploy`/`schedule` refusal shapes. Not for the older, unrelated `@relayflows/core` WorkflowBuilder engine (`.pattern('dag')`/.agent()/.step() chains) covered by `writing-agent-relay-workflows` and `migrating-persona-to-relayflow`.
+---
+
 # Writing Relayflows
 
 ## Overview
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4b63b7d9..3510e309 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -40,6 +40,16 @@ jobs:
       - name: Verify recommended-flow release pins
         run: npm run verify:recommended-flows
 
+      # The setup skills the signup guides render come from prpm, pinned in
+      # prpm.lock. Reinstalling from the lock must not change the committed
+      # copies (the lock's own "generated" timestamp aside), and the bundled
+      # module must match them.
+      - name: Verify setup skills are current
+        run: |
+          npx --yes prpm@2.1.40 install --frozen-lockfile -y
+          git diff --exit-code -I '"generated"' -- prpm.lock .claude/skills
+          npm run verify:setup-skills
+
       # Root script fans out to every workspace (web + router), so a new
       # workspace is covered automatically.
       - name: Run tests
diff --git a/package.json b/package.json
index 7722a8aa..8ea91ba4 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,8 @@
     "test": "npm --workspaces run test",
     "verify:catalog-gates": "node web/scripts/verify-catalog-gates.mjs",
     "verify:recommended-flows": "npm run verify:catalog-gates && node web/scripts/verify-recommended-flow-catalog.mjs",
+    "skills:generate": "node web/scripts/generate-setup-skills.mjs",
+    "verify:setup-skills": "node web/scripts/generate-setup-skills.mjs --check",
     "preview": "npm --workspace web run preview",
     "dev:teams": "CLOUD_DEV_ORIGIN=http://127.0.0.1:3101 npm --workspace web run dev -- --hostname 127.0.0.1 --port 3100"
   }
diff --git a/prpm.lock b/prpm.lock
new file mode 100644
index 00000000..ef8f3ed4
--- /dev/null
+++ b/prpm.lock
@@ -0,0 +1,37 @@
+{
+  "version": "1.0.0",
+  "lockfileVersion": 1,
+  "packages": {
+    "@agent-relay/setting-up-agent-relay-desktop#claude": {
+      "version": "1.1.4",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-desktop/1.1.4.tar.gz",
+      "integrity": "sha256-de1fa4fb20e2a3d02e4cd86bd32a2f3bc3a6a5276a81e0bbc5c114325f5385bf",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/setting-up-agent-relay-desktop/SKILL.md"
+    },
+    "@agent-relay/setting-up-agent-relay-sessions#claude": {
+      "version": "0.2.4",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-sessions/0.2.4.tar.gz",
+      "integrity": "sha256-58021adb458e33c571c92fcf91032466b9653f236323bbf283044b68ba9a3a6e",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/setting-up-agent-relay-sessions/SKILL.md"
+    },
+    "@agent-relay/writing-relayflows#claude": {
+      "version": "1.6.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fwriting-relayflows/1.6.0.tar.gz",
+      "integrity": "sha256-437a96cbc7fba1e9d0640d08dcedd5182fd83905a859417bea4e46f622a58639",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/writing-relayflows/SKILL.md"
+    }
+  },
+  "generated": "2026-10-08T06:50:15.717Z"
+}
\ No newline at end of file
diff --git a/web/content/setup-skills/SOURCE.json b/web/content/setup-skills/SOURCE.json
deleted file mode 100644
index 157aa85b..00000000
--- a/web/content/setup-skills/SOURCE.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "repository": "AgentWorkforce/skills",
-  "commit": "d2e5a3ecfbfdd7b64c6775b3c452c99b06e62fd6",
-  "skills": [
-    "signing-in-to-agent-relay-cloud",
-    "setting-up-agent-relay-desktop",
-    "setting-up-agent-relay-sessions",
-    "setting-up-agent-relay-flows",
-    "writing-relayflows"
-  ]
-}
diff --git a/web/content/setup-skills/setting-up-agent-relay-flows.md b/web/content/setup-skills/setting-up-agent-relay-flows.md
deleted file mode 100644
index 48b7ef47..00000000
--- a/web/content/setup-skills/setting-up-agent-relay-flows.md
+++ /dev/null
@@ -1,227 +0,0 @@
-# Set Up Agent Relay Flows
-
-Drive the setup through the documented Cloud APIs and the official CLI. Do not
-use computer use, browser automation, or the dashboard UI. The human approves
-sign-in, tool consent, and provider logins on their own approval pages; open
-those links with the OS URL opener (or give them the link), then verify by
-polling the API, never by inspecting the browser.
-
-Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
-including its `/cloud` prefix; the site is `https://agentrelay.com`. The flow
-catalog is the one exception: it is a site API, served from the site origin
-without `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a
-guide names a different site and Cloud base (for example a local development
-stack), use those exact origins throughout, including for the catalog, the
-CLI's `--api-url` and the dashboard links, and never fall back to production.
-Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
-
-## Requires
-
-A signed-in Cloud session: an access token and the `user.id` and
-`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`
-first. Send `Authorization: Bearer <access_token>` only to the Cloud API
-endpoints below. Never send it to the site's flow catalog or to a catalog
-`source.rawUrl`; fetch those without credentials.
-
-## API map
-
-- Flow catalog (site origin, not under `/cloud`):
-  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.
-- Tool consent links: `POST /api/v1/integrations/connect-link`; poll
-  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.
-- Coding-agent credentials: the official CLI's `cloud connect` (section 3);
-  `GET /api/v1/cloud-agents` inspects existing connections.
-- Activation: `POST /api/v1/flows/deploy` with the body in section 4.
-- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`
-  reports whether it is available.
-- Verification: `GET /api/v1/flows/listeners/<agentId>`.
-
-## 1. Prebuilt or custom?
-
-Ask the human first, unless their request already says: a **prebuilt** flow
-from the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**
-flow of their own? In an agent-driven signup, ask through that guide's
-web-input protocol on the signup page, not in chat.
-
-- Prebuilt: continue with section 2.
-- Custom: follow **Custom flow: deploy journey** below. A custom flow is
-  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and
-  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is
-  no separate custom API.
-
-## 2. Choose the flow and repository
-
-Ask the human for missing product choices: repository, desired
-workflow/trigger, and approver. In an agent-driven signup, ask through that
-guide's web-input protocol on the signup page, not in chat. Ask for the approver's
-GitHub username in plain language (for example, "octocat" or "@octocat"),
-not an internal provider-address format or their Google email. Normalize the
-answer to github:@handle when constructing the deploy API request. Human-gate
-replies are matched to that provider identity. Infer choices from the user's request and current
-repository where clear.
-Do not invent a repository or enable automation on an unrelated project.
-
-GET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.
-GET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
-kind before doing anything executable: only an entry with kind: flow (or a
-legacy entry with kind omitted) is deployable through the direct-source API
-below. An entry with kind: extension is discoverable metadata, not a standalone
-listener. Do not download or deploy its source, even when it declares trigger
-and input fields. Inspect baseFlowId and extension.activation instead. If the
-extension is blocked, report the unmet dependencies and that it can only be
-added to its base flow after a supported extension activation path is available;
-never substitute a standalone flow deployment.
-
-For a deployable flow, use the catalog's
-supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
-inputs.allowedAgents. Name a model per harness in inputs.models when the house
-default is wrong (for example {"claude": "claude-sonnet-4"}); omit it to fund
-the house default for each declared agent. Download source.rawUrl, verify its bytes against
-source.sha256, and use that source text unchanged for a recommended flow.
-The source is TypeScript, not the source URL. Do not guess a template or hash.
-
-## Custom flow: deploy journey
-
-There is no journey API. A `journey_id` (for example in a
-`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it
-through unchanged where you received it, and never call an endpoint with it or
-wait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`
-as a prebuilt one; only where the source comes from differs.
-
-1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,
-   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that
-   skill for the flow's shape and checks; Flows are always v2. Cloud's
-   prompt generator is an optional shortcut: use it only when
-   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it
-   reports unavailable, refuses your session (403 `session_required`), or
-   fails, author with `writing-relayflows` instead; do not retry into it.
-2. Choose its repository, trigger and approver as in section 2.
-3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the
-   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent
-   only when the prompt generator produced one. `base` and `extensions` are
-   optional and only for a flow that names them.
-
-The human-only steps are the same for both paths: Google sign-in and device
-approval, GitHub and trigger-app OAuth including the repository grants,
-model-provider login when section 3 calls for one (not for an ordinary first
-activation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.
-
-## 3. Connect the required tools and coding agents
-
-Use bearer-authenticated POST /api/v1/integrations/connect-link:
-
-```json
-{"provider":"github","workspaceId":"<currentWorkspace.id>"}
-```
-
-Open the returned connectUrl for the user to approve. Keep token/sessionToken
-private. Connect only the repository and tools the chosen flow requires.
-For GitHub the user must grant repository access. Repeat with the chosen trigger
-provider if different. Reuse existing ready connections rather than relinking.
-Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
-until oauth.connected is true (poll with backoff and a bounded timeout); a
-returned connect link or a closed popup alone does not prove the connection.
-For the GitHub-triggered Software Garden flow, activation separately checks
-that the connected GitHub App covers the selected repository. Its trigger
-does not require background data indexing, so do not block solely because
-the broader status.ready is false from queued syncs.
-If a different flow declares Relayfile data that requires synced records,
-verify that readiness separately before activating it.
-
-Do not connect a Claude or Codex subscription yet. The first three runs use
-Cloud's own model key, so no provider login is needed to activate. If the chosen
-flow declares more than one coding agent (the catalog's `inputs.defaults.agents`,
-which becomes `inputs.agents` in the deploy body), included Cloud runs
-can fund only one of them per run — connect your own subscription for at least
-one declared agent before activating a multi-agent flow. After the included
-runs, activation and launches will ask for your own subscription; only then use
-the official Relay CLI with the private credential environment from
-`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:
-
-This promotion depends on Cloud's internal house-key proxy and account
-enrollment. If local activation returns flow_credentials_unavailable or
-flow_model_not_connected before the three promotional runs, treat it as an
-internal configuration or eligibility issue. Do not ask the user to connect
-Claude/Codex, provide an API key, or choose an inactive draft as a workaround.
-Report the blocker (in a signup, through its Progress API) and have an internal developer
-verify the proxy, promotion flag, provider readiness, and enrollment. Never
-copy a house key into the agent environment or expose it in this guide.
-
-```sh
-npx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'
-```
-
-Use anthropic for Claude or openai for Codex, according to the selected flow.
-The command drives provider login; open its authorization URL for the user,
-and keep the process alive until it confirms the credential is connected.
-Google approval does not grant GitHub or model-provider access: those services
-may require their own consent. Never fabricate credentials or claim consent
-happened. GET /api/v1/cloud-agents lets you inspect the account's credential
-state without reconnecting.
-
-## 4. Activate through the same API as web onboarding
-
-POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
-session. The token must be the device-flow session from
-`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with
-`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the
-browser onboarding handoff: source is TypeScript text, repository is singular,
-and sources contains provider/settings objects. The catalog supplies the source
-reference and defaults; it is not itself a deploy request. The current endpoint
-does not accept a flowId/repositories-only catalog activation request or fetch
-the source for you. For multiple repositories, submit one deployment per
-repository with a distinct name and handoffId.
-
-For the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the
-workspace, verified source, repository, GitHub approver and a new UUID:
-
-```json
-{
-  "workspaceId": "<currentWorkspace.id>",
-  "name": "Software Garden",
-  "workflow": "software-factory",
-  "source": "<verified TypeScript source text>",
-  "handoffId": "<one UUID generated for this setup>",
-  "inputs": {"approver": "github:@octocat", "agents": ["claude"]},
-  "mode": "activate",
-  "repository": {"owner": "acme", "name": "api"},
-  "sources": [{"provider": "github", "settings": {"repository": "acme/api"}}]
-}
-```
-
-For another deployable kind: flow catalog entry use its id as workflow, allowed agents, and
-defaultTrigger for sources, then apply the user's trigger settings. Scope a
-GitHub issue trigger with settings.repository set to the chosen owner/name;
-for GitLab use settings.project. Cloud does not derive this filter from the
-deployment repository. An empty filter can trigger on other repositories in
-the workspace. Only use a different trigger scope when explicitly requested.
-Give each repository its own trigger filter for multi-repository setup. Do not send
-the example acme repository or octocat approver unchanged. The workflow field
-is a label, not a source lookup; keep the verified source in the request.
-For GitLab set repository.host to gitlab and use the namespace path
-as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
-failure, GET /api/v1/flows/listeners and check whether the flow already exists;
-do not create a new ID/name on every retry. Activation subscribes to matching
-future events and can run work; confirm the intended repository and trigger
-with the user if they have not specified them.
-
-HTTP 201 must contain agentId and status: listening. A draft is not completion.
-For a 409 workspace_mismatch, verify the active workspace; for connection
-preflight failures, fix the indicated connection before retrying. If the user
-wants to save incomplete work, use mode: draft explicitly and report that it
-is inactive. Never mask activation failures by silently falling back to draft.
-
-## 5. Verify
-
-GET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and
-verify its repository and sources match the request. Open
-https://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,
-workspace, repository, trigger, and verified listening state. This proves
-activation; only an actual completed run proves execution. Do not create a
-real issue or launch paid work merely to make the onboarding check turn green.
-Delete temporary authentication files after the work is complete.
-
-The desktop app is optional for Flows. If the user also wants local session
-sharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`
-with the same account (an agent-driven signup can follow
-https://agentrelay.com/signup/agent/teams).
diff --git a/web/content/setup-skills/signing-in-to-agent-relay-cloud.md b/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
deleted file mode 100644
index 05b2e5ea..00000000
--- a/web/content/setup-skills/signing-in-to-agent-relay-cloud.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Sign In to Agent Relay Cloud
-
-Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
-or pre-existing Agent Relay account is required. Only the human approves the
-sign-in; never approve access on their behalf, ask for their password, or
-operate the approval page yourself.
-
-Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
-including its `/cloud` prefix. When a guide names a different Cloud base (for
-example a local development stack), use that exact base throughout and never
-fall back to production.
-
-## HTTP client
-
-Use `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their
-default User-Agent: the device-token endpoint answers them with HTTP 403 and no
-JSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth
-response while debugging; on success it contains tokens. Send JSON request
-bodies with `Content-Type: application/json`, set a 30-second request timeout,
-and check every response status before proceeding.
-
-## 1. Start the device grant
-
-`POST /api/v1/auth/device/start` with:
-
-```json
-{"client_name":"My agent setup"}
-```
-
-An agent-driven signup guide also passes its product as `signup_source`
-(`"teams"` or `"flows"`); keep the value the guide names. Omit it otherwise.
-
-Expect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,
-`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep
-`device_code` private. Open `verification_uri_complete` in the person's
-browser with the OS URL opener (for example macOS `open`, with the URL passed as
-a separate argument, never interpolated into shell code), or give them the link
-if no opener is available. Show the `user_code` so they can compare it. The page
-lets them sign in with Google, review the requesting device, and Approve or
-Deny. A signup marker in the returned URL creates the right account type;
-preserve it through sign-in. Do not call `/auth/device/approve` yourself.
-
-For a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`
-on the same Cloud base first (in production,
-`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of
-`verification_uri_complete`. This opens Google immediately and returns to the
-same device approval with its code and signup marker intact. Never open the
-production URL for a non-production base: that would sign the human in to
-production instead.
-
-## 2. Poll for tokens
-
-While the browser is open, wait `interval` seconds between POSTs to
-`/api/v1/auth/device/token` with this JSON (substitute the private
-`device_code`):
-
-```json
-{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}
-```
-
-- `authorization_pending`: keep waiting; respect a returned interval.
-- `slow_down`: increase the interval by at least 5 seconds.
-- HTTP 429: respect `Retry-After` and increase the interval.
-- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.
-- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start
-  a new grant only if the person still wants to continue. Never poll past
-  expiry.
-
-HTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,
-`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in
-memory or a private file (directory 0700, file 0600) outside repositories.
-Never echo tokens, put them in chat or URLs, or dump full authentication
-responses. Use `Authorization: Bearer <access_token>` for subsequent Cloud
-requests. Reject an `api_url` pointing at another origin; keep using the Cloud
-base above.
-
-## 3. Refresh before expiry
-
-Before expiry, `POST /api/v1/auth/token/refresh` with
-`{"refreshToken":"<refresh_token>"}`. The response uses camelCase:
-`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,
-`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the
-refresh token rotates and must not be shared between machines. An
-invalid/expired refresh requires a new device login, not an endless retry.
-
-## 4. Read the account and workspace
-
-`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,
-`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups
-create a workspace automatically. Reuse it; do not create duplicate
-accounts/workspaces. If `currentWorkspace` is missing, or an existing account
-is in the wrong workspace, resolve that with the person before connecting or
-activating anything. Never silently replace an existing connection to another
-account.
-
-## 5. Hand the session to the official CLI
-
-When running a child process, pass these through its environment from your
-private session object (never interpolate their values into logged commands):
-
-```text
-CLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>
-CLOUD_API_ACCESS_TOKEN=<access_token>
-CLOUD_API_REFRESH_TOKEN=<refresh_token>
-CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
-CLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>
-```
-
-The official CLI consumes this session. Refresh the parent session before
-starting a long command; do not concurrently refresh it from parent and child
-processes. Do not overwrite an existing CLI auth file or copy a session to
-another machine. Delete temporary authentication files after the work is
-complete.
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 18ecffc7..0e64570a 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -53,9 +53,9 @@ HTTP status, never the body.
 
 This header holds only what is specific to signup. The setup steps are the
 canonical Agent Relay skills from https://github.com/AgentWorkforce/skills,
-included below verbatim at commit ${SETUP_SKILLS_SOURCE.commit}:
+included below verbatim as published to the prpm registry:
 
-${parts.map((part, index) => `- Part ${index + 1}: ${part.label} (${part.skill})`).join('\n')}
+${parts.map((part, index) => `- Part ${index + 1}: ${part.label} (@agent-relay/${part.skill}@${(SETUP_SKILLS_SOURCE.packages as Readonly<Record<string, string>>)[part.skill]})`).join('\n')}
 
 Follow the parts in order${product === 'flows' ? ' (Part 3 is a reference, read only for a custom flow)' : ''}. Where a part says to ask the human, ask the user
 ${product === 'flows' ? 'through the web-input protocol below, not in chat' : 'in your conversation with them'}.
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 29eff5fb..a06ee613 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -5,10 +5,13 @@ import { agentSignupPrompt } from '../agent-signup';
 import { SETUP_SKILLS, SETUP_SKILLS_SOURCE } from '../generated/setup-skills';
 import { getRecommendedFlow } from '../recommended-flow-catalog';
 // @ts-expect-error -- plain .mjs build script without type declarations
-import { renderModule, stripFrontmatter } from '../../scripts/sync-setup-skills.mjs';
+import { readInstalledSkills, renderModule, SETUP_SKILL_NAMES, stripFrontmatter } from '../../scripts/generate-setup-skills.mjs';
 
-const vendored = (name: string) => readFileSync(new URL(`../../content/setup-skills/${name}.md`, import.meta.url), 'utf8');
-const pin = JSON.parse(readFileSync(new URL('../../content/setup-skills/SOURCE.json', import.meta.url), 'utf8'));
+const repoRoot = new URL('../../../', import.meta.url);
+const lockText = readFileSync(new URL('prpm.lock', repoRoot), 'utf8');
+const lock = JSON.parse(lockText);
+const entry = (name: string) => lock.packages[`@agent-relay/${name}#claude`];
+const installed = (name: string) => stripFrontmatter(readFileSync(new URL(entry(name).installedPath, repoRoot), 'utf8'));
 const guide = async (product: string, url = `https://agentrelay.com/signup/agent/${product}`) =>
   (await GET(new Request(url), { params: Promise.resolve({ product }) })).text();
 
@@ -45,19 +48,20 @@ describe('agent signup instructions', () => {
     }
   });
 
-  it('vendors exactly the pinned skills, with frontmatter stripped', () => {
-    expect(pin.repository).toBe('AgentWorkforce/skills');
-    expect(pin.commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(SETUP_SKILLS_SOURCE).toEqual({ repository: pin.repository, commit: pin.commit });
-    expect(Object.keys(SETUP_SKILLS)).toEqual(pin.skills);
-    for (const name of pin.skills) {
-      expect(SETUP_SKILLS[name]).toBe(vendored(name));
+  it('bundles exactly the prpm-installed skills pinned in prpm.lock, with frontmatter stripped', async () => {
+    const versions = Object.fromEntries(SETUP_SKILL_NAMES.map((name: string) => [name, entry(name).version]));
+    expect(SETUP_SKILLS_SOURCE).toEqual({ registry: 'prpm', packages: versions });
+    expect(Object.keys(SETUP_SKILLS)).toEqual(SETUP_SKILL_NAMES);
+    for (const name of SETUP_SKILL_NAMES) {
+      expect(entry(name).resolved).toMatch(/^https:\/\/registry\.prpm\.dev\//);
+      expect(SETUP_SKILLS[name]).toBe(installed(name));
       expect(SETUP_SKILLS[name].startsWith('# ')).toBe(true);
       expect(SETUP_SKILLS[name]).not.toMatch(/^---\nname:/);
     }
-    // The generated module is exactly what the sync script renders from the copies.
+    // The generated module is exactly what the generator renders from the installed files.
     const generated = readFileSync(new URL('../generated/setup-skills.ts', import.meta.url), 'utf8');
-    expect(generated).toBe(renderModule(pin, Object.fromEntries(pin.skills.map((name: string) => [name, vendored(name)]))));
+    expect(generated).toBe(renderModule(versions, Object.fromEntries(SETUP_SKILL_NAMES.map((name: string) => [name, installed(name)]))));
+    await expect(readInstalledSkills('{"packages":{}}', async () => '')).rejects.toThrow('is not in prpm.lock');
     expect(stripFrontmatter('---\nname: x\ndescription: y\n---\n\n# X\n')).toBe('# X\n');
     expect(() => stripFrontmatter('# X\n')).toThrow('frontmatter');
   });
@@ -67,7 +71,7 @@ describe('agent signup instructions', () => {
     ['flows', ['signing-in-to-agent-relay-cloud', 'setting-up-agent-relay-flows', 'writing-relayflows'], ['Cloud account', 'Flows', 'Custom flow authoring']],
   ])('renders %s as the signup header followed by the skills verbatim, in order', async (product, skills, labels) => {
     const content = await guide(product);
-    expect(content).toContain(`verbatim at commit ${pin.commit}`);
+    expect(content).toContain('verbatim as published to the prpm registry');
     let cursor = 0;
     skills.forEach((name, index) => {
       const part = content.indexOf(`# Part ${index + 1}: ${labels[index]}\n\n${SETUP_SKILLS[name].trim()}\n`, cursor);
diff --git a/web/package.json b/web/package.json
index d0ddf03c..a0a70ca8 100644
--- a/web/package.json
+++ b/web/package.json
@@ -8,10 +8,12 @@
   },
   "scripts": {
     "dev": "next dev --webpack",
+    "prebuild": "node scripts/generate-setup-skills.mjs",
     "build": "next build --webpack",
     "start": "next start",
     "test": "vitest run",
     "test:e2e": "playwright test",
+    "precf:build": "node scripts/generate-setup-skills.mjs",
     "cf:build": "opennextjs-cloudflare build",
     "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview"
   },
diff --git a/web/scripts/generate-setup-skills.mjs b/web/scripts/generate-setup-skills.mjs
new file mode 100644
index 00000000..20c0ff3c
--- /dev/null
+++ b/web/scripts/generate-setup-skills.mjs
@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Generates web/lib/generated/setup-skills.ts, the bundled text that
+// /signup/agent/teams and /signup/agent/flows render (Workers have no
+// filesystem). The skills are written in AgentWorkforce/skills and installed
+// here by prpm: prpm.lock pins each package, and `prpm install` writes its
+// SKILL.md under .claude/skills/. Nothing here is edited by hand.
+//
+//   prpm install @agent-relay/<skill> --as claude -y   # add a skill
+//   prpm update                                        # move the pins
+//   node web/scripts/generate-setup-skills.mjs         # regenerate the module
+//   node web/scripts/generate-setup-skills.mjs --check # fail on drift
+//
+// CI also runs `prpm install --frozen-lockfile` and fails when that changes
+// .claude/skills or prpm.lock, which proves the installed copies are current.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const repoRoot = new URL('../../', import.meta.url);
+const lockUrl = new URL('prpm.lock', repoRoot);
+const generatedUrl = new URL('../lib/generated/setup-skills.ts', import.meta.url);
+
+/** The skills the signup guides render, in AgentWorkforce/skills' @agent-relay scope. */
+export const SETUP_SKILL_NAMES = [
+  'signing-in-to-agent-relay-cloud',
+  'setting-up-agent-relay-desktop',
+  'setting-up-agent-relay-sessions',
+  'setting-up-agent-relay-flows',
+  'writing-relayflows',
+];
+
+export function stripFrontmatter(text) {
+  const match = /^---\n[\s\S]*?\n---\n+/.exec(text);
+  if (!match) throw new Error('SKILL.md is missing YAML frontmatter');
+  return text.slice(match[0].length);
+}
+
+export function renderModule(versions, skills) {
+  const banner = '// Generated by web/scripts/generate-setup-skills.mjs from the prpm-installed\n'
+    + '// @agent-relay setup skills pinned in prpm.lock. Do not edit.\n';
+  return `${banner}export const SETUP_SKILLS_SOURCE = ${JSON.stringify({ registry: 'prpm', packages: versions })} as const;\n\n`
+    + `export const SETUP_SKILLS: Readonly<Record<string, string>> = ${JSON.stringify(skills, null, 2)};\n`;
+}
+
+/** Reads the pinned version and installed SKILL.md of every setup skill, or names what is missing. */
+export async function readInstalledSkills(lockText, readInstalled) {
+  const lock = JSON.parse(lockText);
+  const versions = {};
+  const skills = {};
+  const missing = [];
+  for (const name of SETUP_SKILL_NAMES) {
+    const entry = lock.packages?.[`@agent-relay/${name}#claude`];
+    if (!entry || typeof entry.installedPath !== 'string') {
+      missing.push(`@agent-relay/${name} is not in prpm.lock`);
+      continue;
+    }
+    const text = await readInstalled(entry.installedPath).catch(() => null);
+    if (text === null) {
+      missing.push(`${entry.installedPath} is missing (run prpm install)`);
+      continue;
+    }
+    versions[name] = entry.version;
+    skills[name] = stripFrontmatter(text);
+  }
+  if (missing.length) throw new Error(`Setup skills are not installed:\n${missing.map(line => `  ${line}`).join('\n')}`);
+  return { versions, skills };
+}
+
+async function main() {
+  const check = process.argv.includes('--check');
+  const { versions, skills } = await readInstalledSkills(
+    await readFile(lockUrl, 'utf8'),
+    path => readFile(new URL(path, repoRoot), 'utf8'),
+  );
+  const expected = renderModule(versions, skills);
+  if (check) {
+    const existing = await readFile(generatedUrl, 'utf8').catch(() => null);
+    if (existing !== expected) {
+      console.error(`${generatedUrl.pathname} does not match the prpm-installed setup skills.`);
+      console.error('Run node web/scripts/generate-setup-skills.mjs; never edit the generated module by hand.');
+      process.exit(1);
+    }
+    console.log(`Setup skills match prpm.lock (${Object.entries(versions).map(([name, version]) => `${name}@${version}`).join(', ')}).`);
+    return;
+  }
+  await mkdir(new URL('.', generatedUrl), { recursive: true });
+  await writeFile(generatedUrl, expected);
+  console.log(`Generated the setup skills module from prpm.lock (${SETUP_SKILL_NAMES.length} skills).`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
diff --git a/web/scripts/sync-setup-skills.mjs b/web/scripts/sync-setup-skills.mjs
deleted file mode 100644
index 05b23466..00000000
--- a/web/scripts/sync-setup-skills.mjs
+++ /dev/null
@@ -1,88 +0,0 @@
-#!/usr/bin/env node
-// Vendors the Agent Relay setup skills that /signup/agent/teams and
-// /signup/agent/flows render. The single source of truth is the public
-// AgentWorkforce/skills repository at the commit pinned in
-// web/content/setup-skills/SOURCE.json; nothing here is edited by hand.
-//
-//   node web/scripts/sync-setup-skills.mjs          # fetch the pin, rewrite the copies
-//   node web/scripts/sync-setup-skills.mjs --check  # fail when the copies differ from the pin
-//
-// To move the pin, change "commit" in SOURCE.json and run without --check.
-import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
-
-const contentDir = new URL('../content/setup-skills/', import.meta.url);
-const sourceUrl = new URL('SOURCE.json', contentDir);
-const generatedUrl = new URL('../lib/generated/setup-skills.ts', import.meta.url);
-const SHA = /^[0-9a-f]{40}$/;
-const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
-export function stripFrontmatter(text) {
-  const match = /^---\n[\s\S]*?\n---\n+/.exec(text);
-  if (!match) throw new Error('SKILL.md is missing YAML frontmatter');
-  return text.slice(match[0].length);
-}
-
-export function renderModule(source, skills) {
-  const banner = '// Generated by web/scripts/sync-setup-skills.mjs from the pinned\n'
-    + '// AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.\n';
-  return `${banner}export const SETUP_SKILLS_SOURCE = ${JSON.stringify({ repository: source.repository, commit: source.commit })} as const;\n\n`
-    + `export const SETUP_SKILLS: Readonly<Record<string, string>> = ${JSON.stringify(skills, null, 2)};\n`;
-}
-
-async function readSource() {
-  const source = JSON.parse(await readFile(sourceUrl, 'utf8'));
-  if (source.repository !== 'AgentWorkforce/skills') throw new Error('SOURCE.json repository must be AgentWorkforce/skills');
-  if (!SHA.test(source.commit ?? '')) throw new Error('SOURCE.json commit must be a full 40-character commit SHA');
-  if (!Array.isArray(source.skills) || source.skills.length === 0 || !source.skills.every(name => NAME.test(name))) {
-    throw new Error('SOURCE.json skills must be a non-empty list of skill directory names');
-  }
-  return source;
-}
-
-async function fetchSkill(source, name) {
-  const url = `https://raw.githubusercontent.com/${source.repository}/${source.commit}/skills/${name}/SKILL.md`;
-  for (let attempt = 1; ; attempt += 1) {
-    try {
-      const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-      if (!response.ok) throw new Error(`HTTP ${response.status}`);
-      return stripFrontmatter(await response.text());
-    } catch (error) {
-      if (attempt >= 3) throw new Error(`Could not fetch ${url}: ${error.message}`);
-      await new Promise(resolve => setTimeout(resolve, attempt * 2000));
-    }
-  }
-}
-
-async function main() {
-  const check = process.argv.includes('--check');
-  const source = await readSource();
-  const skills = Object.fromEntries(await Promise.all(source.skills.map(async name => [name, await fetchSkill(source, name)])));
-  const expected = new Map(source.skills.map(name => [new URL(`${name}.md`, contentDir), skills[name]]));
-  expected.set(generatedUrl, renderModule(source, skills));
-
-  // A vendored copy that SOURCE.json no longer lists is stale too.
-  const pinned = new Set(source.skills.map(name => `${name}.md`));
-  const unlisted = (await readdir(contentDir)).filter(file => file.endsWith('.md') && !pinned.has(file));
-
-  if (check) {
-    const stale = unlisted.map(file => new URL(file, contentDir).pathname);
-    for (const [url, text] of expected) {
-      const existing = await readFile(url, 'utf8').catch(() => null);
-      if (existing !== text) stale.push(url.pathname);
-    }
-    if (stale.length) {
-      console.error(`Setup skills differ from AgentWorkforce/skills@${source.commit}:\n${stale.map(path => `  ${path}`).join('\n')}`);
-      console.error('Run node web/scripts/sync-setup-skills.mjs to re-vendor them; never edit the copies by hand.');
-      process.exit(1);
-    }
-    console.log(`Setup skills match AgentWorkforce/skills@${source.commit} (${source.skills.join(', ')}).`);
-    return;
-  }
-  await mkdir(new URL('.', generatedUrl), { recursive: true });
-  for (const [url, text] of expected) await writeFile(url, text);
-  for (const file of unlisted) await rm(new URL(file, contentDir));
-  console.log(`Vendored ${source.skills.length} setup skills from AgentWorkforce/skills@${source.commit}.`);
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

From 435d290369b8677b239c610ed2446f7ec2878505 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Thu, 8 Oct 2026 00:02:27 -0700
Subject: [PATCH 8/9] build(signup): install the published setup skills from
 prpm

prpm install signing-in-to-agent-relay-cloud 0.1.0 and
setting-up-agent-relay-flows 0.1.0; prpm update moves desktop to 1.1.5 and
sessions to 0.2.5 (AgentWorkforce/skills@7d727ee). Regenerated the module.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../setting-up-agent-relay-desktop/SKILL.md   | 124 ++++++++--
 .../setting-up-agent-relay-flows/SKILL.md     | 232 ++++++++++++++++++
 .../setting-up-agent-relay-sessions/SKILL.md  |  43 +++-
 .../signing-in-to-agent-relay-cloud/SKILL.md  | 118 +++++++++
 prpm.lock                                     |  34 ++-
 web/lib/generated/setup-skills.ts             |   6 +-
 6 files changed, 513 insertions(+), 44 deletions(-)
 create mode 100644 .claude/skills/setting-up-agent-relay-flows/SKILL.md
 create mode 100644 .claude/skills/signing-in-to-agent-relay-cloud/SKILL.md

diff --git a/.claude/skills/setting-up-agent-relay-desktop/SKILL.md b/.claude/skills/setting-up-agent-relay-desktop/SKILL.md
index 883cf664..a1b0bc34 100644
--- a/.claude/skills/setting-up-agent-relay-desktop/SKILL.md
+++ b/.claude/skills/setting-up-agent-relay-desktop/SKILL.md
@@ -18,7 +18,8 @@ The finished state is:
 
 - the current release is installed and running;
 - sign-in is complete;
-- sharing mode is `new` (new sessions upload automatically);
+- sharing mode is `new` (new sessions upload automatically), unless an existing
+  install already uses another mode and the human chose to keep it (section 4);
 - auto-activate is on, with every existing live session and every future session on the relay;
 - Claude Code direct delivery is on (`crossSessionInbound` is `accept`);
 - this Codex or Claude session is registered and accepts direct delivery;
@@ -106,9 +107,18 @@ test -S "${relay_socket:-/nonexistent}" && printf 'socket=%s\n' "$relay_socket"
 If the socket exists, inspect it before installing anything:
 
 ```sh
-curl -sS --unix-socket "$relay_socket" http://relay/setup/status | jq
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq
 ```
 
+**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
+take about 30 seconds on a busy Desktop (tracked in
+AgentWorkforce/relay-desktop#333). Give each socket call a 60-second timeout
+(`curl --max-time 60`), and do not treat a slow reply as a failure. The probe's
+`relay socket-request` can give up sooner with "Probe could not finish. Check
+your connection and run setup again"; on these paths that is the same latency,
+not a setup problem. Retry the call once before reporting a blocker, and do not
+start a second install or sign-in because of it.
+
 Preserve a working newer install. When the socket is absent, check for an
 installed-but-stopped copy before downloading: use `dpkg-query -W agent-relay`
 when `dpkg-query` exists and `systemctl --user status agent-relay.service` on
@@ -228,7 +238,7 @@ esac
 relay_unit="$HOME/.config/systemd/user/agent-relay.service"
 relay_installed_version=
 if test -S "${relay_socket:-/nonexistent}"; then
-  relay_installed_version=$(curl -fsS --unix-socket "$relay_socket" \
+  relay_installed_version=$(curl -fsS --max-time 60 --unix-socket "$relay_socket" \
     http://relay/setup/status 2>/dev/null | jq -r '.data.version // empty' || true)
 fi
 if test -z "$relay_installed_version" && test -r "$relay_unit"; then
@@ -340,7 +350,7 @@ if ! test -S "$relay_socket" && test "$(uname -s)" = Linux; then
   relay_socket="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-relay/relay.sock"
 fi
 test -S "$relay_socket"
-curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
+curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | jq -e '.ok and (.data.version | length > 0)'
 ```
 
 ## 3. Sign in by device approval
@@ -350,7 +360,7 @@ only read state. The CLI checks run only when section 2 found a `relay_cli`;
 never call the `.deb`'s `/usr/bin/agent-relay` launcher for them:
 
 ```sh
-curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{sign_in: .data.sign_in, workspace: .data.workspace}'
 if test -n "${relay_cli:-}"; then
   "$relay_cli" cloud whoami       # signed in, and as whom
@@ -372,7 +382,7 @@ human has confirmed that the reusable login's current workspace is intended.
 ```sh
 relay_workspace_uuid='HUMAN-PROVIDED-WORKSPACE-UUID'
 sign_in_payload=$(jq -nc --arg workspace "$relay_workspace_uuid" '{workspace:$workspace}')
-sign_in=$(curl -sS --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -391,7 +401,7 @@ acknowledgement added; never use it merely to suppress the error:
 ```sh
 sign_in_payload=$(printf '%s\n' "$sign_in_payload" | \
   jq '. + {acknowledge_uninspected_schedules:true}')
-sign_in=$(curl -sS --unix-socket "$relay_socket" \
+sign_in=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d "$sign_in_payload" http://relay/setup/sign-in)
 printf '%s\n' "$sign_in" | jq \
@@ -434,7 +444,7 @@ print it, and map the known messages to their fix instead of dumping raw state:
 
 ```sh
 while :; do
-  state=$(curl -sS --unix-socket "$relay_socket" http://relay/setup/status)
+  state=$(curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status)
   phase=$(printf '%s' "$state" | jq -r '.data.sign_in // .error.code')
   case "$phase" in
     signed_in)
@@ -462,13 +472,52 @@ done
 
 ## 4. Apply the agent-led defaults and register this session
 
-Set and verify all three agent-led defaults even when the app's `/setup/*`
+Read the current sharing mode before changing it. `/setup/status` reports it as
+`.data.sharing_mode` (`new`, `all`, or `selected`; `new` when nothing is
+uploading yet). The probe reports the same field, `sharing_mode`, in
+`agent-relay-probe status --account <account-id> --workspace <workspace-id> --json`.
+
+```sh
+relay_prior_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+  http://relay/setup/status | jq -r '.data.sharing_mode // empty')
+case "$relay_prior_mode" in
+  new|all|selected) printf 'sharing_mode=%s\n' "$relay_prior_mode" ;;
+  *) printf 'Could not read the sharing mode; ask the human before changing sharing.\n' >&2
+     exit 1 ;;
+esac
+```
+
+Continue only with a verified `new`, `all`, or `selected`. If the status read
+fails or reports no mode, retry once; if it is still unknown, stop and ask the
+human how to proceed rather than sending any sharing request.
+
+On a fresh install, or when it already reports `new`, keep `new`. When an
+existing install reports `all` (which also uploads past sessions, so it is
+broader than this skill's default) or `selected`, tell the human the current
+mode and ask whether to keep it or change it to `new`. Never change it silently.
+Only when the human explicitly chooses a different mode, set
+`relay_sharing_mode` to that answer at the top of the next block; left unset,
+the block keeps the mode the app reports, so nothing changes without an answer.
+Remember the chosen mode: section 8 checks it again, and shell variables do not
+survive between separate tool calls.
+
+Then set and verify all three agent-led defaults even when the app's `/setup/*`
 bootstrap already applied them. Sharing mode `new` uploads every new session;
 auto-activation puts every existing live session and every future session on
 the relay; direct delivery sets Claude Code `crossSessionInbound` to `accept`:
 
 ```sh
-direct_delivery=$(curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+# Unset keeps the current mode; set it only to the human's explicit answer.
+if test -z "${relay_sharing_mode:-}"; then
+  relay_sharing_mode=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
+    http://relay/setup/status | jq -r '.data.sharing_mode // empty')
+fi
+case "$relay_sharing_mode" in
+  new|all|selected) ;;
+  *) printf 'Sharing mode unknown; ask the human before changing sharing.\n' >&2
+     exit 1 ;;
+esac
+direct_delivery=$(curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' http://relay/setup/direct-delivery)
 printf '%s\n' "$direct_delivery" | jq
 if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; then
@@ -477,16 +526,17 @@ if ! printf '%s\n' "$direct_delivery" | jq -e '.ok and .data.direct_delivery'; t
   fi
   exit 1
 fi
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
-  -d '{"mode":"new"}' http://relay/setup/sharing | jq
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg mode "$relay_sharing_mode" '{mode:$mode}')" \
+  http://relay/setup/sharing | jq
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{"enabled":true}' \
   http://relay/setup/auto-activate | jq
-register=$(curl -sS --unix-socket "$relay_socket" \
+register=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   -H 'Content-Type: application/json' \
   -d '{}' http://relay/register)
 printf '%s\n' "$register" | jq
-registration_status=$(curl -sS --unix-socket "$relay_socket" \
+registration_status=$(curl -sS --max-time 60 --unix-socket "$relay_socket" \
   http://relay/setup/status)
 printf '%s\n' "$registration_status" | \
   jq '{session: .data.session, direct_delivery: .data.direct_delivery, error}'
@@ -495,11 +545,26 @@ printf '%s\n' "$registration_status" | jq -e \
    .data.session.registered == true and .data.session.direct_delivery == true'
 ```
 
+**Codex on macOS.** The system `curl` hides a Codex session's identity from the
+socket there, so `/register` is refused `not_a_relay_session` (section 6 says
+the same for subscriptions). In a Codex session on macOS, find `relay_probe`
+with section 6's first block and send the registration through it instead of
+the `curl` line above, then read `/setup/status` as above:
+
+```sh
+register=$(printf '{}' | "$relay_probe" relay socket-request \
+  --socket "$relay_socket" --method POST --path /register)
+```
+
+If `/setup/sign-in` is refused the same way, send its payload through the probe
+the same way. Without a probe, stop and report it rather than registering
+another process.
+
 Direct delivery is checked first so a managed-policy refusal stops setup
 before auto-activation or upload settings are changed. Report that refusal
 clearly; never claim the three-default setup completed.
 
-Sharing mode `new` and auto-activate are different settings: the former
+Sharing mode and auto-activate are different settings: the former
 controls upload eligibility and the latter controls Relay registration. The
 setup flow requires both.
 
@@ -525,7 +590,7 @@ Capture the one-time secret without echoing it:
 ```sh
 umask 077
 hook_file=$(mktemp)
-curl -sS --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
+curl -sS --max-time 60 --unix-socket "$relay_socket" -H 'Content-Type: application/json' \
   -d '{}' http://relay/webhooks >"$hook_file"
 jq '{ok, created: .data.created, webhook_id: .data.webhook_id, url: .data.url, error}' "$hook_file"
 ```
@@ -636,10 +701,10 @@ relay_req() {  # METHOD PATH [JSON body]
     printf 'A Codex session on macOS needs agent-relay-probe; start Agent Relay and retry.\n' >&2
     return 1
   elif test -n "${3:-}"; then
-    curl -sS --unix-socket "$relay_socket" -X "$1" \
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' -d "$3" "http://relay$2"
   else
-    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 
@@ -786,19 +851,22 @@ agent acted only once.
 Read status again:
 
 ```sh
-curl -sS --unix-socket "$relay_socket" http://relay/setup/status | \
+curl -sS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
   jq '{version: .data.version, sign_in: .data.sign_in, workspace: .data.workspace, sharing_mode: .data.sharing_mode, auto_activate: .data.auto_activate, direct_delivery: .data.direct_delivery, defaults_error: .data.defaults_error, uploader: .data.uploader, session: .data.session, webhook: .data.webhook, integrations: .data.integrations}'
 ```
 
-Require all three defaults before declaring setup complete:
+Require all three defaults before declaring setup complete. Set
+`relay_sharing_mode` again to the mode chosen in section 4 (`new`, or the
+existing mode the human kept); the check refuses to guess it:
 
 ```sh
-curl -fsS --unix-socket "$relay_socket" http://relay/setup/status | \
-  jq -e '.ok and .data.sharing_mode == "new" and .data.auto_activate == true and .data.direct_delivery == true'
+: "${relay_sharing_mode:?set relay_sharing_mode to the mode chosen in section 4}"
+curl -fsS --max-time 60 --unix-socket "$relay_socket" http://relay/setup/status | \
+  jq -e --arg mode "$relay_sharing_mode" '.ok and .data.sharing_mode == $mode and .data.auto_activate == true and .data.direct_delivery == true'
 ```
 
 Report the exact version, `signed_in`, signed-in workspace id and name, sharing
-mode `new`, auto-activate `true`, direct-delivery `true`,
+mode (`new`, or the existing mode the human kept), auto-activate `true`, direct-delivery `true`,
 uploader health, session address, direct-delivery state, webhook test marker,
 subscriptions, real GitHub event evidence, and polling-coexistence result.
 Separate verified facts from steps that still require a human or external
@@ -808,7 +876,9 @@ event.
 
 - **Socket missing or slow:** check `systemctl --user status agent-relay.service`
   on Linux or `open -a "Agent Relay"` on macOS. Confirm the pointer names a
-  socket. Never delete a live socket; restart the owning service/app.
+  socket. Never delete a live socket; restart the owning service/app. A reply
+  that takes up to about 30 seconds is the known latency in section 1
+  (relay-desktop#333), not a fault: allow 60 seconds and retry once.
 - **`not_a_relay_session`:** the command is not a descendant of a supported
   live Codex/Claude session, or the session id/process start no longer matches.
   Run it through this agent's shell tool. In tmux, confirm the agent process and
@@ -866,7 +936,7 @@ event.
 - **Managed Claude policy:** if direct delivery reports `managed_policy`, the
   organization controls `crossSessionInbound`; report the policy block rather
   than modifying managed settings.
-- **Undo registration:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
+- **Undo registration:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/register | jq`.
 - **Undo an integration:** with section 6's `relay_probe`, `relay_socket`,
   `relay_req`, and `pr_resources` defined, remove every subscription the
   session holds for the pull request, in whichever form it was made. On macOS
@@ -884,7 +954,7 @@ event.
   ```
 
   Require the final list to hold none of that pull request's resources.
-- **Undo a webhook:** `curl -sS --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
+- **Undo a webhook:** `curl -sS --max-time 60 --unix-socket "$relay_socket" -X DELETE http://relay/webhooks | jq`.
 - **Undo direct delivery:** POST `{"enabled":false}` to
   `/setup/direct-delivery`. On Claude this restores the local opt-out; managed
   organization policy still wins.
diff --git a/.claude/skills/setting-up-agent-relay-flows/SKILL.md b/.claude/skills/setting-up-agent-relay-flows/SKILL.md
new file mode 100644
index 00000000..de28d222
--- /dev/null
+++ b/.claude/skills/setting-up-agent-relay-flows/SKILL.md
@@ -0,0 +1,232 @@
+---
+name: setting-up-agent-relay-flows
+description: Set up and activate an Agent Relay Flow end-to-end from a running agent session through the Cloud APIs, with no dashboard clicks - choose a catalog flow and repository, connect the GitHub (or other trigger) tools and any coding-agent credentials, activate the listener through the direct-source deploy API, and verify it is listening. Use when a human asks an agent to set up Flows, activate a recommended flow such as Software Garden on a repository, or finish Flows onboarding.
+---
+
+# Set Up Agent Relay Flows
+
+Drive the setup through the documented Cloud APIs and the official CLI. Do not
+use computer use, browser automation, or the dashboard UI. The human approves
+sign-in, tool consent, and provider logins on their own approval pages; open
+those links with the OS URL opener (or give them the link), then verify by
+polling the API, never by inspecting the browser.
+
+Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
+including its `/cloud` prefix; the site is `https://agentrelay.com`. The flow
+catalog is the one exception: it is a site API, served from the site origin
+without `/cloud` (`https://agentrelay.com/api/v1/flows/catalog`). When a
+guide names a different site and Cloud base (for example a local development
+stack), use those exact origins throughout, including for the catalog, the
+CLI's `--api-url` and the dashboard links, and never fall back to production.
+Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
+
+## Requires
+
+A signed-in Cloud session: an access token and the `user.id` and
+`currentWorkspace.id` from whoami. Get them with `signing-in-to-agent-relay-cloud`
+first. Send `Authorization: Bearer <access_token>` only to the Cloud API
+endpoints below. Never send it to the site's flow catalog or to a catalog
+`source.rawUrl`; fetch those without credentials.
+
+## API map
+
+- Flow catalog (site origin, not under `/cloud`):
+  `GET https://agentrelay.com/api/v1/flows/catalog` and `/<id>`.
+- Tool consent links: `POST /api/v1/integrations/connect-link`; poll
+  `GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status`.
+- Coding-agent credentials: the official CLI's `cloud connect` (section 3);
+  `GET /api/v1/cloud-agents` inspects existing connections.
+- Activation: `POST /api/v1/flows/deploy` with the body in section 4.
+- Custom-flow prompt generator (optional): `GET /api/v1/flows/prompt/generate`
+  reports whether it is available.
+- Verification: `GET /api/v1/flows/listeners/<agentId>`.
+
+## 1. Prebuilt or custom?
+
+Ask the human first, unless their request already says: a **prebuilt** flow
+from the Agent Relay catalogue (https://agentrelay.com/flows), or a **custom**
+flow of their own? In an agent-driven signup, ask through that guide's
+web-input protocol on the signup page, not in chat.
+
+- Prebuilt: continue with section 2.
+- Custom: follow **Custom flow: deploy journey** below. A custom flow is
+  activated by the same `POST /api/v1/flows/deploy` API as a prebuilt one and
+  as the deploy builder at https://agentrelay.com/cloud/flows/deploy; there is
+  no separate custom API.
+
+## 2. Choose the flow and repository
+
+Ask the human for missing product choices: repository, desired
+workflow/trigger, and approver. In an agent-driven signup, ask through that
+guide's web-input protocol on the signup page, not in chat. Ask for the approver's
+GitHub username in plain language (for example, "octocat" or "@octocat"),
+not an internal provider-address format or their Google email. Normalize the
+answer to github:@handle when constructing the deploy API request. Human-gate
+replies are matched to that provider identity. Infer choices from the user's request and current
+repository where clear.
+Do not invent a repository or enable automation on an unrelated project.
+
+GET https://agentrelay.com/api/v1/flows/catalog and select a matching entry from flows.
+GET https://agentrelay.com/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
+kind before doing anything executable: only an entry with kind: flow (or a
+legacy entry with kind omitted) is deployable through the direct-source API
+below. An entry with kind: extension is discoverable metadata, not a standalone
+listener. Do not download or deploy its source, even when it declares trigger
+and input fields. Inspect baseFlowId and extension.activation instead. If the
+extension is blocked, report the unmet dependencies and that it can only be
+added to its base flow after a supported extension activation path is available;
+never substitute a standalone flow deployment.
+
+For a deployable flow, use the catalog's
+supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
+inputs.allowedAgents. Name a model per harness in inputs.models when the house
+default is wrong (for example {"claude": "claude-sonnet-4"}); omit it to fund
+the house default for each declared agent. Download source.rawUrl, verify its bytes against
+source.sha256, and use that source text unchanged for a recommended flow.
+The source is TypeScript, not the source URL. Do not guess a template or hash.
+
+## Custom flow: deploy journey
+
+There is no journey API. A `journey_id` (for example in a
+`next=/flows/deploy?journey_id=...` link) is only an analytics tag: pass it
+through unchanged where you received it, and never call an endpoint with it or
+wait on it. A custom flow is activated by the same `POST /api/v1/flows/deploy`
+as a prebuilt one; only where the source comes from differs.
+
+1. Author the flow with `writing-relayflows` (the Relayflows v2 engine,
+   `@relayflows/surface` / `@relayflows/sdk`, CLI `flows`). Defer to that
+   skill for the flow's shape and checks; Flows are always v2. Cloud's
+   prompt generator is an optional shortcut: use it only when
+   `GET /api/v1/flows/prompt/generate` returns `available: true`. If it
+   reports unavailable, refuses your session (403 `session_required`), or
+   fails, author with `writing-relayflows` instead; do not retry into it.
+2. Choose its repository, trigger and approver as in section 2.
+3. Continue with sections 3 to 5 unchanged. In section 4, `source` is the
+   custom TypeScript text, `workflow` is its label, and `promptSpec` is sent
+   only when the prompt generator produced one. `base` and `extensions` are
+   optional and only for a flow that names them.
+
+The human-only steps are the same for both paths: Google sign-in and device
+approval, GitHub and trigger-app OAuth including the repository grants,
+model-provider login when section 3 calls for one (not for an ordinary first
+activation), and confirming the repository and trigger before activation. Do every other step yourself through the APIs.
+
+## 3. Connect the required tools and coding agents
+
+Use bearer-authenticated POST /api/v1/integrations/connect-link:
+
+```json
+{"provider":"github","workspaceId":"<currentWorkspace.id>"}
+```
+
+Open the returned connectUrl for the user to approve. Keep token/sessionToken
+private. Connect only the repository and tools the chosen flow requires.
+For GitHub the user must grant repository access. Repeat with the chosen trigger
+provider if different. Reuse existing ready connections rather than relinking.
+Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
+until oauth.connected is true (poll with backoff and a bounded timeout); a
+returned connect link or a closed popup alone does not prove the connection.
+For the GitHub-triggered Software Garden flow, activation separately checks
+that the connected GitHub App covers the selected repository. Its trigger
+does not require background data indexing, so do not block solely because
+the broader status.ready is false from queued syncs.
+If a different flow declares Relayfile data that requires synced records,
+verify that readiness separately before activating it.
+
+Do not connect a Claude or Codex subscription yet. The first three runs use
+Cloud's own model key, so no provider login is needed to activate. If the chosen
+flow declares more than one coding agent (the catalog's `inputs.defaults.agents`,
+which becomes `inputs.agents` in the deploy body), included Cloud runs
+can fund only one of them per run — connect your own subscription for at least
+one declared agent before activating a multi-agent flow. After the included
+runs, activation and launches will ask for your own subscription; only then use
+the official Relay CLI with the private credential environment from
+`signing-in-to-agent-relay-cloud` (its section 5) and a PTY:
+
+This promotion depends on Cloud's internal house-key proxy and account
+enrollment. If local activation returns flow_credentials_unavailable or
+flow_model_not_connected before the three promotional runs, treat it as an
+internal configuration or eligibility issue. Do not ask the user to connect
+Claude/Codex, provide an API key, or choose an inactive draft as a workaround.
+Report the blocker (in a signup, through its Progress API) and have an internal developer
+verify the proxy, promotion flag, provider readiness, and enrollment. Never
+copy a house key into the agent environment or expose it in this guide.
+
+```sh
+npx --yes agent-relay@13 cloud connect anthropic --api-url 'https://agentrelay.com/cloud'
+```
+
+Use anthropic for Claude or openai for Codex, according to the selected flow.
+The command drives provider login; open its authorization URL for the user,
+and keep the process alive until it confirms the credential is connected.
+Google approval does not grant GitHub or model-provider access: those services
+may require their own consent. Never fabricate credentials or claim consent
+happened. GET /api/v1/cloud-agents lets you inspect the account's credential
+state without reconnecting.
+
+## 4. Activate through the same API as web onboarding
+
+POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
+session. The token must be the device-flow session from
+`signing-in-to-agent-relay-cloud` (scope `cli:auth`) or a token with
+`flows:listeners:write`, and `workspaceId` must be that token's workspace. This is the direct-source listener API used by flows deploy, not the
+browser onboarding handoff: source is TypeScript text, repository is singular,
+and sources contains provider/settings objects. The catalog supplies the source
+reference and defaults; it is not itself a deploy request. The current endpoint
+does not accept a flowId/repositories-only catalog activation request or fetch
+the source for you. For multiple repositories, submit one deployment per
+repository with a distinct name and handoffId.
+
+For the catalog's Software Garden entry (id `software-factory`), construct this body, substituting the
+workspace, verified source, repository, GitHub approver and a new UUID:
+
+```json
+{
+  "workspaceId": "<currentWorkspace.id>",
+  "name": "Software Garden",
+  "workflow": "software-factory",
+  "source": "<verified TypeScript source text>",
+  "handoffId": "<one UUID generated for this setup>",
+  "inputs": {"approver": "github:@octocat", "agents": ["claude"]},
+  "mode": "activate",
+  "repository": {"owner": "acme", "name": "api"},
+  "sources": [{"provider": "github", "settings": {"repository": "acme/api"}}]
+}
+```
+
+For another deployable kind: flow catalog entry use its id as workflow, allowed agents, and
+defaultTrigger for sources, then apply the user's trigger settings. Scope a
+GitHub issue trigger with settings.repository set to the chosen owner/name;
+for GitLab use settings.project. Cloud does not derive this filter from the
+deployment repository. An empty filter can trigger on other repositories in
+the workspace. Only use a different trigger scope when explicitly requested.
+Give each repository its own trigger filter for multi-repository setup. Do not send
+the example acme repository or octocat approver unchanged. The workflow field
+is a label, not a source lookup; keep the verified source in the request.
+For GitLab set repository.host to gitlab and use the namespace path
+as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
+failure, GET /api/v1/flows/listeners and check whether the flow already exists;
+do not create a new ID/name on every retry. Activation subscribes to matching
+future events and can run work; confirm the intended repository and trigger
+with the user if they have not specified them.
+
+HTTP 201 must contain agentId and status: listening. A draft is not completion.
+For a 409 workspace_mismatch, verify the active workspace; for connection
+preflight failures, fix the indicated connection before retrying. If the user
+wants to save incomplete work, use mode: draft explicitly and report that it
+is inactive. Never mask activation failures by silently falling back to draft.
+
+## 5. Verify
+
+GET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and
+verify its repository and sources match the request. Open
+https://agentrelay.com/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,
+workspace, repository, trigger, and verified listening state. This proves
+activation; only an actual completed run proves execution. Do not create a
+real issue or launch paid work merely to make the onboarding check turn green.
+Delete temporary authentication files after the work is complete.
+
+The desktop app is optional for Flows. If the user also wants local session
+sharing, use `setting-up-agent-relay-desktop` and `setting-up-agent-relay-sessions`
+with the same account (an agent-driven signup can follow
+https://agentrelay.com/signup/agent/teams).
diff --git a/.claude/skills/setting-up-agent-relay-sessions/SKILL.md b/.claude/skills/setting-up-agent-relay-sessions/SKILL.md
index 331b4933..6c9c30a6 100644
--- a/.claude/skills/setting-up-agent-relay-sessions/SKILL.md
+++ b/.claude/skills/setting-up-agent-relay-sessions/SKILL.md
@@ -161,13 +161,20 @@ Before sending that message, check what this machine already has. If an Agent
 Relay CLI 13.x is installed (a user-level npm, mise or nvm `agent-relay`, not
 the `.deb`'s `/usr/bin/agent-relay` Desktop launcher), run these read-only
 checks. Without one, section 2 reads the signed-in workspace from
-`/setup/status` instead.
+`/setup/status` instead. The CLI is optional for this skill: detect it as
+below, which skips the Desktop launcher that `command -v agent-relay` finds on
+a `.deb` install, and do not install or upgrade it just for these checks.
 
 ```sh
-agent-relay cloud whoami       # signed in, and as whom
-agent-relay workspace active   # the active Cloud workspace (keys stay masked)
-agent-relay cloud workspaces   # every workspace this login can use, with ids
-agent-relay status             # workspace, cloud login and local broker
+relay_cli=$(command -v agent-relay || true)
+case "$relay_cli" in ''|/usr/bin/agent-relay) relay_cli= ;; esac
+if test -n "$relay_cli"; then
+  "$relay_cli" --version
+  "$relay_cli" cloud whoami       # signed in, and as whom
+  "$relay_cli" workspace active   # the active Cloud workspace (keys stay masked)
+  "$relay_cli" cloud workspaces   # every workspace this login can use, with ids
+  "$relay_cli" status             # workspace, cloud login and local broker
+fi
 ```
 
 If the active workspace is already the shared one, confirm it with the person
@@ -247,14 +254,23 @@ relay_req() {
     return 1
   elif test -n "${3:-}"; then
     # body on stdin: curl treats a -d/--data-binary value starting with @ as a filename
-    printf '%s' "$3" | curl -sS --unix-socket "$relay_socket" -X "$1" \
+    printf '%s' "$3" | curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" \
       -H 'Content-Type: application/json' --data-binary @- "http://relay$2"
   else
-    curl -sS --unix-socket "$relay_socket" -X "$1" "http://relay$2"
+    curl -sS --max-time 60 --unix-socket "$relay_socket" -X "$1" "http://relay$2"
   fi
 }
 ```
 
+**Slow socket replies are known.** `GET /setup/status` and `GET /agents` can
+take about 30 seconds on a busy Desktop (tracked in
+AgentWorkforce/relay-desktop#333). Allow 60 seconds per call (add
+`--max-time 60` to the `curl` lines above), and do not treat a slow reply as a
+failure. The probe's `relay socket-request` can give up sooner with "Probe
+could not finish. Check your connection and run setup again"; on these paths
+that is the same latency, not a setup problem. Retry once before reporting a
+blocker, and do not rerun desktop setup because of it.
+
 ## 2. Make sure the desktop is set up first
 
 Session handoff needs a signed-in, healthy desktop underneath it. If the socket
@@ -272,6 +288,7 @@ relay_req GET /setup/status | jq '{
   version: .data.version,
   sign_in: .data.sign_in,
   workspace: .data.workspace,
+  sharing_mode: .data.sharing_mode,
   uploader: .data.uploader,
   direct_delivery: .data.direct_delivery,
   session: .data.session,
@@ -304,6 +321,17 @@ read **this** person's session, this machine must have uploaded it. If
 anyone can read this session — this is the single most common reason a live
 handoff silently fails.
 
+`sharing_mode` decides which sessions upload at all, and a healthy uploader
+does not prove that **this** session is among them. `all` includes it. `new`
+includes sessions that started after `new` was enabled, so a session that was
+already running when the desktop was set up may not be uploaded. Under
+`selected`, only the sessions the person chose upload. Unless the mode is
+`all`, tell the person that this session may not be shared yet, and ask them to
+select it in the app or to continue from a new session; do not change the
+sharing mode or select sessions on their behalf. Section 5's round trip is the
+proof: if the teammate cannot read this session there, this is the first
+thing to check.
+
 ## 3. Install the agent-sessions cloud MCP (before the session uses it)
 
 Check whether the token is present in the environment **without printing it**
@@ -413,6 +441,7 @@ without a second person:
    citation link) — the uploader→read path works.
 3. Record that the two-party round trip still needs the teammate online, and
    name it as the remaining step rather than claiming the handoff is proven.
+   Setup is not complete until the full round trip succeeds.
 
 Never paste the Bearer token or any session token into a `send_relay_message`
 body or any artifact.
diff --git a/.claude/skills/signing-in-to-agent-relay-cloud/SKILL.md b/.claude/skills/signing-in-to-agent-relay-cloud/SKILL.md
new file mode 100644
index 00000000..735fdeb5
--- /dev/null
+++ b/.claude/skills/signing-in-to-agent-relay-cloud/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: signing-in-to-agent-relay-cloud
+description: Sign a person in to Agent Relay Cloud from a running agent session through the OAuth device flow, with no API key or dashboard wizard - start the device grant, let the human approve it, poll for tokens, refresh them, read the account and workspace from whoami, and hand the session to the official CLI without printing a token. Use when an agent needs a Cloud access token or the person's user and workspace ids, including as the first step of an Agent Relay agent-driven signup.
+---
+
+# Sign In to Agent Relay Cloud
+
+Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
+or pre-existing Agent Relay account is required. Only the human approves the
+sign-in; never approve access on their behalf, ask for their password, or
+operate the approval page yourself.
+
+Paths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,
+including its `/cloud` prefix. When a guide names a different Cloud base (for
+example a local development stack), use that exact base throughout and never
+fall back to production.
+
+## HTTP client
+
+Use `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their
+default User-Agent: the device-token endpoint answers them with HTTP 403 and no
+JSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth
+response while debugging; on success it contains tokens. Send JSON request
+bodies with `Content-Type: application/json`, set a 30-second request timeout,
+and check every response status before proceeding.
+
+## 1. Start the device grant
+
+`POST /api/v1/auth/device/start` with:
+
+```json
+{"client_name":"My agent setup"}
+```
+
+An agent-driven signup guide also passes its product as `signup_source`
+(`"teams"` or `"flows"`); keep the value the guide names. Omit it otherwise.
+
+Expect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,
+`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep
+`device_code` private. Open `verification_uri_complete` in the person's
+browser with the OS URL opener (for example macOS `open`, with the URL passed as
+a separate argument, never interpolated into shell code), or give them the link
+if no opener is available. Show the `user_code` so they can compare it. The page
+lets them sign in with Google, review the requesting device, and Approve or
+Deny. A signup marker in the returned URL creates the right account type;
+preserve it through sign-in. Do not call `/auth/device/approve` yourself.
+
+For a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`
+on the same Cloud base first (in production,
+`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of
+`verification_uri_complete`. This opens Google immediately and returns to the
+same device approval with its code and signup marker intact. Never open the
+production URL for a non-production base: that would sign the human in to
+production instead.
+
+## 2. Poll for tokens
+
+While the browser is open, wait `interval` seconds between POSTs to
+`/api/v1/auth/device/token` with this JSON (substitute the private
+`device_code`):
+
+```json
+{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}
+```
+
+- `authorization_pending`: keep waiting; respect a returned interval.
+- `slow_down`: increase the interval by at least 5 seconds.
+- HTTP 429: respect `Retry-After` and increase the interval.
+- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.
+- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start
+  a new grant only if the person still wants to continue. Never poll past
+  expiry.
+
+HTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,
+`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in
+memory or a private file (directory 0700, file 0600) outside repositories.
+Never echo tokens, put them in chat or URLs, or dump full authentication
+responses. Use `Authorization: Bearer <access_token>` for subsequent Cloud
+requests. Reject an `api_url` pointing at another origin; keep using the Cloud
+base above.
+
+## 3. Refresh before expiry
+
+Before expiry, `POST /api/v1/auth/token/refresh` with
+`{"refreshToken":"<refresh_token>"}`. The response uses camelCase:
+`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,
+`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the
+refresh token rotates and must not be shared between machines. An
+invalid/expired refresh requires a new device login, not an endless retry.
+
+## 4. Read the account and workspace
+
+`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,
+`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups
+create a workspace automatically. Reuse it; do not create duplicate
+accounts/workspaces. If `currentWorkspace` is missing, or an existing account
+is in the wrong workspace, resolve that with the person before connecting or
+activating anything. Never silently replace an existing connection to another
+account.
+
+## 5. Hand the session to the official CLI
+
+When running a child process, pass these through its environment from your
+private session object (never interpolate their values into logged commands):
+
+```text
+CLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>
+CLOUD_API_ACCESS_TOKEN=<access_token>
+CLOUD_API_REFRESH_TOKEN=<refresh_token>
+CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
+CLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>
+```
+
+The official CLI consumes this session. Refresh the parent session before
+starting a long command; do not concurrently refresh it from parent and child
+processes. Do not overwrite an existing CLI auth file or copy a session to
+another machine. Delete temporary authentication files after the work is
+complete.
diff --git a/prpm.lock b/prpm.lock
index ef8f3ed4..44e4b2ea 100644
--- a/prpm.lock
+++ b/prpm.lock
@@ -3,9 +3,9 @@
   "lockfileVersion": 1,
   "packages": {
     "@agent-relay/setting-up-agent-relay-desktop#claude": {
-      "version": "1.1.4",
-      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-desktop/1.1.4.tar.gz",
-      "integrity": "sha256-de1fa4fb20e2a3d02e4cd86bd32a2f3bc3a6a5276a81e0bbc5c114325f5385bf",
+      "version": "1.1.5",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-desktop/1.1.5.tar.gz",
+      "integrity": "sha256-977560daebe00574ab9af8964f0004e0535f62f94a65f53a7f9cbb5de592fd35",
       "format": "claude",
       "subtype": "skill",
       "sourceFormat": "claude",
@@ -13,9 +13,9 @@
       "installedPath": ".claude/skills/setting-up-agent-relay-desktop/SKILL.md"
     },
     "@agent-relay/setting-up-agent-relay-sessions#claude": {
-      "version": "0.2.4",
-      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-sessions/0.2.4.tar.gz",
-      "integrity": "sha256-58021adb458e33c571c92fcf91032466b9653f236323bbf283044b68ba9a3a6e",
+      "version": "0.2.5",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-sessions/0.2.5.tar.gz",
+      "integrity": "sha256-4e6234a7f970d6d653ca3cb50381a0959c5dd49171d64a81e743dff56613e1df",
       "format": "claude",
       "subtype": "skill",
       "sourceFormat": "claude",
@@ -31,7 +31,27 @@
       "sourceFormat": "claude",
       "sourceSubtype": "skill",
       "installedPath": ".claude/skills/writing-relayflows/SKILL.md"
+    },
+    "@agent-relay/signing-in-to-agent-relay-cloud#claude": {
+      "version": "0.1.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsigning-in-to-agent-relay-cloud/0.1.0.tar.gz",
+      "integrity": "sha256-6d1413b9793546ce39d686e10c2ac288963919ad5a58b61864a53b75cb154a82",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/signing-in-to-agent-relay-cloud/SKILL.md"
+    },
+    "@agent-relay/setting-up-agent-relay-flows#claude": {
+      "version": "0.1.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fsetting-up-agent-relay-flows/0.1.0.tar.gz",
+      "integrity": "sha256-39fe2bbe69f92b0fb1120e40e49263e84c4163bbca11c15b1262d2badf55a206",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/setting-up-agent-relay-flows/SKILL.md"
     }
   },
-  "generated": "2026-10-08T06:50:15.717Z"
+  "generated": "2026-10-08T07:02:02.207Z"
 }
\ No newline at end of file
diff --git a/web/lib/generated/setup-skills.ts b/web/lib/generated/setup-skills.ts
index 84627515..022c28ae 100644
--- a/web/lib/generated/setup-skills.ts
+++ b/web/lib/generated/setup-skills.ts
@@ -1,6 +1,6 @@
-// Generated by web/scripts/sync-setup-skills.mjs from the pinned
-// AgentWorkforce/skills commit in web/content/setup-skills/SOURCE.json. Do not edit.
-export const SETUP_SKILLS_SOURCE = {"repository":"AgentWorkforce/skills","commit":"d2e5a3ecfbfdd7b64c6775b3c452c99b06e62fd6"} as const;
+// Generated by web/scripts/generate-setup-skills.mjs from the prpm-installed
+// @agent-relay setup skills pinned in prpm.lock. Do not edit.
+export const SETUP_SKILLS_SOURCE = {"registry":"prpm","packages":{"signing-in-to-agent-relay-cloud":"0.1.0","setting-up-agent-relay-desktop":"1.1.5","setting-up-agent-relay-sessions":"0.2.5","setting-up-agent-relay-flows":"0.1.0","writing-relayflows":"1.6.0"}} as const;
 
 export const SETUP_SKILLS: Readonly<Record<string, string>> = {
   "signing-in-to-agent-relay-cloud": "# Sign In to Agent Relay Cloud\n\nUse the existing OAuth device flow. No API key, invitation, dashboard wizard,\nor pre-existing Agent Relay account is required. Only the human approves the\nsign-in; never approve access on their behalf, ask for their password, or\noperate the approval page yourself.\n\nPaths below are relative to the Cloud API base, `https://agentrelay.com/cloud`,\nincluding its `/cloud` prefix. When a guide names a different Cloud base (for\nexample a local development stack), use that exact base throughout and never\nfall back to production.\n\n## HTTP client\n\nUse `curl` or `fetch`. Avoid Python's `urllib` or `requests` with their\ndefault User-Agent: the device-token endpoint answers them with HTTP 403 and no\nJSON body (tracked in AgentWorkforce/cloud#4254). Never print a raw auth\nresponse while debugging; on success it contains tokens. Send JSON request\nbodies with `Content-Type: application/json`, set a 30-second request timeout,\nand check every response status before proceeding.\n\n## 1. Start the device grant\n\n`POST /api/v1/auth/device/start` with:\n\n```json\n{\"client_name\":\"My agent setup\"}\n```\n\nAn agent-driven signup guide also passes its product as `signup_source`\n(`\"teams\"` or `\"flows\"`); keep the value the guide names. Omit it otherwise.\n\nExpect HTTP 201 with `device_code`, `user_code`, `verification_uri_complete`,\n`verification_uri`, `interval` (seconds), and `expires_in` (seconds). Keep\n`device_code` private. Open `verification_uri_complete` in the person's\nbrowser with the OS URL opener (for example macOS `open`, with the URL passed as\na separate argument, never interpolated into shell code), or give them the link\nif no opener is available. Show the `user_code` so they can compare it. The page\nlets them sign in with Google, review the requesting device, and Approve or\nDeny. A signup marker in the returned URL creates the right account type;\npreserve it through sign-in. Do not call `/auth/device/approve` yourself.\n\nFor a fresh signup, you can open `/api/auth/google/start?next=<encoded-return-path>`\non the same Cloud base first (in production,\n`https://agentrelay.com/cloud/api/auth/google/start?next=<encoded-return-path>`), where `encoded-return-path` is the URL-encoded pathname plus query of\n`verification_uri_complete`. This opens Google immediately and returns to the\nsame device approval with its code and signup marker intact. Never open the\nproduction URL for a non-production base: that would sign the human in to\nproduction instead.\n\n## 2. Poll for tokens\n\nWhile the browser is open, wait `interval` seconds between POSTs to\n`/api/v1/auth/device/token` with this JSON (substitute the private\n`device_code`):\n\n```json\n{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"<device_code>\"}\n```\n\n- `authorization_pending`: keep waiting; respect a returned interval.\n- `slow_down`: increase the interval by at least 5 seconds.\n- HTTP 429: respect `Retry-After` and increase the interval.\n- HTTP 5xx or request timeout: retry with backoff, bounded by `expires_in`.\n- `access_denied`: stop. `expired_token` or `invalid_grant`: explain and start\n  a new grant only if the person still wants to continue. Never poll past\n  expiry.\n\nHTTP 200 returns `access_token`, `refresh_token`, `access_token_expires_at`,\n`refresh_token_expires_at`, `api_url` and `token_type`. Keep credentials in\nmemory or a private file (directory 0700, file 0600) outside repositories.\nNever echo tokens, put them in chat or URLs, or dump full authentication\nresponses. Use `Authorization: Bearer <access_token>` for subsequent Cloud\nrequests. Reject an `api_url` pointing at another origin; keep using the Cloud\nbase above.\n\n## 3. Refresh before expiry\n\nBefore expiry, `POST /api/v1/auth/token/refresh` with\n`{\"refreshToken\":\"<refresh_token>\"}`. The response uses camelCase:\n`accessToken`, `refreshToken`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`,\n`apiUrl`. Replace both stored tokens atomically. Serialize refreshes: the\nrefresh token rotates and must not be shared between machines. An\ninvalid/expired refresh requires a new device login, not an endless retry.\n\n## 4. Read the account and workspace\n\n`GET /api/v1/auth/whoami`. Require `authenticated: true` and read `user.id`,\n`user.email`, `currentWorkspace.id`, and `currentOrganization.id`. New signups\ncreate a workspace automatically. Reuse it; do not create duplicate\naccounts/workspaces. If `currentWorkspace` is missing, or an existing account\nis in the wrong workspace, resolve that with the person before connecting or\nactivating anything. Never silently replace an existing connection to another\naccount.\n\n## 5. Hand the session to the official CLI\n\nWhen running a child process, pass these through its environment from your\nprivate session object (never interpolate their values into logged commands):\n\n```text\nCLOUD_API_URL=<the Cloud base above; https://agentrelay.com/cloud in production>\nCLOUD_API_ACCESS_TOKEN=<access_token>\nCLOUD_API_REFRESH_TOKEN=<refresh_token>\nCLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>\nCLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>\n```\n\nThe official CLI consumes this session. Refresh the parent session before\nstarting a long command; do not concurrently refresh it from parent and child\nprocesses. Do not overwrite an existing CLI auth file or copy a session to\nanother machine. Delete temporary authentication files after the work is\ncomplete.\n",

From 298b90863e1e094a9f5ac419255044a05d0eadb8 Mon Sep 17 00:00:00 2001
From: Khaliq <khaliqgant@gmail.com>
Date: Thu, 8 Oct 2026 00:25:42 -0700
Subject: [PATCH 9/9] fix(signup): Dev app display name, CRLF frontmatter,
 stricter skills drift check

- The local-stack rewrite also renames the quoted "Agent Relay" display
  name (open -a, tell application) to "Agent Relay Dev".
- stripFrontmatter accepts CRLF line endings.
- CI diffs .claude/skills strictly and ignores only the lock's timestamp.
- prepreview regenerates the module too.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/test.yml            | 3 ++-
 web/lib/agent-signup.ts               | 1 +
 web/lib/test/agent-signup.test.ts     | 3 +++
 web/package.json                      | 1 +
 web/scripts/generate-setup-skills.mjs | 2 +-
 5 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 3510e309..f644e9fb 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -47,7 +47,8 @@ jobs:
       - name: Verify setup skills are current
         run: |
           npx --yes prpm@2.1.40 install --frozen-lockfile -y
-          git diff --exit-code -I '"generated"' -- prpm.lock .claude/skills
+          git diff --exit-code -- .claude/skills
+          git diff --exit-code -I '"generated"' -- prpm.lock
           npm run verify:setup-skills
 
       # Root script fans out to every workspace (web + router), so a new
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 0e64570a..dcb0a4e8 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -177,6 +177,7 @@ function forEnvironment(skill: string | undefined, site: string, cloud: string):
     .replaceAll(DESKTOP_RELEASES, `${site}/cloud/desktop-downloads`)
     .replaceAll('AgentRelay-macOS-', 'AgentRelay-Dev-macOS-')
     .replaceAll('Agent Relay.app', 'Agent Relay Dev.app')
+    .replaceAll('"Agent Relay"', '"Agent Relay Dev"')
     .replace(/com\.agentrelay\.desktop(?!\.dev)/g, 'com.agentrelay.desktop.dev')
     .replace(/\.agentworkforce\/desktop\/relay-socket(?!\.dev)/g, '.agentworkforce/desktop/relay-socket.dev') : skill;
   return local
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index a06ee613..83a40a65 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -64,6 +64,7 @@ describe('agent signup instructions', () => {
     await expect(readInstalledSkills('{"packages":{}}', async () => '')).rejects.toThrow('is not in prpm.lock');
     expect(stripFrontmatter('---\nname: x\ndescription: y\n---\n\n# X\n')).toBe('# X\n');
     expect(() => stripFrontmatter('# X\n')).toThrow('frontmatter');
+    expect(stripFrontmatter('---\r\nname: x\r\n---\r\n\r\n# X\r\n')).toBe('# X\r\n');
   });
 
   it.each([
@@ -153,6 +154,8 @@ describe('agent signup instructions', () => {
     expect(content).not.toMatch(/com\.agentrelay\.desktop(?!\.dev)/);
     expect(content).not.toMatch(/relay-socket(?!\.dev)"/);
     expect(content).not.toContain('Agent Relay.app');
+    expect(content).not.toContain('"Agent Relay"');
+    expect(content).toContain('open -a "Agent Relay Dev"');
     expect(content).toContain('"$release/AgentRelay-Dev-macOS-$relay_arch.dmg"');
     expect(content).toContain('http://127.0.0.1:3199/cloud/api/v1/mcp/shared-sessions');
     expect(content).not.toContain('https://agentrelay.com/cloud');
diff --git a/web/package.json b/web/package.json
index a0a70ca8..a27d7ab2 100644
--- a/web/package.json
+++ b/web/package.json
@@ -15,6 +15,7 @@
     "test:e2e": "playwright test",
     "precf:build": "node scripts/generate-setup-skills.mjs",
     "cf:build": "opennextjs-cloudflare build",
+    "prepreview": "node scripts/generate-setup-skills.mjs",
     "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview"
   },
   "dependencies": {
diff --git a/web/scripts/generate-setup-skills.mjs b/web/scripts/generate-setup-skills.mjs
index 20c0ff3c..d3362194 100644
--- a/web/scripts/generate-setup-skills.mjs
+++ b/web/scripts/generate-setup-skills.mjs
@@ -29,7 +29,7 @@ export const SETUP_SKILL_NAMES = [
 ];
 
 export function stripFrontmatter(text) {
-  const match = /^---\n[\s\S]*?\n---\n+/.exec(text);
+  const match = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n)+/.exec(text);
   if (!match) throw new Error('SKILL.md is missing YAML frontmatter');
   return text.slice(match[0].length);
 }