docs: document filesystem policies in sbx policy ls

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

@@ -23,8 +23,8 @@ Audit logging is active only while your organization enforces a centralized
 governance policy. The subscription alone doesn't produce records. If your
 organization hasn't configured and enforced an [organization policy](org.md),
 the daemon writes no audit logs. To confirm governance is active, run `sbx
-policy ls` — the output begins with a `Governance: managed by <org>` header
-when an organization policy is in effect.
+policy ls` — the output begins with a `Policy rules` header listing a
+`Governance  Managed by <org>` line when an organization policy is in effect.
 
 Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx
 policy ls` and `sbx policy log` is for live, interactive debugging. Audit

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

@@ -80,6 +80,10 @@ 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.
 
+A workspace mounted with write access must be allowed by both a `read` and a
+`write` rule; a read-only workspace needs only `read`. When default deny blocks
+a mount, the denial reason names whether read or write access was missing.
+
 `~` expands to the user's home directory on every platform, including Windows,
 where it resolves to `%USERPROFILE%`. A single `~/**` rule therefore matches
 each user's home tree on macOS, Linux, and Windows. The policy engine expands

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

@@ -138,11 +138,12 @@ $ sbx policy reset --force
 
 If rules you add with `sbx policy allow` or `sbx policy deny` don't change
 sandbox behavior, your organization likely has governance enabled. Run `sbx
-policy ls` to check: if the output starts with a `Governance: managed by <org>`
-header, org governance is active. When it's active, the organization policy
-replaces local policy, so your rules have no effect. They're hidden from `sbx
-policy ls` by default; run `sbx policy ls --include-inactive` to see them with
-an `inactive` status.
+policy ls` to check: if the output starts with a `Policy rules` header listing a
+`Governance  Managed by <org>` line, org governance is active. When it's active,
+the organization policy replaces local policy, so your rules have no effect.
+They're hidden from `sbx policy ls` by default; run `sbx policy ls
+--include-inactive` to see them with an `inactive` status in the `STATUS`
+column.
 
 Organization policy can't be supplemented from your machine. To change what
 your sandboxes can access, ask your admin to update the organization policy in
@@ -153,7 +154,8 @@ the Admin Console.
 If a domain remains blocked after you add a local allow rule, your organization
 likely enforces governance, which makes local rules inactive. Run `sbx policy
 ls` to check whether org governance is active; if the output starts with a
-`Governance: managed by <org>` header, it is. Add `--include-inactive` to
-confirm your rule shows an `inactive` status. If so, the block can only be
+`Policy rules` header listing a `Governance  Managed by <org>` line, it is. Add
+`--include-inactive` to confirm your rule shows an `inactive` status. If so, the
+block can only be
 lifted by updating the org policy in the Admin Console or via the
 [API](/reference/api/ai-governance/).

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

@@ -17,77 +17,119 @@ Use `sbx policy ls` to see all active rules and their current status:
 
 ```console
 $ sbx policy ls
-NAME                  TYPE      ORIGIN               DECISION   STATUS   RESOURCES
-balanced-dev          network   local                allow      active   api.anthropic.com
-ads-block             network   local                deny       active   ads.example.com
-kit:my-sandbox        network   sandbox:my-sandbox   allow      active   api.example.com
-kit:my-sandbox:deny   network   sandbox:my-sandbox   deny       active   telemetry.example.com
+PROVENANCE   APPLIES_TO     POLICY/RULE                  TYPE               DECISION   RESOURCES
+local        all            default-ai-services          network            allow      api.anthropic.com:443
+                                                                                       api.openai.com:443
+local        all            default-fs-read-allow-all    filesystem:read    allow      **
+local        all            default-fs-write-allow-all   filesystem:write   allow      **
+kit          sandbox:docs   kit:docs                     network            allow      api.github.com
+                                                                                       registry.npmjs.org
 ```
 
 The columns are:
 
-- `NAME`: the rule name.
-- `TYPE`: the rule domain, such as `network`.
-- `ORIGIN`: where the rule was configured. `local` means the rule is global
-  and applies to all sandboxes. `sandbox:<name>` means the rule is scoped to
-  the named sandbox. `remote` means the rule was set by your organization.
+- `PROVENANCE`: where the rule came from. `local` is a rule from your local
+  policy — a preset default or one you added with `sbx policy`. `kit` is a rule
+  added by a [kit](../customize/kits.md#control-network-access). `remote` is a
+  rule set by your organization.
+- `APPLIES_TO`: which sandboxes the rule applies to. `all` means the rule is
+  global. `sandbox:<name>` means it's scoped to the named sandbox.
+- `POLICY/RULE`: the rule's identity. Organization rules show as
+  `<policy> / <rule>`. Local and kit rules show the rule name.
+- `TYPE`: the rule domain. Network rules show as `network`. Filesystem rules
+  show as `filesystem:read` or `filesystem:write`, depending on the access the
+  rule controls.
 - `DECISION`: whether the rule allows or denies the resource.
-- `STATUS`: whether the rule is in effect. A rule may be `inactive` if it's
-  overridden or suppressed — for example, when organization governance is
-  active, local rules are not evaluated. Inactive rules are hidden by default;
-  pass `--include-inactive` to list them. See
-  [Showing inactive rules](#showing-inactive-rules).
 - `RESOURCES`: the hosts or patterns the rule applies to.
 
-When organization governance is active, the output starts with a governance
-header showing which organization manages the policy and when it last synced:
+A `STATUS` column also appears when you pass `--include-inactive`; see
+[Showing inactive rules](#showing-inactive-rules).
+
+When organization governance is active, the output starts with a `Policy rules`
+header showing which organization manages the policy, the sync state, and how
+many inactive rules are hidden:
 
 ```console
 $ sbx policy ls
-Governance: managed by my-org
-[OK] last synced 13:54:21
-NAME                  TYPE      ORIGIN               DECISION   STATUS   RESOURCES
-allow AI services     network   remote               allow      active   api.anthropic.com
-                                                                         api.openai.com
-allow Docker services network   remote               allow      active   *.docker.com
-                                                                         *.docker.io
+Policy rules
+------------
+Governance  Managed by my-org
+Sync        OK, last synced 08:21:01
+Hidden      9 inactive rules. Show with: sbx policy ls --include-inactive
+
+PROVENANCE   APPLIES_TO   POLICY/RULE                                      TYPE               DECISION   RESOURCES
+remote       all          default filesystem / allow home subdirectories   filesystem:write   allow      ~/**
+remote       all          default filesystem / deny home directory         filesystem:write   deny       ~/
+remote       all          default network / allow AI services              network            allow      api.anthropic.com
+                                                                                                         api.openai.com
+remote       all          default network / allow Docker services          network            allow      *.docker.com
+                                                                                                         *.docker.io
 ```
 
-The governance header shows which organization is managing the policy and
-confirms the daemon has successfully pulled the latest rules. If the sync
-status shows an error or a stale timestamp, the daemon may not have the most
-recent org policy. Run `sbx policy reset` to force a fresh pull.
+The `Governance` line shows which organization manages the policy, and `Sync`
+confirms the daemon has pulled the latest rules. If the sync state shows an
+error or a stale timestamp, the daemon may not have the most recent org policy.
+Run `sbx policy reset` to force a fresh pull. The `Hidden` line reports how many
+inactive rules are suppressed and how to reveal them.
 
 ### Showing inactive rules
 
 When organization governance is active, local and kit-defined rules are not
 evaluated, so `sbx policy ls` hides them by default. To list them too — for
 example, to confirm which local rules the organization policy overrides — pass
-`--include-inactive`:
+`--include-inactive`. This adds a `STATUS` column:
 
 ```console
 $ sbx policy ls --include-inactive
-Governance: managed by my-org
-[OK] last synced 13:54:21
-NAME                  TYPE      ORIGIN               DECISION   STATUS     RESOURCES
-balanced-dev          network   local                allow      inactive   api.anthropic.com
-allow AI services     network   remote               allow      active     api.anthropic.com
-                                                                           api.openai.com
-allow Docker services network   remote               allow      active     *.docker.com
-                                                                           *.docker.io
+Policy rules
+------------
+Governance  Managed by my-org
+Sync        OK, last synced 08:41:06
+
+PROVENANCE   APPLIES_TO   POLICY/RULE                                      TYPE               DECISION   STATUS                        RESOURCES
+local                     default-fs-read-allow-all                        filesystem:read    allow      inactive — corporate policy   **
+                                                                                                         takes precedence and does
+                                                                                                         not delegate this rule type
+                                                                                                         to local policy.
+local                     default-fs-write-allow-all                       filesystem:write   allow      inactive — corporate policy   **
+                                                                                                         takes precedence and does
+                                                                                                         not delegate this rule type
+                                                                                                         to local policy.
+remote       all          default filesystem / allow home subdirectories   filesystem:write   allow      active                        ~/**
+remote       all          default filesystem / deny home directory         filesystem:write   deny       active                        ~/
 ```
 
-Inactive rules show with an `inactive` status. They have no effect while
-organization governance is active.
+Inactive rules show `inactive` in the `STATUS` column, along with the reason.
+They have no effect while organization governance is active.
 
-Use `--type network` to show only network rules. Without a sandbox argument,
-`sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to
-filter to global rules and rules scoped to that sandbox:
+Use `--type network` or `--type filesystem` to show only rules of that type.
+Without a sandbox argument, `sbx policy ls` shows every rule across all
+sandboxes. Pass a sandbox name to filter to global rules and rules scoped to
+that sandbox:
 
 ```console
 $ sbx policy ls my-sandbox
 ```
 
+### Filesystem rules
+
+`sbx policy ls` lists filesystem rules alongside network rules. Filesystem
+rules control which host paths a sandbox can mount as a workspace. Pass
+`--type filesystem` to show only them:
+
+```console
+$ sbx policy ls --type filesystem
+PROVENANCE   APPLIES_TO   POLICY/RULE                  TYPE               DECISION   RESOURCES
+local        all          default-fs-read-allow-all    filesystem:read    allow      **
+local        all          default-fs-write-allow-all   filesystem:write   allow      **
+```
+
+A writable workspace mount must be allowed by both a `filesystem:read` and a
+`filesystem:write` rule; a read-only mount needs only `filesystem:read`. The
+default local policy allows read and write access to all paths, shown as the
+two `default-fs-*` rules above. For the rule syntax and path patterns, see
+[Policy concepts](concepts.md#filesystem-rules).
+
 ## Monitoring traffic
 
 Use `sbx policy log` to see which hosts your sandboxes have contacted and
@@ -127,3 +169,5 @@ $ sbx policy log my-sandbox
 
 Use `--limit N` to show only the last `N` entries, `--json` for
 machine-readable output, or `--type network` to filter by policy type.
+`sbx policy log` records network traffic only; filesystem mount decisions
+aren't available in the log yet.

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

@@ -71,8 +71,8 @@ access to.
 Admins can restrict which paths are mountable with filesystem allow and deny
 rules. 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).
+For path pattern syntax and how read and write access combine to allow a
+mount, see [Policy concepts](concepts.md#filesystem-rules).
 
 ## Scope policies to teams