sbx: document team-scoped and time-bounded governance policies

Add docs for scoping organization governance policies to specific teams
and bounding them with validity windows. Explains org-wide vs team-scoped
policies, how a user's effective policies combine (additive allows,
absolute denies, org-wide guardrails), and updates the AI Governance API
Scope schema with the teams and validity fields.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dvdksn

content/manuals/ai/sandboxes/governance/concepts.md

@@ -11,18 +11,17 @@ Docker sandbox governance is built around two resource types: **policies** and
 **rules**.
 
 A **policy** is a named collection of rules that controls sandbox access.
-Policies exist at different levels:
+Policies exist at two levels:
 
 - **Local**: configured per machine using the `sbx policy` CLI. Applies to
   sandboxes on that machine only.
 - **Organization**: configured in the Docker Admin Console or via the
-  [Governance API](/reference/api/ai-governance/). Applies uniformly across every sandbox in the
-  organization.
-- **Team**: applies to sandboxes used by a specific team within an
-  organization. Coming soon.
+  [Governance API](/reference/api/ai-governance/). Applies to sandboxes across
+  the organization. An organization can have several policies, each applying
+  either org-wide or to specific teams. See [Policy scope](#policy-scope).
 
-When multiple levels are active, organization policies take precedence over
-local policies. See [Precedence](#precedence).
+When organization governance is active, organization policies replace local
+policies entirely. See [Precedence](#precedence).
 
 A **rule** is the unit of access control within a policy. Each rule has:
 
@@ -34,6 +33,32 @@ A **rule** is the unit of access control within a policy. Each rule has:
 Rules are grouped by domain: all rules in a policy must share the same domain,
 either `network` or `filesystem`.
 
+## Policy scope
+
+Each organization policy applies either across the whole organization or only
+to specific teams. The policy's scope determines which members it applies to:
+
+- **Org-wide**: with no teams assigned, the policy applies to every member of
+  the organization.
+- **Team-scoped**: with one or more teams assigned, the policy applies only to
+  members of those teams.
+
+Teams are the same [teams](/manuals/admin/organization/manage/manage-a-team.md)
+you manage for your organization. A team-scoped policy references the teams it
+applies to, and Docker matches those teams against each user's team membership.
+Because assignment follows team membership, you can govern an organization with
+thousands of users without configuring policies per user.
+
+An organization can mix org-wide and team-scoped policies. A user's effective
+policy set is every org-wide policy plus every team-scoped policy for a team
+the user belongs to. See [Rule evaluation](#rule-evaluation) for how those
+policies combine.
+
+A policy can also be bound in time with a validity window, independent of team
+scope. A validity window can set a start time, an end time, both, or neither. A
+policy with no validity window is always active while governance is enabled for
+the organization.
+
 ## Rule syntax
 
 ### Network rules
@@ -43,12 +68,12 @@ hostnames, CIDR ranges, or ports.
 
 **Hostname patterns**
 
-| Pattern | Example | Matches |
-| ------- | ------- | ------- |
-| Exact hostname | `example.com` | `example.com` only, not subdomains |
-| Single-level wildcard | `*.example.com` | One subdomain level: `api.example.com` |
-| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` |
-| Hostname with port | `example.com:443` | `example.com` on port 443 only |
+| Pattern               | Example           | Matches                                            |
+| --------------------- | ----------------- | -------------------------------------------------- |
+| Exact hostname        | `example.com`     | `example.com` only, not subdomains                 |
+| Single-level wildcard | `*.example.com`   | One subdomain level: `api.example.com`             |
+| Multi-level wildcard  | `**.example.com`  | Any depth: `api.example.com`, `v2.api.example.com` |
+| Hostname with port    | `example.com:443` | `example.com` on port 443 only                     |
 
 `example.com` and `*.example.com` don't cover each other. Specify both if you
 need to match the root domain and its subdomains.
@@ -63,11 +88,11 @@ Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`,
 Filesystem rules use the actions `read` and `write`. Resources are host paths
 that sandboxes can mount as workspaces.
 
-| Pattern | Example | Matches |
-| ------- | ------- | ------- |
-| Exact path | `/data` | `/data` only |
-| Segment wildcard | `/data/*` | `/data/project`, one path segment only, not subdirectories |
-| Recursive wildcard | `/data/**` | `/data/project`, `/data/project/src`, any depth |
+| Pattern            | Example    | Matches                                                    |
+| ------------------ | ---------- | ---------------------------------------------------------- |
+| Exact path         | `/data`    | `/data` only                                               |
+| Segment wildcard   | `/data/*`  | `/data/project`, one path segment only, not subdirectories |
+| Recursive wildcard | `/data/**` | `/data/project`, `/data/project/src`, any depth            |
 
 Use `**` when you intend to match a directory tree recursively. A single `*`
 only matches within one path segment and won't cross directory boundaries.
@@ -76,15 +101,22 @@ matches only direct children of `~`.
 
 ## Rule evaluation
 
-All rules in a policy are evaluated against every request. The outcome follows
-two principles:
+When organization governance is active, the rules from all of a user's
+effective policies (every org-wide policy plus every matching team-scoped
+policy) are combined and evaluated together against each request. Evaluation
+follows two principles:
 
 **Deny wins.** If any rule matches with `decision: deny`, the request is
 denied regardless of any matching allow rules.
 
 **Default deny.** Outbound traffic is blocked unless an explicit allow rule
 matches.
 
+Because rules combine across policies, allows are additive (a request is
+allowed if any effective policy allows it) and denies are absolute (a request
+is blocked if any effective policy denies it). A deny rule in an org-wide
+policy therefore acts as a guardrail that no team-scoped policy can override.
+
 These principles apply within whichever policy is active. When organization
 governance is active, only organization rules are evaluated; local rules have
 no effect.
@@ -101,5 +133,7 @@ whether your organization has governance enabled:
   developer machines, and local and kit-defined rules are not evaluated. They
   still appear in `sbx policy ls`, but with an `inactive` status.
 
-Within the active policy, deny rules beat allow rules regardless of specificity
-or order.
+When organization governance is active, all of a user's effective
+organization policies combine into a single rule set, where deny rules beat
+allow rules regardless of which policy they come from, their specificity, or
+their order. See [Rule evaluation](#rule-evaluation).

content/manuals/ai/sandboxes/governance/org.md

@@ -54,11 +54,56 @@ access**. Each rule takes a path pattern and an action (allow or deny).
 For path pattern syntax including the difference between `*` and `**`, see
 [Policy concepts](concepts.md#filesystem-rules).
 
+## Scope policies to teams
+
+An organization can have more than one policy, and each policy applies either
+to the whole organization or to specific teams. Use scoping to give different
+parts of the organization different rules: for example, a permissive policy for
+a security research team alongside a stricter default for everyone else.
+
+When you create or edit a policy in the Admin Console, the **Scope** setting
+controls who it applies to:
+
+- Leave the team list empty to make the policy org-wide. It applies to every
+  member of the organization.
+- Add one or more teams to scope the policy to those teams. It applies only to
+  members of the listed teams.
+
+Teams are the same [teams](/manuals/admin/organization/manage/manage-a-team.md)
+you manage for your organization, so assignment follows existing team
+membership. This lets you manage policies for an organization with thousands of
+users without configuring anything per user. When team membership changes in
+your identity provider, the policies a user receives change with it.
+
+### How org-wide and team-scoped policies combine
+
+A user receives every org-wide policy plus every team-scoped policy for a team
+they belong to. The rules from all of these policies are combined and evaluated
+together:
+
+- **Allows are additive.** A request is allowed if any of the user's effective
+  policies allow it.
+- **Denies are absolute.** A request is blocked if any of the user's effective
+  policies deny it.
+
+Because deny always wins, a deny rule in an org-wide policy acts as a guardrail
+that team-scoped policies can't override. Use org-wide policies for rules that
+must apply everywhere, and team-scoped policies to grant additional access to
+specific teams.
+
+### Validity windows
+
+A policy can also be limited to a time window, independent of its team scope.
+Set a start time, an end time, both, or neither when you create or edit the
+policy. A policy with no validity window is always active while governance is
+enabled. Use a validity window for time-bound exceptions, such as temporary
+access granted for the duration of a project.
+
 ## Precedence
 
-Within the active policy, deny rules beat allow rules. If a domain matches both,
-it's blocked regardless of specificity. Outbound traffic is blocked unless a
-rule allows it.
+Deny rules beat allow rules. If a resource matches both an allow and a deny, in
+the same policy or across a user's effective policies, it's blocked regardless
+of specificity. Outbound traffic is blocked unless a rule allows it.
 
 When organization governance is active, local rules are not evaluated. Only
 organization rules set in the Admin Console determine what is allowed or

content/reference/api/ai-governance/api.yaml

@@ -488,7 +488,11 @@ components:
 
     Scope:
       type: object
-      description: Restricts the policy to specific profiles or teams. Empty or absent lists mean the policy applies org-wide.
+      description: >
+        Restricts the policy to specific profiles or teams, and optionally to a
+        time window. An empty or absent `teams` list means the policy applies to
+        every member of the organization. A non-empty `teams` list means the
+        policy applies only to members of the listed teams.
       properties:
         profiles:
           type: array
@@ -498,8 +502,31 @@ components:
             - ["security"]
         teams:
           type: array
+          description: >
+            Identifiers of the teams (organization groups) the policy applies
+            to. Each value must be a valid group in the target organization;
+            requests referencing unknown identifiers are rejected.
           items:
             type: string
+        validity:
+          type: object
+          description: >
+            Optional time window during which the policy is active. Both fields
+            are optional; a policy with neither set is always active while
+            governance is enabled for the organization.
+          properties:
+            notBefore:
+              type: string
+              format: date-time
+              description: The policy is not active before this timestamp.
+              examples:
+                - "2026-04-22T00:00:00Z"
+            notAfter:
+              type: string
+              format: date-time
+              description: The policy is not active after this timestamp.
+              examples:
+                - "2026-07-22T00:00:00Z"
 
     AllowlistV0:
       type: object