docs(relayfile): Guides section — PR review bot walkthrough (local + cloud) and a copy-paste agent brief

[kjgbot]

Why

The Relayfile docs cover each primitive well — mount layout, reads/writes, ACLs, sync, the SDK — but there was no page that walks a single build from an empty machine to a working agent. Coming out of a call with someone building an open-source PR reviewer, the gap was concrete: how do I add integrations without wiring OAuth and webhooks per provider, and how do my specialist agents in separate sandboxes share context?

What

Adds a Guides group to the Relayfile sidebar with two pages.

1. /docs/file/review-bot — Build a PR review bot

Runs one build end to end, annotated for both a workstation and a cloud fleet:

• Where it runs — a table splitting workstation / cloud sandboxes / serverless, and the rule the guide leans on: provisioning happens once, mounting happens per run.
• Connect GitHub — relayfile setup interactively, plus headless provisioning with RELAYFILE_CLOUD_TOKEN and --skip-mount, and the SDK equivalent (RelayfileSetup.fromCloudTokens → joinWorkspace → connectIntegration) for a control plane that already holds Cloud tokens.
• Verify — which relayfile status fields to gate on (dead-lettered, not the lifetime failed counter), reading LAYOUT.md / .layout.md / _index.json instead of hard-coding paths, and relayfile tree / read for checking a workspace with no mount.
• Add context — integration available / search / connect for Linear, Notion, Slack; Nango vs Composio; the Jira/Confluence cloudId follow-up.
• Mount in every sandbox — ensureMountedWorkspace with verifyProvider, a path-scoped token per specialist, handle.env() as the whole handoff; where a cloud process gets its credentials (CLOUD_API_* env before ~/.agentworkforce/relay/cloud-auth.json); and the no-mount RelayFileClient path for functions with no writable disk.
• Coordinate — orchestrator recon in, specialist findings out, streamed via onWrite as each lands rather than blocking on the slowest.
• Post the review — discovery-first writeback (.adapter.md, .schema.json, .create.example.json), CREATE-by-non-canonical-filename, writeback status and dead-letter recovery.
• Trigger — relayfile listen instead of a webhook endpoint, with cursor catch-up noted so a mid-afternoon deploy doesn't drop PRs.

2. /docs/file/review-bot-brief — Review bot agent brief

A complete operating document written for the agent: environment variables, orient-before-acting rules, ACL boundaries, the /runs/<run-id>/ protocol and findings shape, discovery-first writeback, writeback verification, a troubleshooting table, and a numbered rules list.

The page body is the document, so the existing markdown mirror makes it copy-paste ready with no new infrastructure:

curl -o AGENTS.md https://agentrelay.com/docs/file/markdown/review-bot-brief.md

(or the page's built-in Copy page as markdown action).

Quickstart gets a banner link to the guide; the guide links to the brief.

Notes

• Every command and API is drawn from the existing docs and the setting-up-relayfile skill; no new hostnames or endpoints are introduced.
• Adapter-owned path shapes are shown as examples, with an explicit note that the reader's own .layout.md / _index.json is authoritative.
• Not verified locally: node_modules isn't installed in this checkout and npm install / npm ci hang in this environment, so npm test and a build were not run. The added tests' assertions were hand-checked against the same regex/filters getProductSearchIndex uses. Note the workflows build the site but don't run vitest.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NVwyjaMnm1PTRC6m7oXHJV

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 90e83fd6-64cb-4d17-b841-09fc35f9e655

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="web/content/docs/file/review-bot.mdx">

<violation number="1" location="web/content/docs/file/review-bot.mdx:236">
P2: The commands this guide tells readers to run don't match the CLI reference (cli.mdx) that the guide links at the bottom. cli.mdx documents dead-lettered writeback inspection/replay as `relayfile ops list / replay` and integration management as only `connect / list / disconnect`, yet the guide uses `relayfile writeback status`, `relayfile writeback retry --opId`, `relayfile integration available --refresh`, `relayfile integration search --refresh --json`, and `relayfile integration set-metadata`. Reconcile the two so a reader following the walkthrough gets working commands (or update the CLI reference to cover the subcommands the guide introduces).</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The commands this guide tells readers to run don't match the CLI reference (cli.mdx) that the guide links at the bottom. cli.mdx documents dead-lettered writeback inspection/replay as relayfile ops list / replay and integration management as only connect / list / disconnect, yet the guide uses relayfile writeback status, relayfile writeback retry --opId, relayfile integration available --refresh, relayfile integration search --refresh --json, and relayfile integration set-metadata. Reconcile the two so a reader following the walkthrough gets working commands (or update the CLI reference to cover the subcommands the guide introduces).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/file/review-bot.mdx, line 236:

<comment>The commands this guide tells readers to run don't match the CLI reference (cli.mdx) that the guide links at the bottom. cli.mdx documents dead-lettered writeback inspection/replay as `relayfile ops list / replay` and integration management as only `connect / list / disconnect`, yet the guide uses `relayfile writeback status`, `relayfile writeback retry --opId`, `relayfile integration available --refresh`, `relayfile integration search --refresh --json`, and `relayfile integration set-metadata`. Reconcile the two so a reader following the walkthrough gets working commands (or update the CLI reference to cover the subcommands the guide introduces).</comment>

<file context>
@@ -0,0 +1,273 @@
+relayfile writeback status review-bot --json | jq
+```
+
+Pending writebacks should drain to zero within a sync cycle, and the command exits non-zero only when there are dead-lettered ops — so gate CI on the exit code, not on the lifetime `failed` counter. If `deadLettered` is non-empty, each record under `$MOUNT/.relay/dead-letter/<opId>.json` carries `lastStatus` and a truncated `lastBody` — fix the payload, then `relayfile writeback retry --opId <opId> review-bot`. Read denials are preserved separately in `$MOUNT/.relay/permissions-denied.log`, so an ACL mistake surfaces as a logged denial rather than a silent no-op. Never write anything under `.relay/` yourself.
+
+## 8. Trigger on a new PR without running a webhook server
</file context>

[github-actions]

Preview deployed!

Environment	URL
Web	https://34cbdf41-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[agent-relay-code]

Automated end-to-end verification of the Relayfile review-bot guide in this PR: this review was created by writing a JSON draft to /github/repos/AgentWorkforce/agentrelay.com/pulls/59/reviews/ through Relayfile, with no GitHub API call and no GitHub token held by the writer.

[kjgbot]

Verified end to end against a live workspace

Ran the guide against a live Cloud workspace on relayfile 0.10.41. The writeback in step 7 is not a worked example — review 5112118049 on this PR was posted by writing the JSON draft the guide tells you to write, with no GitHub API call.

Addressing the review comments

• Guide vs cli.mdx mismatch (P2) — resolved in the guide's favour: writeback status, writeback retry --opId, integration available/search/set-metadata all exist in the binary. cli.mdx was the stale document — it listed relayfile permissions and seed --dry-run/--exclude/--batch-size, none of which exist. Fixed there.
• Brief placeholders (P3) — the note now lists every angle-bracket placeholder and splits set-once from per-run.
• Undefined client (P3) — the no-mount snippet now points at workspace.client() from step 1.

What the run found wrong

Claim	Reality
relayfile listen	Doesn't exist. Was also in events.mdx and introduction.mdx — replaced with integration bind / SDK onWrite.
relayfile permissions	Doesn't exist.
seed --dry-run	Rejected as undefined; seed and ops list also can't use a Cloud session.
<provider>/.layout.md	It's <provider>/LAYOUT.md.
Sibling .schema.json	Lives at /discovery/<provider>/…{owner}/{repo}/{pullNumber}/….
"id is the last __ segment"	GitHub is <number>__<slug>, number first. Linear is id-last.
pulls/59/meta.json	404 — reads need the full 59__<slug> directory. Writes take the bare number.
Review payload {event, body}	comments is required too.
PUT /fs/file	Needs If-Match as well as X-Correlation-Id (412 without).
status shows dead-lettered	It shows pending/conflicts/denied; dead-letter counts are in writeback status.
Records are provider JSON	They're envelopes; the object is under .payload.

Also found: one registered mirror per workspace per machine (a second mount is refused, --rehome moves it), workspace join --name renames an existing entry rather than adding one, and 429 workspace_busy is common enough on a busy workspace to need backoff.

Not verified

The local mount round-trip. This machine already mirrors the workspace for another project and re-homing it was not worth the risk, so reads and the writeback went through relayfile tree/read and the data-plane API. Everything else above was executed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NVwyjaMnm1PTRC6m7oXHJV

[cubic-dev-ai]

All reported issues were addressed across 9 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[kjgbot]

Correction: relayfile listen does exist

My previous comment claimed relayfile listen doesn't exist. That was wrong, and the mistake was mine twice over:

1. I tested against relayfile 0.10.41 while 0.10.53 was published.
2. More importantly, I concluded the command was missing because it wasn't in relayfile --help — instead of running it. listen is simply hidden from the help summary. It exists in both versions.

Re-ran it against 0.10.53. It works, and delivered the event for 3/3 test writes:

{"type":"file.created","path":"/runs/doc-verify-20260904/findings/listen-1.json",
 "revision":"rev_2935117","eventId":"evt_2507297","provider":"runs","origin":"agent_write",
 "contentType":"application/json","content":"{}","inlineContent":true,
 "correlationId":"lt-1-1788520629","timestamp":"2026-09-04T11:17:09.694Z"}

Two things that came out of doing it properly:

• Events inline small file content (inlineContent: true) and carry a correlationId from the write that caused them. events.mdx now shows a captured event instead of an invented one.
• The stream needs supervision. On this workspace it dies within seconds — read limited at 32769 bytes mid-message, or a frame EOF — and reconnecting immediately returns 429 on the WebSocket handshake. Both docs now say so.

listen was also missing from the CLI reference entirely; cli.mdx now documents it with its real flags (--provider, --path, --event, --run, --format text|json, --background) plus the note that relayfile help listen prints the generic help rather than its examples.

The revert touches events.mdx, introduction.mdx, and step 8 of the guide — all three are back to relayfile listen, which was right before I "fixed" it.

Still standing after re-testing on 0.10.53

No relayfile permissions; seed still rejects --dry-run/--exclude/--batch-size; status reports pending/conflicts/denied while writeback status reports pending/failed/dead-lettered; a second mount is still refused without --rehome. All the server-side findings (path shapes, /discovery, record envelopes, the review contract, If-Match) are version-independent and unchanged.

One thing I could not confirm

--run's {{path}} substitution. Five attempts; the stream dropped before an event reached the handler each time. The flag exists and the docs describe the templating — I just have no direct evidence of it firing.

Sidebar version badge updated 0.10.31 → 0.10.53.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NVwyjaMnm1PTRC6m7oXHJV

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[kjgbot]

--run substitution confirmed

The one item I'd left unverified is now verified. Single attempts kept losing the stream before an event arrived, so I drove it with a script that reconnects with backoff and only writes once the listener reports Listening on — it caught the event on the second attempt.

Handler invoked with --run "handler.sh {{path}} {{type}} {{provider}} {{revision}} {{event}}":

argc=17
ARG1=/runs/doc-verify-20260904/findings/drive-1-1.json   ← {{path}}
ARG2=file.created                                        ← {{type}}
ARG3=runs                                                ← {{provider}}
ARG4=rev_2936535                                         ← {{revision}}
ARG5=type:file.created                                   ┐
ARG6=path:/runs/doc-verify-20260904/findings/drive-1-1.json │
ARG7=revision:rev_2936535                                │ ← {{event}}
ARG8=eventId:evt_2508448                                 │
…                                                        │
ARG17=timestamp:2026-09-04T11:30:07.190Z                 ┘

{{event}} expands to the entire event as space-separated key:value pairs — 13 tokens here — so unquoted it splatters across argv. That's why the CLI's own embedded example writes '{{event}}' in quotes. Now documented with a warning.

All five placeholders come from the binary's own flag help — "shell command per event; supports {{path}}, {{type}}, {{provider}}, {{revision}}, {{event}}" — which no page documented; four of them appeared nowhere in our docs at all.

Also added: relayfile supervisor install accepts every listen flag and embeds them verbatim into a launchd/systemd unit that restarts on failure — the supported answer to the stream instability, and previously undocumented.

Cleanup

The verification scratch files under /runs/doc-verify-20260904/ are deleted; /runs is empty again. The review from the earlier writeback test stays on this PR as evidence.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NVwyjaMnm1PTRC6m7oXHJV