Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/gateway/operator-scopes.md

@@ -0,0 +1,119 @@
+---
+summary: "Operator roles, scopes, and approval-time checks for Gateway clients"
+read_when:
+  - Debugging missing operator scope errors
+  - Reviewing device or node pairing approvals
+  - Adding or classifying Gateway RPC methods
+title: "Operator scopes"
+---
+
+Operator scopes gate what a Gateway client can do after it authenticates.
+They are a control-plane guardrail inside one trusted Gateway operator domain,
+not hostile multi-tenant isolation. For strong separation between people,
+teams, or machines, run separate Gateways under separate OS users or hosts.
+
+Related: [Security](/gateway/security), [Gateway protocol](/gateway/protocol),
+[Gateway pairing](/gateway/pairing), [Devices CLI](/cli/devices).
+
+## Roles
+
+Every Gateway WebSocket client connects with one role:
+
+- `operator`: control-plane clients such as CLI, Control UI, automation, and
+  trusted helper processes.
+- `node`: capability hosts (macOS, iOS, Android, headless) that expose
+  commands through `node.invoke`.
+
+Operator RPC methods require the `operator` role; node-originated methods
+require the `node` role.
+
+## Scope levels
+
+| Scope                   | Meaning                                                                                                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `operator.read`         | Read-only status, lists, catalog, logs, session reads, and other non-mutating calls.                                                                          |
+| `operator.write`        | Mutating operator actions: sending messages, invoking tools, updating talk/voice settings, node command relay. Also satisfies `operator.read`.                |
+| `operator.admin`        | Administrative access. Satisfies every `operator.*` scope. Required for config mutation, updates, native hooks, reserved namespaces, and high-risk approvals. |
+| `operator.pairing`      | Device and node pairing management: list, approve, reject, remove, rotate, revoke.                                                                            |
+| `operator.approvals`    | Exec and plugin approval APIs.                                                                                                                                |
+| `operator.talk.secrets` | Reading Talk configuration with secrets included.                                                                                                             |
+
+Unknown future `operator.*` scopes require an exact match unless the caller
+already holds `operator.admin`.
+
+## Method scope is only the first gate
+
+Each Gateway RPC has a least-privilege method scope that decides whether a
+request reaches its handler. Some handlers then apply stricter checks based on
+the concrete thing being approved or mutated:
+
+- `device.pair.approve` is reachable with `operator.pairing`, but approving an
+  operator device can only mint or preserve scopes the caller already holds.
+- `node.pair.approve` is reachable with `operator.pairing`, then derives extra
+  approval scopes from the pending node's declared command list.
+- `chat.send` is a write-scoped method, but the `/config set` and
+  `/config unset` chat commands require `operator.admin` on top of that,
+  regardless of the caller's chat-send scope.
+
+This lets lower-scope operators perform low-risk pairing actions without
+making all pairing approval admin-only.
+
+## Device pairing approvals
+
+Device pairing records are the durable source of approved roles and scopes.
+An already-paired device does not get broader access silently: a reconnect
+that asks for a broader role or broader scopes creates a new pending upgrade
+request.
+
+Approving a device request:
+
+- A request with no operator role does not need operator scope approval.
+- A request for a non-operator device role (for example `node`) requires
+  `operator.admin`, even though `device.pair.approve` itself only needs
+  `operator.pairing`.
+- A request for `operator.read`, `operator.write`, `operator.approvals`,
+  `operator.pairing`, or `operator.talk.secrets` requires the caller to already
+  hold that scope, or `operator.admin`.
+- A request for `operator.admin` requires `operator.admin`.
+- A repair request with no explicit scopes can inherit the existing operator
+  token's scopes; if that token is admin-scoped, approval still requires
+  `operator.admin`.
+
+Non-admin shared-secret and trusted-proxy sessions can only approve
+operator-device requests within their own declared operator scopes; approving
+non-operator roles is admin-only even when those sessions can otherwise use
+`operator.pairing`.
+
+For paired-device token sessions, management is self-scoped unless the caller
+has `operator.admin`: a non-admin caller sees only its own pairing entries, and
+can approve, reject, rotate, revoke, or remove only its own device entry.
+
+## Node pairing approvals
+
+Legacy `node.pair.*` methods use a separate Gateway-owned node pairing store.
+WS nodes use device pairing (`role: node`) instead, but the same approval
+vocabulary applies. See [Gateway pairing](/gateway/pairing) for how the two
+stores relate.
+
+`node.pair.approve` derives extra required scopes from the pending request's
+command list:
+
+| Declared commands                                     | Required scopes                       |
+| ----------------------------------------------------- | ------------------------------------- |
+| none                                                  | `operator.pairing`                    |
+| non-exec node commands                                | `operator.pairing` + `operator.write` |
+| `system.run`, `system.run.prepare`, or `system.which` | `operator.pairing` + `operator.admin` |
+
+Node pairing establishes identity and trust; it does not replace a node's own
+`system.run` exec approval policy.
+
+## Shared-secret auth
+
+Shared gateway token/password auth is treated as trusted operator access for
+that Gateway. OpenAI-compatible HTTP surfaces, `/tools/invoke`, and HTTP
+session-history endpoints restore the full default operator scope set for
+shared-secret bearer auth, even if a caller sends narrower declared scopes.
+
+Identity-bearing modes, such as trusted proxy auth or private-ingress `none`,
+can still honor explicit declared scopes. Use separate Gateways for real trust
+boundary separation.