NVIDIA
diff --git a/‎.agents/skills/tui-development/SKILL.md‎
Lines changed: 16 additions & 11 deletions b/‎.agents/skills/tui-development/SKILL.md‎
Lines changed: 16 additions & 11 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 6 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 7 additions & 1 deletion b/‎CONTRIBUTING.md‎
Lines changed: 7 additions & 1 deletion
diff --git a/‎architecture/gateway.md‎
Lines changed: 30 additions & 11 deletions b/‎architecture/gateway.md‎
Lines changed: 30 additions & 11 deletions
@@ -479,12 +479,14 @@ use openshell_core::proto::{
 
 ### Proto field gotchas
 
-- `DeleteSandboxRequest` uses the `name` field (not `id`):
+- `DeleteSandboxRequest` uses `name` for the primary sandbox and an explicit
+  workspace selector:
   ```rust
   let req = openshell_core::proto::DeleteSandboxRequest {
       name: sandbox_name,
       workspace_scope: Some(workspace_selector(workspace)),
       allow_missing: true,
+      ..Default::default()
   };
   ```
 - Delete responses carry `DeletionOutcome`: distinguish `Accepted` (cleanup
@@ -493,20 +495,22 @@ use openshell_core::proto::{
 - `WatchSandboxRequest` has extra fields beyond what you might need — always use `..Default::default()`:
   ```rust
   let req = openshell_core::proto::WatchSandboxRequest {
-      id: sandbox_id,
+      sandbox: sandbox_name,
       follow_status: false,
       follow_logs: true,
       follow_events: false,
       log_tail_lines: 0,
+      workspace_scope: Some(workspace_selector(workspace)),
       ..Default::default()
   };
   ```
 - `SandboxLogLine` proto fields: `sandbox_id`, `event_time` (`Option<prost_types::Timestamp>`), `level`, `target`, `message`, `source`, `fields` (`HashMap<String, String>`).
-- Workspace-scoped request fields use `workspace_scope: Option<WorkspaceSelector>`.
-  Select one workspace with `Some(workspace_selector(name))`. List requests that
-  explicitly support cross-workspace access also accept
+- Workspace-scoped requests use
+  `workspace_scope: Option<WorkspaceSelector>`. Select one workspace with
+  `Some(workspace_selector(name))`. Collection list requests that explicitly
+  support cross-workspace access also accept
   `Some(all_workspaces_selector())`; do not use that marker on other requests.
-- `GetSandboxLogsRequest` fields: `sandbox_id`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
+- `GetSandboxLogsRequest` fields: `sandbox`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
   `sources` (Vec<String>), `min_level` (String), `workspace_scope`.
 - `ListSandboxesRequest` fields: `page_size` (i32), `page_token` (String),
   `label_selector` (String), `workspace_scope`.
@@ -517,11 +521,12 @@ use openshell_core::proto::{
 - Paginated list responses return `next_page_token`. Continue with the same
   request parameters and that token until it is empty; changing filters or
   scope invalidates the token.
-- `UpdateConfigRequest` fields include `name` (String, sandbox name or empty for
-  global), `setting_key`, `setting_value`, `delete_setting` (bool), `global`
-  (bool), and `workspace_scope`. Sandbox-scoped updates require a named selector;
-  gateway-global updates must leave `workspace_scope` as `None`.
-- Most resource requests require an explicit named `workspace_scope`, including
+- `UpdateConfigRequest` fields include `sandbox` (String, canonical sandbox name),
+  `setting_key`, `setting_value`, `delete_setting` (bool), `global` (bool), and
+  `workspace_scope`. Sandbox-scoped updates require canonical `sandbox` and a
+  named selector; gateway-global updates leave `sandbox` empty and
+  `workspace_scope` as `None`.
+- Most workspace-scoped requests require an explicit named selector, including
   the `default` workspace. An omitted selector is not an implicit default.
 
 ### gRPC timeouts
 
@@ -83,6 +83,12 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer, doc writer) |
 | `architecture/` | Architecture docs | Design decisions and component documentation |
 
+## Public API Conventions
+
+Follow [proto/README.md](proto/README.md) for public protobuf API design. It is
+the canonical source for entity-reference naming, workspace selectors, field
+design, and schema evolution.
+
 ## Vouch System
 
 - First-time external contributors must be vouched before their PRs are accepted. The `vouch-check` workflow auto-closes PRs from unvouched users.
 
@@ -465,7 +465,7 @@ These are the primary `mise` tasks for day-to-day development:
 | `python/`       | Python SDK and bindings                       |
 | `sdk/go/`       | Go SDK (types, gRPC clients, converters)      |
 | `sdk/typescript/` | TypeScript SDK (Connect client and generated protobuf bindings) |
-| `proto/`        | Protocol buffer definitions                   |
+| `proto/`        | Protocol buffer definitions and [public API conventions](proto/README.md) |
 | `tasks/`        | `mise` task definitions and build scripts     |
 | `deploy/`       | Dockerfiles, Helm chart, Kubernetes manifests |
 | `docs/`         | Published Fern docs source, navigation, and content assets |
@@ -479,6 +479,12 @@ These are the primary `mise` tasks for day-to-day development:
 
 New features always start as GitHub issues using the feature request template. For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, maintainers may ask for an RFC from the issue and assign an RFC number there. RFCs live in `rfc/`. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines.
 
+## Public API conventions
+
+Follow [the protobuf API conventions](proto/README.md) when adding or changing
+gRPC contracts. The guide defines entity-reference naming, workspace selectors,
+field design, and schema-evolution rules.
+
 ## Documentation
 
 If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR and adjust `docs/index.yml` if navigation changes. For explicit navigation entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `docs/index.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides.
 
@@ -112,15 +112,34 @@ health, metrics, or tunnel routes. The plaintext service router also rejects
 browser requests whose Fetch Metadata, Origin, or Referer headers indicate a
 cross-origin or sibling-subdomain request.
 
-Public workspace-scoped RPCs carry a typed `WorkspaceSelector`. A request must
-select one non-empty workspace explicitly; `default` is an ordinary explicit
-name, not an omitted-value fallback. Sandbox, sandbox template, provider, and
-service list RPCs also accept an all-workspaces marker after Platform Admin
-authorization. Single-workspace handlers reject that marker. Platform-global
-policy operations require the selector to be absent, while workspace policy
-operations require it. The gateway authorizes the selected scope before
-performing resource lookup so malformed, unsupported, and unauthorized scopes
-have consistent behavior across resource types.
+The normative public contract rules live in the
+[protobuf API conventions](../proto/README.md). Public API fields follow one
+entity-reference convention. `name` identifies the
+primary resource targeted by an RPC. A role field such as `sandbox`, `provider`,
+`service`, or `workload_template` identifies an entity referenced while
+operating on another resource or relationship. Entity references never append
+`_name`; their string value is already the canonical name.
+
+Public workspace-scoped RPCs declare `workspace_scope` first and use the typed
+`WorkspaceSelector`. A request that targets one workspace selects a non-empty
+canonical workspace name; `default` is an ordinary explicit name, not an
+omitted-value fallback. Only sandbox, sandbox template, provider, and service
+collection list RPCs accept `all_workspaces`, after Platform Admin
+authorization. Provider-profile requests may omit the selector to address the
+platform profile scope. The authenticated sandbox bootstrap request may also
+omit it because the gateway resolves the immutable sandbox identity before the
+supervisor has learned its workspace. Canonical sandbox
+IDs remain internal metadata used at authentication, persistence, and
+compute-driver boundaries; public callers do not use them as sandbox
+references. The gateway resolves the name to the persisted sandbox record only
+after authorizing the selected workspace. A
+sandbox principal is instead resolved by the immutable ID in its authenticated
+identity, then checked against the requested name and workspace. Missing and
+unauthorized references use the same response within each principal class so
+the resolver does not expose an object-existence oracle. Sandbox, sandbox
+template, provider, and service collection list RPCs use the same field with an
+all-workspaces marker. Platform-global policy operations omit both `sandbox`
+and `workspace_scope`, while sandbox policy operations require both.
 
 Docker and Podman report the local address through which their sandboxes can
 reach the gateway. When the primary listener covers that address, the gateway
@@ -852,8 +871,8 @@ channel and returns the exec with an error. Once a command reports its exit
 status, the gateway also bounds how long it waits for the trailing channel close.
 
 `ForwardTcp` is the client-facing byte stream for SSH and service forwarding.
-The first frame is a `TcpForwardInit` that carries the sandbox ID, an
-authorization token from `CreateSshSession`, and an explicit target:
+The first frame is a `TcpForwardInit` that carries the workspace-scoped sandbox
+name, an authorization token from `CreateSshSession`, and an explicit target:
 `target.ssh` for the sandbox SSH socket or `target.tcp` for a loopback service
 inside the sandbox. The gateway validates the token and sandbox readiness,
 sends a targeted `RelayOpen` to the supervisor, then bridges