Skip to content

docs(j5): peering docs drifted from the shipped behavior #487

Closed

Description

@Jacksondr5

Follow-up to the peering poll-mode stack (#400–#408), from Bryant's review (#400, #407, #408) and CodeRabbit. Part of #399. Docs only. The definition changes that come with the poll-mode robustness and peering-lifecycle issues ship in those issues' PRs.

docs/j5/product/cross-device.md

  • Availability is only measured for polling peers. "whether a peer server is available" should become "whether a peer server that polls this one is available". availabilityOf in PeerDirectory.ts returns null for other modes, and agent-tools.md already says nothing measures a direct peer.
  • "a message sent directly to a server that is off is lost" contradicts a2a/index.md ("never a silent loss"). The code retries a few times, then raises a delivery alarm. Say it fails after a few quick retries, matching the user guide.
  • AC13 says a revoked session shows on the issuer's record. That's only true in the CLI, and it becomes moot once peer sessions are only revoked through Remove (see the peering-lifecycle issue). Reword it to match.

docs/j5/runbooks/peering.md

"every cancelled message's sender gets a not-delivered notice" misses three cases:

  • rows already handed out to a poller get "may not have been delivered";
  • asks get the Exchange drop notice instead;
  • a sender already told about a refusal gets nothing more.

CodeRabbit flagged this too.

docs/j5/product/a2a/agent-tools.md

"the message is told" should say "the sender is told".

docs/user/j5-peering.md

  • Name refresh. "the new name reaches the other server the next time they talk" is only true when one server polls the other. Direct peers refresh the name on hello or when one reads the other's address book. Say "the next time it polls, or the other server reads its address book".
  • Discoverability. Link the guide from docs/README.md, next to the other J5 user guides (playbooks.md, personas.md).

Activity

  1. added a commit that references this issue on Oct 8, 2026
    2e196db
  2. added a commit that references this issue on Oct 8, 2026
    5aaaab0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions