Skip to content

docs: add the agent-mesh Field Guide - #76

Merged
hartsock merged 1 commit into
mainfrom
docs/field-guide
Aug 13, 2026
Merged

docs: add the agent-mesh Field Guide#76
hartsock merged 1 commit into
mainfrom
docs/field-guide

Conversation

@hartsock

@hartsock hartsock commented Aug 13, 2026

Copy link
Copy Markdown
Member

Summary

Adds docs/field_guide.md — a single operator-facing explainer with eight
mermaid diagrams (GitHub renders them natively):

  1. The four-layer crate stack and its consumers (newt-mesh, newt-web, amesh, amesh mcp)
  2. The trust chain: GitHub SSH key → UserKey → AgentKey → SignedEnvelope
  3. The wire sequence: mDNS hints → auto-team QUIC handshake → per-envelope verify
  4. The authority-provenance CID DAG (real, 0.6.4) vs the agent-mesh-store
    per-writer merkle logs (ADR only, no code) — explicitly badged TODAY vs PLANNED
  5. An honest comparison with tmux-message-bus (the durable-inbox gap)
  6. newt-agent's two live integrations: inference dispatch and docking (bus: handle_requests_with_context — expose the verified caller principal #75)
  7. wyvern-agent's status (no mesh code yet) and its two integration paths
  8. A zero-to-two-agents runbook

The known auto-team handshake residual is stated plainly rather than papered
over ("a filter, not a proof").

Test plan

  • Docs-only change; no code touched.
  • Full pre-push gate ran on push (fmt, clippy -D warnings, workspace tests, cov-ci ≥75%): green.
  • Mermaid blocks use plain flowchart/sequenceDiagram syntax that GitHub's renderer supports.

Risk: low (documentation only).

🤖 Generated with Claude Code


Note

Cursor Bugbot is generating a summary for commit 2ed6163. Configure here.

WHAT: A single-document explainer (docs/field_guide.md) with eight mermaid
diagrams covering: the four-layer crate stack, the GitHub-SSH -> UserKey ->
AgentKey trust chain, the wire protocol (signed envelopes, payload CIDs),
the authority-provenance CID DAG (0.6.4) vs the designed-but-unbuilt
agent-mesh-store merkle logs, an honest comparison with tmux-message-bus
(the durable-inbox gap), the two live newt-agent integrations (inference
dispatch + docking), wyvern-agent's status and integration paths, and a
zero-to-two-agents runbook.

WHY: There was no one place that explains what the mesh IS and how to get
real agents onto it today. Existing docs are decision records (deep, narrow);
the README is an overview. This is the operator-facing bridge between them,
and it is explicit about TODAY vs PLANNED so it cannot oversell the store.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@hartsock hartsock added the documentation Improvements or additions to documentation label Aug 13, 2026
@cursor

cursor Bot commented Aug 13, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_cdc45637-94c3-4b7a-9fa2-35415d178078)

@hartsock
hartsock merged commit 9de0a8a into main Aug 13, 2026
5 checks passed
@hartsock
hartsock deleted the docs/field-guide branch August 13, 2026 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant