From d18492491f443ec27ddf908a19bcc2b4bf3a7dcf Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 3 Mar 2026 11:12:54 +0000
Subject: [PATCH] docs: remove undocumented AppMessage protocol

The `docs/concepts/wire-protocol.md` file documented an `0x50 AppMessage` protocol for end-to-end encrypted application-level messages. However, this message type is not defined in `src/protocol/messages.zig`. Since the source code is the ground truth, this aspirational documentation has been removed to accurately reflect the implementation.

Co-authored-by: igorls <4753812+igorls@users.noreply.github.com>
---
 .jules/scribe.md               |  4 ++++
 docs/concepts/wire-protocol.md | 16 ----------------
 2 files changed, 4 insertions(+), 16 deletions(-)

diff --git a/.jules/scribe.md b/.jules/scribe.md
index 48b090c..441acb0 100644
--- a/.jules/scribe.md
+++ b/.jules/scribe.md
@@ -12,3 +12,7 @@
 **Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`.
 **Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated.
 **Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
+## 2024-03-22 - AppMessage Documentation Gap
+**Gap:** The documentation (docs/concepts/wire-protocol.md) described an AppMessage protocol for end-to-end encrypted application-level messages, while the implementation (src/protocol/messages.zig) does not define it.
+**Learning:** Documentation drifted because the initial design likely included an AppMessage protocol which was either not implemented or removed, but docs were not updated.
+**Prevention:** Regularly audit messages.zig against documentation to ensure all documented message types are actually defined.
diff --git a/docs/concepts/wire-protocol.md b/docs/concepts/wire-protocol.md
index 2f7aaec..28009d1 100644
--- a/docs/concepts/wire-protocol.md
+++ b/docs/concepts/wire-protocol.md
@@ -33,7 +33,6 @@ SWIM messages use a **1-byte type tag**:
 | `0x41` | OrgAliasAnnounce    | Org Trust | Gossip          |
 | `0x42` | OrgCertRevoke       | Org Trust | Gossip          |
 | `0x43` | OrgTrustVouch       | Org Trust | Gossip          |
-| `0x50` | AppMessage          | App       | A → B (relayed) |
 
 ## Ping
 
@@ -150,21 +149,6 @@ Propagated via gossip. Org admin vouches for an external standalone node — all
 
 Total: **137 bytes**. Signature covers `vouched_pubkey ‖ lamport`. Revocable via OrgCertRevoke.
 
-## AppMessage
-
-End-to-end encrypted application-level message, relayed through the mesh.
-
-```
-[0x50][32B dest_pubkey][32B sender_pubkey][12B nonce][N ciphertext][16B tag]
-```
-
-Minimum size: **93 bytes** (empty payload). Maximum payload: 1024 bytes.
-
-- **Key derivation**: X25519(sender_private, dest_wg_pubkey) → HKDF("meshguard-app-v1") → symmetric key
-- **AD**: sender's Ed25519 public key
-- **Routing**: intermediate peers forward the entire packet as-is (encrypted, opaque) to the destination by pubkey lookup
-- **Delivery**: when `dest_pubkey` matches our own, the message is decrypted and delivered via callback
-
 ## Endpoint Encoding
 
 All IPv4 endpoints are encoded as: