Skip to content

docs/blog: accuracy fixes + flagged inconsistencies#127

Open
pstayets wants to merge 2 commits into
pilot-protocol:mainfrom
pstayets:docs-accuracy-fixes
Open

docs/blog: accuracy fixes + flagged inconsistencies#127
pstayets wants to merge 2 commits into
pilot-protocol:mainfrom
pstayets:docs-accuracy-fixes

Conversation

@pstayets

Copy link
Copy Markdown
Contributor

Documentation/blog accuracy pass. Two classes of change: (1) small, confident corrections applied in this PR; (2) issues where the correct fix is a content/product decision — these are not changed, only outlined below with file:line so a maintainer can decide. Whitepaper (pilot-protocol/docs) was intentionally left untouched; where the docs and whitepaper disagree, the docs are treated as authoritative.

Applied in this PR

  1. Pub/sub "no single point of failure" was stated absolutely — reads as a network-wide guarantee. Scoped it to event delivery and noted that peer discovery and trust still resolve through the central registry. (src/pages/docs/pubsub.astro, src/pages/plain/docs/pubsub.astro). The per-node-broker statement itself is accurate and was left as-is.
  2. Cipher key size dropped in several authoritative statements — standardized AES-GCMAES-256-GCM in the spec/comparison tables and the two protocol blog posts that had dropped it (docs/comparison, plain/docs/comparison, blog/how-pilot-protocol-works, blog/overlay-network-ai-agents). The 256 is a security-relevant claim and is used everywhere else.

Flagged — NOT changed, correct fix is a judgment call

A. Benchmark numbers contradict our own whitepapersrc/pages/blog/benchmarking-http-vs-udp-overlay.astro:19
The post states "85ms RTT between US-East and EU-West (measured with ICMP ping, averaged over 1000 samples)" and Pilot sustained throughput of 50 Mbps. The whitepaper measures the same corridor at ~193 ms (raw samples 193.289 / 193.317 / 193.405 ms) and 2.1 MB/s round-trip (~16.8 Mbps). The entire latency table and the "11× faster connection setup" figure are derived from the 85 ms baseline. These cannot both be real measurements. I did not edit the numbers because I can't determine which is correct without re-running the benchmark, and the whitepaper is out of scope. Needs: re-measured figures, or a note on the differing test setup.

B. "Emergent / without human intervention" framing vs. the skill-injection mechanismsrc/pages/docs/research.astro:61
The abstract says the trust network formed from "OpenClaw instances that independently discovered, installed, and joined the Pilot Protocol without human intervention" and "No human designed these social structures." But pilot-protocol/skillinject rewrites each agent tool's config every 15 min specifically to make an agent "reach for Pilot first," and the injected pilotctl skill instructs every agent to "Initiate trust proactively" and to end its first session with "at least one trusted relationship." The trust edges the paper measures are induced, at least in part, by injected instructions. Needs: disclose the injection/onboarding mechanism in the methodology, or soften "without human intervention" / "no human designed."

C. Blog title vs. body/on-page-title mismatches

  • src/pages/blog/how-626-agents-autonomously-adopted-pilot.astro — title says "626 Agents" but the body only ever references "hundreds." Align the number.
  • src/pages/blog/multi-agent-system-networking-guide-ai-developers.astro — title promises an "86.7% failure fix"; the body documents the 86.7% failure problem (SWE-Bench/GAIA) and never quantifies a fix. Remove "fix" or substantiate it. (Also carries a "generated by BabyLoveGrowth" attribution.)
  • src/pages/blog/replace-message-broker-twelve-lines-go.astro — "12 Lines of Go" isn't matched by the code samples (7–8 logic lines for the toy case, 30–50+ for the real one).
  • src/pages/blog/preferential-attachment-ai-networks-trust-graph.astro — the blog index title ("Why a Few AI Agents Get 80% of the Work (And How to Stop It)") differs from the on-page title ("Preferential Attachment in AI Agent Trust Graphs"). Pick one per URL.

D. Remaining AES-GCM (no key size) in softer prose — left unchanged for a focused diff, optional follow-up: blog/encrypted-data-exchange-for-decentralized-ai-systems.astro:158,289, blog/nat-traversal-ai-agents-deep-dive.astro:212. (The URL slug zero-dependency-encryption-x25519-aes-gcm is deliberately left — changing it would break the permalink.)

E. Minor naming consistency

  • Port 1002 is called "Event Stream" (docs/concepts, docs/services) and "Pub/Sub" (docs/messaging, docs/pubsub). Standardize.
  • Broadcast default port is documented as 1000 (docs/consent) while event delivery uses 1002 — confirm intended.

Reviewed and dismissed (not a bug)

The registry endpoint appearing as both 34.71.57.205:9000 and registry.pilotprotocol.network:443 is documented in docs/firewalls.astro:51 as the native-UDP-mode vs. compat/TLS-mode defaults. Not an inconsistency.

…ES-256-GCM

- pub/sub 'No single point of failure' scoped to event delivery; note that
  peer discovery and trust still resolve through the central registry
  (docs/pubsub, plain/docs/pubsub).
- Standardize the cipher name to AES-256-GCM in the authoritative spec/table
  statements that had dropped the key size (docs/comparison, plain/docs/comparison,
  blog/how-pilot-protocol-works, blog/overlay-network-ai-agents).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Jul 14 accuracy edits (AES-256-GCM, pub/sub SPOF qualification)
updated both the docs sources and their plain twins in the same commit,
but the twins' plain-source-sha256 stamps still pointed at the pre-edit
source hashes, so check-plain-coverage flagged them as stale. Bump the
two stamps to the current source hashes; twin content already matches.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant