docs: document node-claim guard and provider subscriptions

web/content/docs/cli-broker-lifecycle.mdx

@@ -38,6 +38,7 @@ Flags:
 | `--workspace-key <key>` | Join a pre-existing Relay workspace. |
 | `--state-dir <path>` | Write runtime state outside `.agentworkforce/relay/`. |
 | `--broker-name <name>` | Override the broker identity. Defaults to the project directory basename. |
+| `--force` | Take the enrolled node over from a live broker on this machine; evicts that broker's delivery socket. |
 | `--verbose` | Enable verbose startup logging (raises the node log level to `debug`). |
 | `--log-file <path>` | Write structured node logs — each capability registered and every action invoked/completed — to a file. |
 | `--log-level <level>` | Node log verbosity: `debug` \| `info` \| `warn` \| `error` (default `info`). |
@@ -53,6 +54,20 @@ agent-relay node up --background --workspace-key "$RELAY_WORKSPACE_KEY"
 
 The broker listens on a local API port starting from `3888` (override with `AGENT_RELAY_BROKER_PORT`). If this machine was enrolled as a Cloud-managed node with `agent-relay cloud enroll`, `node up` picks up the persisted enrollment automatically and serves under the enrolled node name.
 
+### One broker per enrolled node
+
+An enrolled node has one Cloud delivery socket. If two brokers served the same node id, the second registration would evict the first broker's socket and it would silently stop receiving messages. `node up` prevents this with a machine-local claim in `~/.agentworkforce/relay/node-claims/`: the first broker claims its enrolled node id, and a later `node up` for that node — including one pinned with `RELAY_NODE_ID` — refuses and names the holding broker's pid and state directory.
+
+If the refusal is wrong, or you want the takeover:
+
+```bash
+agent-relay node down --state-dir <holder's state dir>   # stop the running broker
+agent-relay node up --workspace-key <different key>       # serve a different enrolled node
+agent-relay node up --force                               # take the node over anyway
+```
+
+`--force` evicts the incumbent's delivery socket: the old broker keeps running but stops receiving realtime delivery. A crashed broker's stale claim never blocks a restart, `--local-only` claims nothing, and `node down` releases the claim on clean exit.
+
 ## Check Status
 
 ```bash

web/content/docs/nodes.mdx

@@ -215,6 +215,8 @@ A node enrolls with `POST /v1/nodes` using the workspace key. The request carrie
 
 A node id supplied or pinned by an operator (`node_id` in the enroll request, used with its node token) is taken as-is. Otherwise the id derives from the machine identity, the working directory, and the workspace, so several nodes on one host — for example one per project directory — do not collide.
 
+The agent runtime also claims the enrolled id locally: a running broker records a claim, and a second broker for the same node on that host is refused instead of evicting the incumbent's delivery socket. See [Broker lifecycle → One broker per enrolled node](/docs/cli-broker-lifecycle#one-broker-per-enrolled-node).
+
 ## Presence And Context
 
 Workspace observers see node presence events as `node.online`, `node.heartbeat`, and `node.offline`. Each event carries a node payload matching the roster entry.

web/content/docs/provider-subscriptions.mdx

@@ -0,0 +1,63 @@
+---
+title: 'Provider Subscriptions'
+description: 'Bind a provider resource — a repo, a team, a channel — to an agent so provider events wake it.'
+---
+
+Provider subscriptions bind an external resource to a Relay recipient. When an event fires — an issue opened, a comment posted — Relayfile writes it to the mounted tree and Relay delivers it as a message that wakes the recipient.
+
+```bash
+agent-relay integration subscribe github \
+  --to @watcher \
+  --resource AgentWorkforce/software-garden \
+  --events issues,issue_comment
+```
+
+The recipient is an agent (`@watcher`) or a channel (`#triage`). The agent does not need to exist yet; `--spawn` creates it.
+
+## What the agent sees
+
+Each event is a message from the provider identity (`github`) with the event type and the Relayfile path holding the payload:
+
+```
+Relay message from github: Github issue_comment.created
+Relayfile path: /github/repos/AgentWorkforce/software-garden/issues/531/comments/5744794683/meta.json
+```
+
+The mounted file holds the full payload — the same tree as [Relayfile integrations](/docs/file/integrations). An in-channel reply posts back to the issue or thread when the provider supports writeback.
+
+Events that arrive while the node is disconnected queue durably and replay on reconnect, so a subscription survives broker restarts. See [Delivery](/docs/delivery).
+
+## Spawning a recipient
+
+`--spawn <cli>` launches a new agent and confirms it is live before subscribing:
+
+```bash
+agent-relay integration subscribe github \
+  --resource AgentWorkforce/software-garden \
+  --events issues,issue_comment \
+  --spawn claude --task "Triage new issue comments and reply with a summary."
+```
+
+## Managing subscriptions
+
+```bash
+agent-relay integration subscribe --list                                   # active bindings
+agent-relay integration unsubscribe github --resource AgentWorkforce/software-garden
+```
+
+Unsubscribing removes the binding and its inbound webhook; agents and channels are untouched.
+
+<CardGroup cols={2}>
+  <Card title="Events" href="/docs/events">
+    The event vocabulary subscriptions and listeners share.
+  </Card>
+  <Card title="Relayfile integrations" href="/docs/file/integrations">
+    How provider resources become files an agent can read and watch.
+  </Card>
+  <Card title="Delivery" href="/docs/delivery">
+    Sequencing, acks, and reconnect replay for node-delivered events.
+  </Card>
+  <Card title="CLI reference" href="/docs/reference-cli">
+    The full `integration` command surface.
+  </Card>
+</CardGroup>

web/content/docs/webhooks.mdx

@@ -10,7 +10,8 @@ directions, both under the `relay.webhooks` namespace:
 - **Outbound:** subscribe your service to Relay events. Relay POSTs HMAC-signed event payloads to your URL.
 
 Provider connections (Slack, GitHub App installs, and similar) live under the separate `relay.integrations`
-namespace — don't conflate it with webhooks.
+namespace — don't conflate it with webhooks. To wake an agent on provider events like GitHub issues and
+comments, use [Provider subscriptions](/docs/provider-subscriptions).
 
 ## Inbound: external services into Relay
 

web/lib/docs-nav.ts

@@ -41,6 +41,7 @@ export const docsNav: NavGroup[] = [
       { title: 'Events', slug: 'events' },
       { title: 'Event handlers', slug: 'event-handlers' },
       { title: 'Webhooks', slug: 'webhooks' },
+      { title: 'Provider subscriptions', slug: 'provider-subscriptions' },
     ],
   },
   {