[kata/root/M015/S05] Plugin Documentation Update

[wollax]

Summary

Updates the plugins/smelt-agent/ documentation for M015 distributed signal capabilities.

Changes

• AGENTS.md: adds poll_signals and send_signal to MCP tools table; adds supports_signals and supports_peer_registry capability section; adds cross-instance forwarding overview
• skills/peer-message.md: adds signal-based messaging section covering poll_signals/send_signal as the agent-facing interface; documents ASSAY_SIGNAL_BIND and ASSAY_SIGNAL_URL
• skills/peer-registry.md (new): documents peer discovery via peers.json, PeerInfo type shape, backend lifecycle, cross-instance forwarding, loop prevention, multi-machine topology
• tests/verify-docs.sh (new): structural test verifying all doc-referenced MCP tool names exist in the router

Verification

• bash plugins/smelt-agent/tests/verify-docs.sh passes
• just ready green

[Copilot]

Pull request overview

Updates the plugins/smelt-agent/ documentation to describe M015 distributed signaling concepts (signal-based peer messaging and peer registry), and adds a lightweight structural check to keep documented MCP tool names aligned with the MCP router.

Changes:

• Document signal-based messaging (poll_signals, send_signal) and cross-instance forwarding concepts in the smelt-agent docs.
• Add new /assay:peer-registry skill describing peer discovery/registration and forwarding topology.
• Add plugins/smelt-agent/tests/verify-docs.sh to verify doc-referenced MCP tool names exist in crates/assay-mcp/src/server.rs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
plugins/smelt-agent/tests/verify-docs.sh	Adds a doc/tool-name structural verification script against the MCP router.
plugins/smelt-agent/skills/run-dispatch.md	Documents smelt as a state_backend config option in manifests.
plugins/smelt-agent/skills/peer-registry.md	New skill documenting peer registry + cross-instance forwarding behavior and setup.
plugins/smelt-agent/skills/peer-message.md	Adds signal-based messaging guidance using poll_signals / send_signal.
plugins/smelt-agent/AGENTS.md	Updates skills/tools list and documents forwarding + signal endpoint env vars.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

PENDING_TOOLS includes poll_signals and send_signal, but both tools are already present in crates/assay-mcp/src/server.rs (they are #[tool] pub async fn in the router). Marking them as pending means this test will stop validating these docs against the router and could let future renames/drift slip through unnoticed. Consider removing them from PENDING_TOOLS, or only treating a tool as pending when it is actually absent from the router output.

Suggested change

	# These are documented in advance of the M015 merge and will be
	# validated once M015 lands.
	PENDING_TOOLS="poll_signals send_signal"
	# Currently none; add tool names here temporarily if docs lead server.rs.
	PENDING_TOOLS=""

[Copilot]

The docs state that SmeltBackend supports peer registry / cross-instance forwarding, but the code currently reports supports_peer_registry: false for SmeltBackend (and does not implement list_peers/unregister_peer). As written, using SmeltBackend will disable forwarding because the signal server gates forwarding on capabilities().supports_peer_registry. Please update the docs to match current behavior, or (if the intended behavior is support) update the backend capability flag and implementations in code.

Suggested change

	Registers peers by POSTing `PeerInfo` JSON to `{smelt_url}/api/v1/peers`. Graceful degradation — registration failure logs a warning but does not abort startup. `list_peers` and `unregister_peer` use the default no-op implementations (Smelt manages peer lifecycle server-side).
	### Other Backends
	`NoopBackend`, `LinearBackend`, `GitHubBackend`, and `SshSyncBackend` all return `supports_peer_registry: false` and use the default no-op implementations.
	## Automatic Lifecycle
	The MCP server manages peer registration automatically:
	1. **On startup** — after the signal endpoint binds, the server calls `register_peer` with its hostname and `signal_url` derived from `ASSAY_SIGNAL_BIND` and `ASSAY_SIGNAL_PORT`.
	2. **On clean shutdown** — the server calls `unregister_peer` to remove itself.
	No manual registration is needed for normal operation.
	As of this version, `SmeltBackend` reports `supports_peer_registry: false` and relies on the default no-op implementations of `register_peer`, `list_peers`, and `unregister_peer`. Deployments using `SmeltBackend` do not currently participate in the peer registry or cross-instance signal forwarding.
	### Other Backends
	`SmeltBackend`, `NoopBackend`, `LinearBackend`, `GitHubBackend`, and `SshSyncBackend` all return `supports_peer_registry: false` and use the default no-op implementations.
	## Automatic Lifecycle
	When using a backend that reports `supports_peer_registry: true` (for example, `LocalFsBackend`), the MCP server manages peer registration automatically:
	1. **On startup** — after the signal endpoint binds, the server calls `register_peer` with its hostname and `signal_url` derived from `ASSAY_SIGNAL_BIND` and `ASSAY_SIGNAL_PORT`.
	2. **On clean shutdown** — the server calls `unregister_peer` to remove itself (this is a no-op for backends like `SmeltBackend` that do not support the peer registry).
	No manual registration is needed for normal operation when the selected backend supports the peer registry.

[Copilot]

This step says the server derives signal_url from ASSAY_SIGNAL_BIND and ASSAY_SIGNAL_PORT, but the server code uses ASSAY_SIGNAL_URL as an override (and warns that 0.0.0.0 is unroutable for peer registration). The docs should mention ASSAY_SIGNAL_URL and recommend setting it in multi-machine deployments to a reachable host/IP.

Suggested change

1. **On startup** — after the signal endpoint binds, the server calls `register_peer` with its hostname and `signal_url` derived from `ASSAY_SIGNAL_BIND` and `ASSAY_SIGNAL_PORT`.

1. **On startup** — after the signal endpoint binds, the server calls `register_peer` with its hostname and `signal_url`. If `ASSAY_SIGNAL_URL` is set, that value is used directly. Otherwise, `signal_url` is derived from `ASSAY_SIGNAL_BIND` and `ASSAY_SIGNAL_PORT` (note that `0.0.0.0` is not routable from other machines, so in multi-machine deployments you should set `ASSAY_SIGNAL_URL` to a reachable host or IP).

[Copilot]

The environment variable table omits ASSAY_SIGNAL_URL, but the server supports it and it is required for correct peer registration when binding ASSAY_SIGNAL_BIND=0.0.0.0 (otherwise peers get an unroutable URL). Please document ASSAY_SIGNAL_URL here (and its relationship to ASSAY_SIGNAL_BIND/ASSAY_SIGNAL_PORT).

[Copilot]

The capability guard lists SmeltBackend as supports_peer_registry: true, but SmeltBackend currently reports supports_peer_registry: false in code. This list should be corrected so operators don’t assume peer forwarding works on Smelt-backed deployments.

Suggested change

	- `supports_peer_registry: true` — `LocalFsBackend`, `SmeltBackend`
	- `supports_peer_registry: false` — `NoopBackend`, `LinearBackend`, `GitHubBackend`, `SshSyncBackend`
	- `supports_peer_registry: true` — `LocalFsBackend`
	- `supports_peer_registry: false` — `SmeltBackend`, `NoopBackend`, `LinearBackend`, `GitHubBackend`, `SshSyncBackend`

[Copilot]

This says signals are consumed on read with “exactly-once delivery”, but the underlying inbox polling is best-effort and can deliver duplicates if file deletion fails (it logs a warning: “may be delivered twice”). Also, poll_signals can consume-but-skip malformed messages during JSON decode. Please soften this claim (e.g., at-least-once / best-effort) to match actual semantics.

Suggested change

	Returns a `PollSignalsResult` with a `signals` array of `PeerUpdate` objects. Messages are consumed on read (exactly-once delivery).
	Returns a `PollSignalsResult` with a `signals` array of `PeerUpdate` objects. Messages are removed from the inbox on a best-effort, at-least-once basis; callers should tolerate occasional duplicates and understand that malformed messages may be consumed but skipped.

[Copilot]

This states “SmeltBackend supports both” supports_signals and supports_peer_registry, but SmeltBackend currently reports supports_peer_registry: false in code, which disables forwarding. Please update the backend matrix here to match actual capability flags.

Suggested change

	13. **Check `supports_signals` and `supports_peer_registry`** to determine if signal-based messaging and cross-instance forwarding are available. The `SmeltBackend` supports both; `LocalFsBackend` supports peer registry but not signal push; `NoopBackend` supports neither.
	13. **Check `supports_signals` and `supports_peer_registry`** to determine if signal-based messaging and cross-instance forwarding are available. The `SmeltBackend` supports signals but not the peer registry; `LocalFsBackend` supports the peer registry but not signal push; `NoopBackend` supports neither.