From 8bc59eceb75e25a1ea9324ecdf9ee03a4d03d55a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 21:17:54 +0100
Subject: [PATCH] docs: refresh gateway feature registry mirrors

---
 docs/concepts/architecture.md |  2 ++
 docs/concepts/typebox.md      | 13 +++++++++----
 docs/gateway/index.md         |  2 ++
 docs/gateway/protocol.md      |  5 +++++
 4 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md
index 923df3c10e8..7c1c33d3a44 100644
--- a/docs/concepts/architecture.md
+++ b/docs/concepts/architecture.md
@@ -82,6 +82,8 @@ sequenceDiagram
 - After handshake:
   - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
   - Events: `{type:"event", event, payload, seq?, stateVersion?}`
+- `hello-ok.features.methods` / `events` are discovery metadata, not a
+  generated dump of every callable helper route.
 - Shared-secret auth uses `connect.params.auth.token` or
   `connect.params.auth.password`, depending on the configured gateway auth mode.
 - Identity-bearing modes such as Tailscale Serve
diff --git a/docs/concepts/typebox.md b/docs/concepts/typebox.md
index 909b09cdc51..410746a661d 100644
--- a/docs/concepts/typebox.md
+++ b/docs/concepts/typebox.md
@@ -51,14 +51,14 @@ Common methods + events:
 | Nodes     | `node.list`, `node.invoke`, `node.pair.*`                 | Gateway WS + node actions          |
 | Events    | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown` | server push                        |
 
-Authoritative advertised method/event inventory lives in
+Authoritative advertised **discovery** inventory lives in
 `src/gateway/server-methods-list.ts` (`listGatewayMethods`, `GATEWAY_EVENTS`).
 
 ## Where the schemas live
 
 - Source: `src/gateway/protocol/schema.ts`
 - Runtime validators (AJV): `src/gateway/protocol/index.ts`
-- Advertised method/event registry: `src/gateway/server-methods-list.ts`
+- Advertised feature/discovery registry: `src/gateway/server-methods-list.ts`
 - Server handshake + method dispatch: `src/gateway/server.impl.ts`
 - Node client: `src/gateway/client.ts`
 - Generated JSON Schema: `dist/protocol.schema.json`
@@ -79,8 +79,13 @@ Authoritative advertised method/event inventory lives in
   accepts a `connect` request whose params match `ConnectParams`.
 - **Client side**: the JS client validates event and response frames before
   using them.
-- **Method surface**: the Gateway advertises the supported `methods` and
-  `events` in `hello-ok` from `listGatewayMethods()` and `GATEWAY_EVENTS`.
+- **Feature discovery**: the Gateway sends a conservative `features.methods`
+  and `features.events` list in `hello-ok` from `listGatewayMethods()` and
+  `GATEWAY_EVENTS`.
+- That discovery list is not a generated dump of every callable helper in
+  `coreGatewayHandlers`; some helper RPCs are implemented in
+  `src/gateway/server-methods/*.ts` without being enumerated in the advertised
+  feature list.
 
 ## Example frames
 
diff --git a/docs/gateway/index.md b/docs/gateway/index.md
index 82434ed1119..ca556ee4aa0 100644
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -305,6 +305,8 @@ Defaults include isolated state/config and base gateway port `19001`.
 
 - First client frame must be `connect`.
 - Gateway returns `hello-ok` snapshot (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
+- `hello-ok.features.methods` / `events` are a conservative discovery list, not
+  a generated dump of every callable helper route.
 - Requests: `req(method, params)` → `res(ok/payload|error)`.
 - Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`.
 
diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
index 9d2d07ad5f9..a1977f5e276 100644
--- a/docs/gateway/protocol.md
+++ b/docs/gateway/protocol.md
@@ -218,6 +218,11 @@ This page is not a generated full dump, but the public WS surface is broader
 than the handshake/auth examples above. These are the main method families the
 Gateway exposes today.
 
+`hello-ok.features.methods` is a conservative discovery list built from
+`src/gateway/server-methods-list.ts` plus loaded plugin/channel method exports.
+Treat it as feature discovery, not as a generated dump of every callable helper
+implemented in `src/gateway/server-methods/*.ts`.
+
 ### System and identity
 
 - `gateway.identity.get` returns the gateway device identity used by relay and