Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-console): 0.19.0 — AgentBBS section in the x.ruv.io view (rooms, envelopes, pinned peers, sync, serve), ADR-417

ruv4e8d34fd6f4b
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index 2d433c26a6..82f7841de9 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a; no network by default.",
- "version": "0.18.0",
+ "version": "0.19.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/hooks/views/xruv.ts b/plugins/ruflo-console/hooks/views/xruv.ts
index 43ef2fe333..b716d0dd11 100644
--- a/plugins/ruflo-console/hooks/views/xruv.ts
+++ b/plugins/ruflo-console/hooks/views/xruv.ts
@@ -2,7 +2,7 @@ import type { RenderElement } from 'claude-code'
import type { Channels, Registry, Roster } from '../data/cli'
import type { SwarmMessages, WorkClaims } from '../data/xruv'
-import { INVITE_COMMAND, UNREGISTER_WHY, XRUV, type XEntry, type XGroup } from '../xruv'
+import { BBS_SERVE_COMMAND, INVITE_COMMAND, UNREGISTER_WHY, XRUV, type XEntry, type XGroup } from '../xruv'
import { ago, button, clip, col, kv, live, row, rule, sourceLine, text, THEME, type Ctx } from './common'
/** Result lines in view at once; j/k scroll the rest. */
@@ -19,6 +19,7 @@ function rowButton(ctx: Ctx, entry: XEntry): RenderElement | null {
if (entry.id === 'x-unregister' || isAdminOff) return null
// The invite code is a bearer secret: it is minted in the terminal, where only the person reads it.
+ if (entry.id === 'x-bbs-serve') return ctx.kit.Button({ key: 'xr-x-bbs-serve', label: ' â–¸ type', plain: true, dimColor: true, onPress: () => ctx.act.term.load('ruflo', BBS_SERVE_COMMAND) })
if (entry.id === 'x-invite') return ctx.kit.Button({ key: 'xr-x-invite', label: ' â–¸ type', plain: true, dimColor: true, onPress: () => ctx.act.term.load('ruflo', INVITE_COMMAND) })
if (entry.takes !== undefined && entry.id !== 'x-join') return null
@@ -32,6 +33,7 @@ function rowButton(ctx: Ctx, entry: XEntry): RenderElement | null {
*/
function pressOf(ctx: Ctx, entry: XEntry): () => void {
if (entry.id === 'x-invite') return () => ctx.act.term.load('ruflo', INVITE_COMMAND)
+ if (entry.id === 'x-bbs-serve') return () => ctx.act.term.load('ruflo', BBS_SERVE_COMMAND)
if (entry.takes !== undefined && entry.id !== 'x-join') return () => ctx.act.focus(`xr-in-${entry.id}`)
return () => void ctx.act.run(entry.id)
@@ -196,6 +198,27 @@ function adminRows(ctx: Ctx, lead: number): RenderElement[] {
return rows
}
+/** AgentBBS: rooms, envelopes and pinned peers on this machine; only SYNC reaches the network, and it asks first. */
+function agentbbsRows(ctx: Ctx, lead: number): RenderElement[] {
+ const rows: RenderElement[] = [rule(ctx, 'AgentBBS', 'rooms · envelopes · pinned peers · federation_bbs_* tools')]
+ const placeholders: Record<string, string> = {
+ 'x-bbs-register': '#sales — Enter asks',
+ 'x-bbs-publish': '<roomId> Status: build green — Enter asks',
+ 'x-bbs-watch': '<roomId> 20 — Enter reads it',
+ 'x-bbs-peer-add': '<16-hex node id> http://100.x.y.z:7777 <64-hex key> — Enter asks',
+ 'x-bbs-sync': '<roomId> [nodeId] — Enter asks (network)',
+ }
+
+ for (const entry of entriesOf('agentbbs')) {
+ rows.push(entryRow(ctx, entry, lead))
+ if (entry.takes !== undefined) rows.push(field(ctx, entry, placeholders[entry.id] ?? entry.takes))
+ }
+
+ rows.push(text(ctx, ' No join-as-human row: it mints a bearer token, which the console never shows. Use the terminal for it.', { dimColor: true }))
+
+ return rows
+}
+
/** The last board run: what it was, how it exited, what it sends, and a window of its lines. */
function resultRows(ctx: Ctx): RenderElement[] {
const { state, nowMs } = ctx
@@ -257,6 +280,7 @@ export function xruvView(ctx: Ctx): RenderElement {
...identityRows(ctx, lead),
...networkRows(ctx, lead),
...channelRows(ctx, lead),
+ ...agentbbsRows(ctx, lead),
...adminRows(ctx, lead),
]
diff --git a/plugins/ruflo-console/hooks/xruv.ts b/plugins/ruflo-console/hooks/xruv.ts
index 8a90a1218a..3b79ee68c4 100644
--- a/plugins/ruflo-console/hooks/xruv.ts
+++ b/plugins/ruflo-console/hooks/xruv.ts
@@ -100,6 +100,43 @@ export function admitArg(raw: string): { pubkey: string; role: 'member' | 'admin
export const maskInvites = (line: string): string => line.replace(INVITE_ANYWHERE, 'v2.•••• (invite code, masked)')
const exec = (tool: string, params: Record<string, unknown>) => ['mcp', 'exec', '-t', tool, '-p', JSON.stringify(params)] as const
+
+const ROOM_ID_RE = /^[A-Za-z0-9_.:@#/-]{1,128}$/
+const NODE_ID_RE = /^[0-9a-f]{16}$/
+const BBS_LABEL_RE = /^[A-Za-z0-9_.\-:/@# ]{1,64}$/
+
+/** `<roomId> Type: text`, as the agentbbs publish Input takes it. */
+export function bbsPublishArg(raw: string): { roomId: string; msgType: string; payload: Record<string, unknown> } | null {
+ const [first = '', ...rest] = raw.trim().split(/\s+/)
+ const message = messageArg(raw.trim().slice(first.length))
+
+ return ROOM_ID_RE.test(first) && rest.length > 0 && message !== null ? { roomId: first, ...message } : null
+}
+
+/** `<roomId> [limit]`: the room to read and how many envelopes (1-500, 20 when unsaid). */
+export function bbsWatchArg(raw: string): { roomId: string; limit: number } | null {
+ const [roomId = '', count = '20', ...extra] = raw.trim().split(/\s+/)
+ const limit = Number(count)
+
+ return ROOM_ID_RE.test(roomId) && /^\d{1,3}$/.test(count) && limit >= 1 && limit <= 500 && extra.length === 0 ? { roomId, limit } : null
+}
+
+/** `<nodeId> <url> <64-hex publicKey> [label…]`: a peer pinned out of band. */
+export function bbsPeerArg(raw: string): { nodeId: string; url: string; publicKey: string; label?: string } | null {
+ const [nodeId = '', url = '', publicKey = '', ...label] = raw.trim().split(/\s+/)
+ const name = label.join(' ')
+
+ if (!NODE_ID_RE.test(nodeId) || !/^https?:\/\/[A-Za-z0-9.-]+(:\d{1,5})?\/?$/.test(url) || !isPubkey(publicKey) || (name !== '' && !BBS_LABEL_RE.test(name))) return null
+
+ return { nodeId, url: url.replace(/\/$/, ''), publicKey: publicKey.toLowerCase(), ...(name === '' ? {} : { label: name }) }
+}
+
+/** `<roomId> [nodeId]`: the room to converge, from one pinned peer or all of them. */
+export function bbsSyncArg(raw: string): { roomId: string; nodeId?: string } | null {
+ const [roomId = '', nodeId, ...extra] = raw.trim().split(/\s+/)
+
+ return ROOM_ID_RE.test(roomId) && (nodeId === undefined || NODE_ID_RE.test(nodeId)) && extra.length === 0 ? { roomId, ...(nodeId === undefined ? {} : { nodeId }) } : null
+}
const ago = (atMs: number | undefined, nowMs: number) => (atMs === undefined ? '' : ` · ${Math.max(0, Math.round((nowMs - atMs) / 60_000))}m ago`)
/** One run's output as the result panel's lines: each read by its shape, anything else flattened, invite codes masked. */
@@ -158,7 +195,7 @@ export function ownPubkeyOf(id: string, stdout: string): string | null {
}
export type XKind = 'read' | 'write' | 'admin'
-export type XGroup = 'identity' | 'live' | 'channels' | 'admin'
+export type XGroup = 'identity' | 'live' | 'channels' | 'admin' | 'agentbbs'
export type XEntry = {
id: string
@@ -312,6 +349,62 @@ export const XRUV: readonly XEntry[] = [
spec: state => spec(state, 'x-accept', { label: 'accept x.ruv.io channel grants sealed to your key', args: exec('x_federation_channel_accept', {}), expect: 'the channels accepted', note: `network: reads the last 7 days of grants on ${RELAY} and stores their keys in ~/.ruflo/channels.json; ${MAKES_KEY}`, timeoutMs: 60_000 }),
why: () => '',
},
+ {
+ id: 'x-bbs-peers', group: 'agentbbs', name: 'PEERS', about: 'the pinned peers and when each last synced', label: 'list the pinned agentbbs peers', kind: 'read',
+ spec: state => spec(state, 'x-bbs-peers', { label: 'list the pinned agentbbs peers (federation_bbs_peers)', args: exec('federation_bbs_peers', {}), expect: 'the peers and their keys', isReadOnly: true, timeoutMs: 30_000 }),
+ why: () => '',
+ },
+ {
+ id: 'x-bbs-register', group: 'agentbbs', name: 'ROOM', about: 'a room label like #sales becomes a stable room id', label: 'register an agentbbs room', kind: 'write', takes: '#sales',
+ spec: (state, text) => {
+ const roomLabel = text.trim()
+
+ return BBS_LABEL_RE.test(roomLabel) ? spec(state, 'x-bbs-register', { label: `register the agentbbs room ${roomLabel}`, args: exec('federation_bbs_register', { roomLabel }), expect: 'the room id', note: 'local, $0: writes room state under .agentbbs in this project' }) : null
+ },
+ why: () => 'type a room label such as "#sales": letters, digits and _ . - : / @ # only, 64 characters at most',
+ },
+ {
+ id: 'x-bbs-publish', group: 'agentbbs', name: 'PUBLISH', about: 'append a typed event to a room log', label: 'publish an envelope to an agentbbs room', kind: 'write', takes: '<roomId> Type: text',
+ spec: (state, text) => {
+ const arg = bbsPublishArg(text)
+
+ return arg === null ? null : spec(state, 'x-bbs-publish', { label: `publish ${arg.msgType} to room ${arg.roomId}`, args: exec('federation_bbs_publish', arg), expect: 'an envelope id and its sequence number', note: 'local, $0: appends one signed envelope to the room log; peers only see it after a sync' })
+ },
+ why: () => 'type "<roomId> Type: text", e.g. "abc123 Status: build green" (the room id comes from ROOM)',
+ },
+ {
+ id: 'x-bbs-watch', group: 'agentbbs', name: 'WATCH', about: 'the latest envelopes in a room', label: 'read recent agentbbs envelopes', kind: 'read', takes: '<roomId> [limit]',
+ spec: (state, text) => {
+ const arg = bbsWatchArg(text)
+
+ return arg === null ? null : spec(state, 'x-bbs-watch', { label: `read the last ${arg.limit} envelopes of room ${arg.roomId}`, args: exec('federation_bbs_watch', arg), expect: 'the envelopes, oldest first', isReadOnly: true, timeoutMs: 30_000 })
+ },
+ why: () => 'type "<roomId> [limit]": limit is 1 to 500, 20 when left out',
+ },
+ {
+ id: 'x-bbs-peer-add', group: 'agentbbs', name: 'PIN PEER', about: 'trust one peer by node id, URL and public key', label: 'pin an agentbbs peer', kind: 'write', takes: '<nodeId> <url> <pubkey> [label]',
+ spec: (state, text) => {
+ const arg = bbsPeerArg(text)
+
+ return arg === null ? null : spec(state, 'x-bbs-peer-add', { label: `pin peer ${arg.nodeId} at ${arg.url}`, args: exec('federation_bbs_peer_add', arg), expect: 'the peer pinned', note: 'local, $0: records the key you typed; every envelope from this peer is verified against it, and a different key for a known node is refused' })
+ },
+ why: () => 'type "<16-hex nodeId> <http(s) url> <64-hex public key> [label]": take all three from the peer own BBS IDENTITY, not from an envelope',
+ },
+ {
+ id: 'x-bbs-sync', group: 'agentbbs', name: 'SYNC ROOM', about: 'pull a room from pinned peers and merge what verifies', label: 'sync an agentbbs room from its peers', kind: 'write', takes: '<roomId> [nodeId]',
+ spec: (state, text) => {
+ const arg = bbsSyncArg(text)
+
+ return arg === null ? null : spec(state, 'x-bbs-sync', { label: `sync room ${arg.roomId} from ${arg.nodeId ?? 'every pinned peer'}`, args: exec('federation_bbs_sync', arg), expect: 'envelopes merged and dropped, per peer', note: 'network: fetches from the pinned peer URLs only; unsigned, misattributed or oversize envelopes are dropped and counted', timeoutMs: 90_000 })
+ },
+ why: () => 'type "<roomId> [nodeId]": pin a peer first (PIN PEER); with no node id every pinned peer is asked',
+ },
+ {
+ id: 'x-bbs-serve', group: 'agentbbs', name: 'SERVE', about: 'the read-only endpoint peers pull from: run it in a terminal', label: 'serve this node to peers (in the terminal)', kind: 'write',
+ // A server that stays up for hours does not fit a one-shot board run, and bindHost decides who can reach it: that is typed where the person sees it.
+ spec: () => null,
+ why: () => 'serve keeps running and binds 127.0.0.1 unless you name a tailnet bindHost: â–¸ type puts the command in the terminal (i) for you to run',
+ },
{
id: 'x-hub', group: 'admin', name: 'HUB PUBLISH', about: 'a broadcast signed as the gateway, not as you', label: 'publish to the x.ruv.io swarm as the gateway (admin)', kind: 'admin', takes: 'Type: text (or a JSON object)',
spec: (state, text) =>
@@ -344,6 +437,9 @@ export const XRUV: readonly XEntry[] = [
},
]
+/** What the SERVE row types into the terminal: loopback by default; a tailnet bindHost is the person's to add. */
+export const BBS_SERVE_COMMAND = 'mcp exec -t federation_bbs_serve -p \'{"port":7777}\''
+
/** What the INVITES row types into the terminal: the code then shows only in its scrollback, never in an answer. */
export const INVITE_COMMAND = 'federation invite --ttl 604800 --uses 25'
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index 24f2ac2417..569d5fa04b 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.18.0"
+step "1. plugin.json declares ruflo-console 0.19.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.18.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.19.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-console/tests/agentbbs.spec.ts b/plugins/ruflo-console/tests/agentbbs.spec.ts
new file mode 100644
index 0000000000..92a4d8df48
--- /dev/null
+++ b/plugins/ruflo-console/tests/agentbbs.spec.ts
@@ -0,0 +1,61 @@
+/**
+ * The AgentBBS rows of the x.ruv.io board, pure: the argument parsers lifted from the tool schemas, what runs at once,
+ * what asks, and what is typed into a terminal instead of run. Run with
+ * npx vitest run plugins/ruflo-console/tests/agentbbs.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { newState } from '../hooks/state'
+import { bbsPeerArg, bbsPublishArg, bbsSyncArg, bbsWatchArg, XRUV } from '../hooks/xruv'
+
+const KEY = 'c0ffee'.repeat(10) + 'beef'
+const NODE = '0123456789abcdef'
+const entry = (id: string) => {
+ const found = XRUV.find(candidate => candidate.id === id)
+
+ if (found === undefined) throw new Error(`no entry ${id}`)
+
+ return found
+}
+const params = (args: readonly string[] | undefined) => JSON.parse(args?.[5] ?? 'null') as unknown
+
+describe('agentbbs rows', () => {
+ it('a room label registers, a malformed one does not', () => {
+ expect(params(entry('x-bbs-register').spec(newState({}), '#sales')?.args)).toEqual({ roomLabel: '#sales' })
+ expect(entry('x-bbs-register').spec(newState({}), 'bad;label')).toBeNull()
+ expect(entry('x-bbs-register').spec(newState({}), '')).toBeNull()
+ })
+
+ it('publish needs a room id and a body; the type defaults to Status', () => {
+ expect(bbsPublishArg('room1 Alert: disk full')).toEqual({ roomId: 'room1', msgType: 'Alert', payload: expect.anything() })
+ expect(bbsPublishArg('room1 just words')?.msgType).toBe('Status')
+ expect(bbsPublishArg('room1')).toBeNull()
+ expect(bbsPublishArg('bad$room hi')).toBeNull()
+ expect(entry('x-bbs-publish').spec(newState({}), 'room1')).toBeNull()
+ })
+
+ it('watch takes a limit from 1 to 500 and reads at once', () => {
+ expect(bbsWatchArg('room1')).toEqual({ roomId: 'room1', limit: 20 })
+ expect(bbsWatchArg('room1 500')?.limit).toBe(500)
+ expect(bbsWatchArg('room1 501')).toBeNull()
+ expect(bbsWatchArg('room1 0')).toBeNull()
+ expect(entry('x-bbs-watch').spec(newState({}), 'room1 5')?.isReadOnly).toBe(true)
+ })
+
+ it('a pinned peer needs a 16-hex node id, an http(s) url and a 64-hex key', () => {
+ expect(bbsPeerArg(`${NODE} http://100.1.2.3:7777/ ${KEY} desk box`)).toEqual({ nodeId: NODE, url: 'http://100.1.2.3:7777', publicKey: KEY, label: 'desk box' })
+ expect(bbsPeerArg(`${NODE} ftp://host ${KEY}`)).toBeNull()
+ expect(bbsPeerArg(`${NODE.slice(1)} http://h ${KEY}`)).toBeNull()
+ expect(bbsPeerArg(`${NODE} http://h ${KEY.slice(1)}`)).toBeNull()
+ expect(bbsPeerArg(`${NODE} http://user@h ${KEY}`)).toBeNull()
+ })
+
+ it('sync is the only row that says it uses the network; serve is typed in a terminal, not run', () => {
+ expect(bbsSyncArg(`room1 ${NODE}`)).toEqual({ roomId: 'room1', nodeId: NODE })
+ expect(bbsSyncArg('room1 nothex')).toBeNull()
+ expect(entry('x-bbs-sync').spec(newState({}), 'room1')?.note).toContain('network')
+ expect(entry('x-bbs-register').spec(newState({}), '#a')?.note).toContain('local')
+ expect(entry('x-bbs-serve').spec(newState({}), '')).toBeNull()
+ expect(entry('x-bbs-serve').why(newState({}), '')).toContain('127.0.0.1')
+ })
+})
diff --git a/plugins/ruflo-console/tests/xruv.test.ts b/plugins/ruflo-console/tests/xruv.test.ts
index ba4b246e38..35cd41d926 100644
--- a/plugins/ruflo-console/tests/xruv.test.ts
+++ b/plugins/ruflo-console/tests/xruv.test.ts
@@ -39,7 +39,8 @@ describe('x.ruv.io board', () => {
const tree = await pane.drawn()
const text = textOf(tree)
- expect(elementsOf(tree, 'Button').map(keyOf)).toEqual(expect.arrayContaining(['xr-x-join', 'xr-x-bbs-identity', 'xr-x-registry', 'xr-x-roster', 'xr-x-claims', 'xr-x-sync', 'xr-x-channels', 'xr-x-accept']))
+ expect(elementsOf(tree, 'Button').map(keyOf)).toEqual(expect.arrayContaining(['xr-x-join', 'xr-x-bbs-identity', 'xr-x-registry', 'xr-x-roster', 'xr-x-claims', 'xr-x-sync', 'xr-x-channels', 'xr-x-accept', 'xr-x-bbs-peers', 'xr-x-bbs-serve']))
+ expect(elementsOf(tree, 'Input').map(keyOf)).toEqual(expect.arrayContaining(['xr-in-x-bbs-register', 'xr-in-x-bbs-publish', 'xr-in-x-bbs-watch', 'xr-in-x-bbs-peer-add', 'xr-in-x-bbs-sync']))
expect(elementsOf(tree, 'Input').map(keyOf)).toEqual(expect.arrayContaining(['xr-in-x-join', 'xr-in-x-read', 'xr-in-x-publish', 'xr-in-x-create', 'xr-in-x-grant']))
expect(text).toContain(' JOIN ....')
expect(text).toContain('present: ~/.ruflo/nostr.key (never read here)')
diff --git a/v3/docs/adr/ADR-417-console-agentbbs-section.md b/v3/docs/adr/ADR-417-console-agentbbs-section.md
new file mode 100644
index 0000000000..357882fe9e
--- /dev/null
+++ b/v3/docs/adr/ADR-417-console-agentbbs-section.md
@@ -0,0 +1,59 @@
+# ADR 417: The AgentBBS section of the x.ruv.io view
+
+Status: Accepted (ships in ruflo-console 0.19.0)
+
+Date: 2026 10 03
+
+Decision owner: Ruflo maintainers
+
+Scope: `plugins/ruflo-console`: `hooks/xruv.ts` (the catalog and the argument parsers), `hooks/views/xruv.ts` (the section), `tests/agentbbs.spec.ts`, `tests/xruv.test.ts`.
+
+Extends: ADR 407. Companion to ADR 412 (answers open where asked) and ADR 411 (Ask Claude).
+
+## 1. Context
+
+ruflo ships nine `federation_bbs_*` MCP tools (rooms, envelopes, pinned peers, a pull endpoint, sync). The console reached only `federation_bbs_identity`, as one row among the x.ruv.io identity rows. Someone who wanted to register a room, publish to it or pin a peer had to leave the console and write the tool call by hand.
+
+The x.ruv.io view already owns `ruflo-bbs-federation` in the plugin map and already has the pattern these tools need: a catalog entry with fixed argv through `mcp exec -t`, a typed field, a confirm row for anything that writes, and a result panel at the top.
+
+## 2. Decision
+
+Add an **AgentBBS** section to the x.ruv.io view, between Channels and Admin, as seven catalog entries in a new `agentbbs` group.
+
+| Row | Tool | Kind | Takes | Reach |
+|---|---|---|---|---|
+| PEERS | `federation_bbs_peers` | read | nothing | local |
+| ROOM | `federation_bbs_register` | write | `#sales` | local |
+| PUBLISH | `federation_bbs_publish` | write | `<roomId> Type: text` | local |
+| WATCH | `federation_bbs_watch` | read | `<roomId> [limit]` | local |
+| PIN PEER | `federation_bbs_peer_add` | write | `<nodeId> <url> <pubkey> [label]` | local |
+| SYNC ROOM | `federation_bbs_sync` | write | `<roomId> [nodeId]` | network |
+| SERVE | `federation_bbs_serve` | typed in the terminal | nothing | long-running |
+
+- Reads run at once; writes ask first and the confirm row says whether the effect is local or on the network. Only SYNC reaches the network, and only to the URLs of peers already pinned.
+- Every argument is validated before anything runs, with the same shapes the tools enforce: room ids and labels from a restricted character set, a 1 to 500 limit, a 16-hex node id, a 64-hex public key, and a peer URL that is plain `http(s)://host[:port]`. A URL carrying credentials is refused, so a secret can never be written into `peers.json` by the console.
+- **SERVE is not run by the board.** The endpoint stays up for hours and `bindHost` decides who can reach it. The row types the command (loopback, port 7777) into the terminal for the person to run, and to add a tailnet `bindHost` themselves.
+- **`federation_bbs_human_join` is deliberately not offered.** It mints a bearer token for a human operator. The console never shows a bearer secret (the same rule as invite codes), so the section says to use the terminal.
+
+## 3. Alternatives considered
+
+- **A new view.** Rejected: the x.ruv.io view already owns the plugin and its confirm and result machinery; a second view would split one federation story.
+- **Running SERVE from the board.** Rejected: a one-shot run with a timeout is the wrong shape for a server, and the bind address is a network decision.
+- **Letting peer_add take a key from a result or an envelope.** Rejected: the tool's own description says trusting a key carried in an envelope proves nothing. The person types all three values from the peer's own identity.
+
+## 4. Consequences
+
+- Rooms, envelopes and pinned peers are reachable from the console with no hand-written tool call.
+- The catalog file grows to 453 lines, under the 500-line limit.
+- A future `federation_bbs_peers` unpin (the `remove` parameter) can be added as one more entry; it is left out here because it is not a pure read or a pure add and deserves its own confirm wording.
+
+## 5. Safety
+
+- No secret is read or shown: the node's private key stays in `.agentbbs/node-identity.json`, which no tool here returns.
+- Every write is confirm-gated; every row that can reach the network says so.
+- Spend: none. All seven tools are $0.
+
+## 6. Tests
+
+- `tests/agentbbs.spec.ts`: each parser accepts its good shape and refuses the bad ones (including a credentialed URL), the reads are read-only, SYNC says "network", the local writes say "local", SERVE returns no spec and explains the loopback default.
+- `tests/xruv.test.ts`: the section's buttons and fields are on the board.