diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 44c07344..669c0cfb 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -6,15 +6,15 @@ These instructions are project-wide defaults for this repository. Keep changes f
 
 ## Architecture
 
-- `lava/`: core public interfaces and contracts (`Middleware`, routers, request/response abstractions).
+- `pkg/lava/`: core public interfaces and contracts (`Middleware`, routers, request/response abstractions). Root `lava/` is a deprecated type-alias shim.
 - `core/`: runtime capabilities (supervisor, scheduler, tunnel, logging/metrics/tracing, debug, DI builder).
-- `servers/`: service hosts (`https` on Fiber, `grpcs` with gateway integration).
+- `servers/`: service hosts (`gatewayserver` multi-protocol gateway, `https` on Fiber, `zrpcs` on NATS).
 - `clients/`: outbound client implementations (`grpcc`, `resty`).
 - `pkg/`: reusable public utilities/components (including gateway and helpers).
 - `internal/`: repository-internal implementation details/examples; avoid exposing as public API.
 
 Place new code by responsibility:
-- Cross-protocol abstractions -> `lava/`
+- Cross-protocol abstractions -> `pkg/lava/`（根 `lava/` 仅为 deprecated shim）
 - Runtime framework capability -> `core/<module>/`
 - HTTP/gRPC serving behavior -> `servers/`
 - Reusable public helper/component -> `pkg/`
@@ -65,5 +65,5 @@ CI reference is `.github/workflows/lint-test.yml` (lint + gotestsum-based tests)
 - Service lifecycle and management: `core/supervisor/`
 - DI registration patterns: `core/lavabuilder/`
 - HTTP server composition: `servers/https/server.go`
-- gRPC + gateway composition: `servers/gatewayserver/server.go`（`servers/grpcs` 为废弃别名）
+- gRPC + gateway composition: `servers/gatewayserver/server.go`
 - Gateway behavior and routing: `pkg/gateway/`
diff --git a/deploy/traefik/README.md b/deploy/traefik/README.md
index 5a1bb42b..cd15fd9f 100644
--- a/deploy/traefik/README.md
+++ b/deploy/traefik/README.md
@@ -18,9 +18,9 @@ lava gateway 是多协议网关，三类入站协议在 L7 上性质不同，**
 
 | 协议 | 默认端口 | 配置项 | 回源 scheme | 备注 |
 | --- | --- | --- | --- | --- |
-| HTTP/REST + gRPC-Web | 8080 | `grpc_server.http_port` | `http` | REST 挂在 `/api` 前缀；gRPC-Web 是普通 POST |
-| WebSocket | 8081 | `grpc_server.websocket_port` | `http` | HTTP/1.1 `Upgrade`，Traefik 自动透传 |
-| 原生 gRPC | 50051 | `grpc_server.grpc_port` | **`h2c`** | 明文 HTTP/2，必须用 h2c |
+| HTTP/REST + gRPC-Web | 8080 | `gateway_server.http` / `running.HttpPort` | `http` | REST 挂在 `/api` 前缀；gRPC-Web 是普通 POST |
+| WebSocket | 8081 | `gateway_server.websocket_port` | `http` | HTTP/1.1 `Upgrade`，Traefik 自动透传 |
+| 原生 gRPC | 50051 | `gateway_server.grpc` / `running.GrpcPort` | **`h2c`** | 明文 HTTP/2，必须用 h2c |
 
 > 关键点：原生 gRPC 回源**必须**用 `h2c://`（明文 HTTP/2）。若写成 `http://`，
 > Traefik 会按 HTTP/1.1 回源，gRPC 直接失败。
@@ -82,6 +82,6 @@ gRPC streaming 与 WebSocket 是长连接，`traefik.yml` 中 `idleConnTimeout`
 
 - 关闭或鉴权保护 Traefik dashboard（`api.dashboard`）。
 - `acme.json` 含真实证书后勿提交到 git（本地/服务器持久化即可）。
-- WebSocket 务必在 `grpc_server.websocket_origin_patterns` 配置允许的来源，
+- WebSocket 务必在 `gateway_server.websocket_origin_patterns` 配置允许的来源，
   不要依赖开发期默认的「跳过校验」。
 - `acme.json` 权限 `600`，并纳入持久化卷。
diff --git a/deploy/traefik/docker-compose.yml b/deploy/traefik/docker-compose.yml
index f46746f3..8139b905 100644
--- a/deploy/traefik/docker-compose.yml
+++ b/deploy/traefik/docker-compose.yml
@@ -27,9 +27,9 @@ services:
 
   # 你的 lava gateway 服务。这里用占位镜像示意端口映射关系，
   # 实际换成自己构建的镜像，并确保监听以下端口：
-  #   8080  = grpc_server.http_port（REST 挂在 /api 前缀 + gRPC-Web）
-  #   8081  = grpc_server.websocket_port
-  #   50051 = grpc_server.grpc_port（原生 gRPC，明文 h2c）
+  #   8080  = gateway_server.http（REST 挂在 /api 前缀 + gRPC-Web）
+  #   8081  = gateway_server.websocket_port
+  #   50051 = gateway_server.grpc（原生 gRPC，明文 h2c）
   gateway:
     image: your-org/lava-gateway:latest
     expose:
diff --git a/docs/architecture-v2.md b/docs/architecture-v2.md
index bcbf9d79..a06da816 100644
--- a/docs/architecture-v2.md
+++ b/docs/architecture-v2.md
@@ -18,7 +18,6 @@ flowchart TD
 
     subgraph Service[服务宿主 servers/*]
         GWS[servers/gatewayserver]
-        GRPCS[servers/grpcs 废弃别名]
         HTTPS[servers/https]
         ZRPCS[servers/zrpcs]
     end
@@ -95,9 +94,9 @@ flowchart TD
 ```
 
 - **命令**：`lava grpc` → `gatewayserver.New`（`cmds/grpcservercmd`）
-- **配置**：`gateway_server`（推荐）或 legacy `grpc_server`
+- **配置**：`gateway_server`（`gatewayserver.LoadConfig`）
 - **TLS**：框架内不处理；Traefik 边缘终止，回源 `http` / `h2c`
-- **调试**：`/debug/vars` 暴露 `gateway-server-info`（兼容 `grpc-server-info`）
+- **调试**：`/debug/vars` 暴露 `gateway-server-info`（兼容旧名 `grpc-server-info`）
 
 ### 通路 B：NATS 微服务（zrpc）
 
@@ -112,7 +111,7 @@ zrpc Client → NATS (subject + queue) → zrpc.Server → 业务 Handler
 | `servers/zrpcs` | 纯 NATS 微服务宿主，代码生成 `Register...ZrpcRoutes` |
 | `pkg/zrpcbridge.RegisterMux` | 把已在 `gateway.Mux` 注册的 handler **额外**暴露到 NATS |
 
-> 重构后：zrpc **不是** gateway 前端，而是可选桥接。`grpc_server.zrpc_url` 已移除。
+> 重构后：zrpc **不是** gateway 前端，而是可选桥接。`gateway_server.zrpc_url`（旧 `grpc_server.zrpc_url`）已移除。
 
 ### 通路 C：反向隧道（tunnel）
 
@@ -232,8 +231,6 @@ sequenceDiagram
     Handler-->>Client: 响应
 ```
 
-`servers/grpcs` 是 **废弃别名**，内部调用 `gatewayserver.NewWithName(..., "grpc-server")`。
-
 ### 5.2 zrpc（`servers/zrpcs` + `clients/zrpcc`）
 
 ```mermaid
@@ -341,7 +338,6 @@ lava/
 ├── cmds/                 # CLI 命令
 ├── servers/
 │   ├── gatewayserver/    # ★ 对外多协议网关
-│   ├── grpcs/            # 废弃别名
 │   ├── https/            # 纯 HTTP
 │   └── zrpcs/            # NATS 微服务
 ├── pkg/
@@ -362,9 +358,9 @@ lava/
 
 | 之前 | 现在 |
 | --- | --- |
-| `servers/grpcs` 同时承载网关与 zrpc | `gatewayserver` 纯网关；zrpc 外置 |
+| `servers/grpcs` 包（废弃别名） | `gatewayserver` 纯网关；v3 删除 `grpcs` |
 | `Mux.RegisterZrpc` | `pkg/zrpcbridge.RegisterMux`（DI 显式调用） |
-| `grpc_server.zrpc_url` 配置 | 已移除 |
+| `gateway_server.zrpc_url`（旧 `grpc_server.zrpc_url`） | 已移除 |
 | 原生 gRPC 空占位 `stream.grpc.go` | 已删除（直接用 `grpc.ServerStream`） |
 
 设计原则：
diff --git a/docs/copilot-skills.md b/docs/copilot-skills.md
index c2284bb7..c7218a13 100644
--- a/docs/copilot-skills.md
+++ b/docs/copilot-skills.md
@@ -216,7 +216,7 @@ func NewUserConfig() *UserConfig {
 // Create a gRPC service for user management
 // Includes:
 //   - UserService with GetUser and ListUsers methods
-//   - Service registration with grpcs server
+//   - Service registration with gatewayserver
 func NewUserGrpcService() lava.GrpcRouter {
     // Copilot 会生成完整的 gRPC 服务实现
 }
diff --git a/docs/design-v2.md b/docs/design-v2.md
index 4c572fad..2ed5e02d 100644
--- a/docs/design-v2.md
+++ b/docs/design-v2.md
@@ -11,12 +11,12 @@ Lava 在设计上聚焦三件事：
 当前在传输层上，Lava 已覆盖：
 
 - HTTP（`servers/https` / `clients/resty`）
-- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`；`servers/grpcs` 为废弃别名）
+- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`）
 - zrpc（`servers/zrpcs` / `clients/zrpcc`，protobuf unary over NATS）
 
 ## 2. 核心抽象
 
-### 2.1 中间件抽象（`lava/middleware.go`）
+### 2.1 中间件抽象（`pkg/lava/middleware.go`）
 
 ```go
 type HandlerFunc func(ctx context.Context, req Request) (Response, error)
@@ -29,7 +29,7 @@ type Middleware interface {
 
 这是一种“函数包裹函数”的链式模型，支持同一语义在 HTTP/gRPC/Client 场景复用。
 
-### 2.2 路由抽象（`lava/router.go`）
+### 2.2 路由抽象（`pkg/lava/router.go`）
 
 ```go
 type HttpRouter interface {
@@ -60,7 +60,7 @@ type Service interface {
 
 `supervisor.Manager` 基于该接口实现生命周期托管、重启策略和状态观测。
 
-### 2.4 统一请求抽象（`lava/request.go` / `lava/response.go`）
+### 2.4 统一请求抽象（`pkg/lava/request.go` / `pkg/lava/response.go`）
 
 当前 `lava.RequestKind` 已覆盖：
 
@@ -165,5 +165,5 @@ stateDiagram-v2
 ## 7. 文档与实现的一致性建议
 
 1. 命令文档以 `main.go` 作为根入口真值。
-2. 接口文档优先引用 `lava/*.go` 与 `core/supervisor/types.go`。
+2. 接口文档优先引用 `pkg/lava/*.go` 与 `core/supervisor/types.go`。
 3. 流程图更新时，必须同步标注对应实现路径。
diff --git a/docs/legacy-removal.md b/docs/legacy-removal.md
index c680ce25..baac9855 100644
--- a/docs/legacy-removal.md
+++ b/docs/legacy-removal.md
@@ -66,6 +66,6 @@ gateway_server:
 - [x] HTTP 中间件链统一到 `servers/serverhttp.HandlerMiddleware`（#107）
 - [x] `internal/configs/components/grpc_server.yaml` 已移除，统一 `gateway_server.yaml`
 - [x] `lavabuilder grpc` 通过 `gatewayserver.LoadConfig` 加载 YAML 并对 `grpc_server` 打废弃警告
-- [ ] 架构文档仅描述 `gateway_server`
+- [x] 架构文档仅描述 `gateway_server`（主文档统一 `gatewayserver`；legacy 见本文档）
 - [ ] `task test` 不依赖 legacy 路径（或单独 `task test:legacy`）
 - [ ] v3 里程碑前开 PR 删除 `grpcs` 包
diff --git a/docs/modules/pkg.md b/docs/modules/pkg.md
index 49901c5b..e6642a2b 100644
--- a/docs/modules/pkg.md
+++ b/docs/modules/pkg.md
@@ -70,4 +70,4 @@ zrpc Client → NATS → zrpc.Server → zrpcbridge → gateway.Mux → handler
 | `servers/zrpcs` | 纯 NATS 微服务宿主 |
 | `pkg/zrpcbridge` | 可选：把 Mux handler 额外暴露到 NATS |
 
-用法见 `pkg/zrpcbridge/README.md`；此前 `Mux.RegisterZrpc` 与 `grpc_server.zrpc_url` 已移除。
+用法见 `pkg/zrpcbridge/README.md`；此前 `Mux.RegisterZrpc` 与 `gateway_server.zrpc_url`（旧 `grpc_server.zrpc_url`）已移除。
diff --git a/docs/modules/servers.md b/docs/modules/servers.md
index cdc6e465..a766392d 100644
--- a/docs/modules/servers.md
+++ b/docs/modules/servers.md
@@ -7,7 +7,6 @@
 | 模块 | 说明 | 关键入口 |
 | --- | --- | --- |
 | `servers/gatewayserver` | 对外 Gateway：HTTP/REST、gRPC-Web、WebSocket、原生 gRPC | `gatewayserver.New` |
-| `servers/grpcs` | **已废弃别名**，等同 `gatewayserver`（supervisor 名仍为 `grpc-server`） | `grpcs.New` |
 | `servers/https` | Fiber HTTP 服务，默认接入 debug 与基础中间件 | `https.New` |
 | `servers/zrpcs` | zrpc 服务宿主，基于 NATS 托管 protobuf unary/streaming RPC | `zrpcs.New` |
 
@@ -19,28 +18,30 @@
 
 | 协议 | 默认端口 | 配置项 | 实现 |
 | --- | --- | --- | --- |
-| HTTP/REST + gRPC-Web | 8080 | `grpc_server.http_port` / `running.HttpPort` | Fiber，`/api` 前缀 |
-| WebSocket | 8081（可选） | `websocket_port` | `net/http` |
-| 原生 gRPC | 50051 | `grpc_server.grpc_port` / `running.GrpcPort` | `grpc.Server` 或 passthrough |
+| HTTP/REST + gRPC-Web | 8080 | `gateway_server.http` / `running.HttpPort` | Fiber，`/api` 前缀 |
+| WebSocket | 8081（可选） | `gateway_server.websocket_port` | `net/http` |
+| 原生 gRPC | 50051 | `gateway_server.grpc` / `running.GrpcPort` | `grpc.Server` 或 passthrough |
 
 ### 装配流程
 
 1. 收集 `GrpcRouter` / `GrpcHttpRouter` → 注册到 `gateway.Mux`
 2. Fiber 挂 `/api` → `mux.Handler`
-3. 可选 `WebSocketPort` → 独立 `http.Server`
-4. gRPC：legacy 双注册，或 `grpc_passthrough` 仅在 Mux 注册
+3. 可选 `websocket_port` → 独立 `http.Server`
+4. gRPC：默认 `grpc_passthrough: true`（仅在 Mux 注册）；`false` 为 legacy 双注册
 5. 全局中间件：serviceinfo / metric / accesslog / recovery
 6. `vars.Register` 路由信息（`gateway-server-info`，兼容 `grpc-server-info`）
 
 ### 配置
 
-YAML 键：`gateway_server`（推荐）或 legacy `grpc_server`。
+YAML 键：**`gateway_server`**（见 `internal/configs/components/gateway_server.yaml`）。
+
+旧键 `grpc_server` 仍可解析，启动时会打废弃警告；详见 `docs/legacy-removal.md`。
 
 ```yaml
 gateway_server:
   enable_print_router: true
+  grpc_passthrough: true
   websocket_port: 8081
-  grpc_passthrough: false
   http: {}
   grpc: {}
 ```
@@ -52,12 +53,7 @@ gateway_server:
 
 ### 命令入口
 
-`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New`
-
-## `servers/grpcs`（废弃）
-
-类型别名 + `New()` 包装，supervisor 服务名仍为 `grpc-server`，便于老项目兼容。
-新代码请使用 `gatewayserver.New`。
+`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New` + `gatewayserver.LoadConfig`
 
 ## `servers/https` 要点
 
@@ -113,3 +109,13 @@ flowchart LR
     Bridge[pkg/zrpcbridge] -.->|可选| Mux
     Bridge -.-> NATS
 ```
+
+## Legacy（v3 移除）
+
+| 项 | 替代 |
+| --- | --- |
+| `servers/grpcs` 包 | `servers/gatewayserver` |
+| YAML 键 `grpc_server` | `gateway_server` |
+| `grpc_passthrough: false` | 默认 `true` |
+
+详见 `docs/legacy-removal.md`。
diff --git a/pkg/gateway/docs/grpcnative.md b/pkg/gateway/docs/grpcnative.md
index 336cc869..b989d93d 100644
--- a/pkg/gateway/docs/grpcnative.md
+++ b/pkg/gateway/docs/grpcnative.md
@@ -32,17 +32,17 @@ grpcServer := grpc.NewServer(grpc.UnknownServiceHandler(handler))
 
 **注意**：启用透传后，不要再对同一个 `grpc.Server` 调用 `RegisterService`，否则会与 `UnknownServiceHandler` 冲突。
 
-### grpc-server 配置
+### gateway_server 配置
 
 ```yaml
-grpc_server:
+gateway_server:
   grpc_passthrough: true
   websocket_port: 8081
 ```
 
 开启后，`servers/gatewayserver` 仅在 `Mux` 上注册服务，gRPC 端口上的原生客户端与 HTTP/WS 前端共享同一套 handler。
 
-> **默认值**：`grpc_passthrough` 默认为 `false`，保持与现有部署兼容（服务同时注册在 Mux 与外层 `grpc.Server`）。新部署若希望「RegisterService 一次、多协议复用」，建议显式设为 `true`。
+> **默认值**：`grpc_passthrough` 默认为 `true`（handler 仅在 Mux 注册）。若需 legacy 双注册（同时挂在外层 `grpc.Server`），显式设为 `false`。
 
 ## 与其他前端的关系
 
diff --git a/pkg/gateway/docs/grpcnats.md b/pkg/gateway/docs/grpcnats.md
index c10241b8..99280f7a 100644
--- a/pkg/gateway/docs/grpcnats.md
+++ b/pkg/gateway/docs/grpcnats.md
@@ -13,4 +13,4 @@ import "github.com/pubgo/lava/v2/pkg/zrpcbridge"
 _ = zrpcbridge.RegisterMux(zrpcSrv, mux, zrpcbridge.Config{Queue: "my-service"})
 ```
 
-原先 `grpc_server.zrpc_url` 配置项已移除；请在应用 DI 中显式连接 NATS 并调用 `RegisterMux`。
+原先 `gateway_server.zrpc_url`（旧 `grpc_server.zrpc_url`）配置项已移除；请在应用 DI 中显式连接 NATS 并调用 `RegisterMux`。
diff --git a/pkg/gateway/docs/websocket.md b/pkg/gateway/docs/websocket.md
index f52344d5..819c6cfc 100644
--- a/pkg/gateway/docs/websocket.md
+++ b/pkg/gateway/docs/websocket.md
@@ -130,12 +130,12 @@ HTTP 握手请求头会被转换为 gRPC 的 incoming metadata，供服务端通
 - 通过 REST 注解路径访问时，`streamWS` 会带上匹配到的 `MatchOperation`，因此 `body:"field"` / `response_body` 字段映射对 WebSocket 同样生效；直查 gRPC 全方法名时整条消息即请求/响应体。
 - 结束时通过 WebSocket Close 帧回传结构化 gRPC 状态：close code 由 gRPC code 映射，reason 为 JSON `{"grpcStatus":N,"grpcMessage":"..."}`，客户端可解析 `event.reason` 获取状态。
 
-## 在 grpc-server 中启用
+## 在 gateway 中启用
 
-在 `grpc_server` 配置里设置 `websocket_port` 即可在独立端口启动 WebSocket 前端（与 Fiber HTTP 端口分离）：
+在 `gateway_server` 配置里设置 `websocket_port` 即可在独立端口启动 WebSocket 前端（与 Fiber HTTP 端口分离）：
 
 ```yaml
-grpc_server:
+gateway_server:
   websocket_port: 8081
   # 生产环境建议配置 Origin 白名单
   websocket_origin_patterns:
@@ -168,7 +168,7 @@ mux.WebSocketHandler(gateway.WSOptionsFromConfig(gateway.WSConfig{
 生产环境务必配置 `websocket_origin_patterns`，例如：
 
 ```yaml
-grpc_server:
+gateway_server:
   websocket_port: 8081
   websocket_origin_patterns:
     - "example.com"