docs: record lazy-browse stays wire-only; align error mapping

docs/DesignDecisions.md

@@ -362,6 +362,19 @@ Dashboard access should require API-key-backed dashboard authentication with
 is enabled by default through `Dashboard:AllowAnonymousLocalhost`; the bypass is
 limited to loopback requests.
 
+## Lazy Browse Is Wire-Only
+
+Decision: the gateway continues to pull the full Galaxy hierarchy on each
+deploy. `BrowseChildren` and the lazy dashboard render only avoid sending and
+DOM-materializing the full tree — they do not push laziness into SQL or cache
+loading.
+
+Rationale: snapshot persistence and the dashboard summary both depend on a
+fully-materialized cache. Lazy SQL would increase per-click latency on a
+deployment-heavy box, multiply per-session SQL connections, and complicate the
+cold-start path. Wire-side laziness solves the actual pain (oversized gRPC
+replies and a heavy DOM) without disturbing the materialization model.
+
 ## Later Revisit Items
 
 These are explicit post-v1 revisit items, not open blockers:

docs/plans/2026-05-28-lazy-browse-design.md

@@ -102,12 +102,14 @@ message BrowseChildrenReply {
 | Condition | Status |
 |---|---|
 | Unknown `parent_gobject_id` / `parent_tag_name` / `parent_contained_path` | `NotFound` |
-| Stale `page_token` (cache deployed forward) | `FailedPrecondition`; current `cache_sequence` in trailers |
+| Stale `page_token` (cache deployed forward) | `InvalidArgument`; current `cache_sequence` in trailers |
 | Filter set differs between pages of the same token | `InvalidArgument` |
 | First load not complete within 5s | `Unavailable` |
 | API key missing `metadata:read` scope | `PermissionDenied` |
 | No API key | `Unauthenticated` |
 
+Stale and filter-changed page tokens both surface as `InvalidArgument` — same contract as `DiscoverHierarchy`, since `BrowseChildren` reuses the same token encoding (`sequence:filter-signature:offset`).
+
 `browse_subtrees` API-key constraints intersect with the request as today.
 
 ## Server projection