Merge pull request #271 from flashcatcloud/doc-review/2026-08-14-061500

Doc Review — 2026-08-14

Author: ysyneu

docs.json

@@ -1506,6 +1506,7 @@
                   "zh/on-call/incident/what-is-incident",
                   "zh/on-call/incident/search-view-incident",
                   "zh/on-call/incident/handle-update-incident",
+                  "zh/on-call/incident/work-items",
                   "zh/on-call/incident/escalate-dispatch-incident",
                   "zh/on-call/incident/alert-management",
                   "zh/on-call/incident/custom-actions",
@@ -2855,6 +2856,7 @@
                   "en/on-call/incident/what-is-incident",
                   "en/on-call/incident/search-view-incident",
                   "en/on-call/incident/handle-update-incident",
+                  "en/on-call/incident/work-items",
                   "en/on-call/incident/escalate-dispatch-incident",
                   "en/on-call/incident/alert-management",
                   "en/on-call/incident/custom-actions",

en/ai-sre/agents.mdx

@@ -77,7 +77,7 @@ On the A2A Agents list page, click **Add A2A Agent** and fill in the form:
 | Streaming | bool | on | Whether to communicate with the remote agent in streaming mode |
 | User Auth Mode | enum | `shared` | See "Auth Modes" below |
 | Skip TLS certificate verification | bool | off | Shown only when the Card URL uses HTTPS. Enable only when the remote endpoint uses a self-signed certificate inside a controlled network; this skips certificate-chain and hostname verification |
-| Allow OAuth discovery over HTTP | bool | off | Required only when "Per-user OAuth" is selected and the Card URL is a non-local HTTP URL. Use only in controlled test environments; after you enable it, the AI SRE service can fetch OAuth metadata from that host |
+| Allow fetching OAuth configuration over HTTP (testing only) | bool | off | Required only when "Per-user OAuth" is selected and the Card URL is a non-local HTTP URL. Use only in controlled test environments; after you enable it, the AI SRE service can fetch OAuth metadata from that host |
 
 ### Writing Instructions
 
@@ -170,7 +170,7 @@ For security reasons, saved sensitive fields (such as `token`, `api_key`, and `c
 </Note>
 
 <Warning>
-Use HTTPS for per-user OAuth discovery whenever possible. Enable "Allow OAuth discovery over HTTP" for a non-local HTTP Card URL only in controlled test environments. If an HTTPS endpoint uses a self-signed certificate, enable "Skip TLS certificate verification" only temporarily and only inside a trusted network.
+Use HTTPS for per-user OAuth discovery whenever possible. Enable "Allow fetching OAuth configuration over HTTP (testing only)" for a non-local HTTP Card URL only in controlled test environments. If an HTTPS endpoint uses a self-signed certificate, enable "Skip TLS certificate verification" only temporarily and only inside a trusted network.
 </Warning>
 
 ## Inbound: Letting External Agents Call AI SRE
@@ -240,7 +240,7 @@ A2A agents share the same **two-level scope** model as other resources (skills,
 | Account level | Visible to all members in the account |
 | Team level | Visible only to members of that team |
 
-**Edit permissions**: the account owner or account admin can edit any agent; team members can edit team-level agents **in their own team**; there is no creator-retains-rights exception. When you do not have edit permission, the corresponding row in the list is **read-only**.
+**Edit permissions**: team-level agents can be acted on only by members of that team — organization admins must join the team first; account-level agents can be acted on only by the account owner or account admin; there is no creator-retains-rights exception. When you do not have edit permission, the corresponding row in the list is **read-only**.
 
 **Create and reassign**: to create a new team-level agent, you must belong to the target team; account-level creation is limited to the account owner or admins. When editing an existing agent, the account owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to.
 

en/ai-sre/apps.mdx

@@ -50,15 +50,15 @@ A Kubernetes App connects an in-cluster agent to AI SRE. After installation, AI
     Go to **Plugins → Apps → Kubernetes Apps** and click **Create Kubernetes App**. Enter a cluster name and choose its scope: **Shared** is available to all sessions in the account; **Team** is available to that team's sessions and to personal sessions of its members. Cluster names must be unique within a scope.
   </Step>
   <Step title="Set namespace access">
-    Choose **All namespaces** or **Specific namespaces**. All namespaces applies one permission level to current and future namespaces. With specific namespaces, set **Read-only** or **Read + limited modifications** for each namespace. Leaving the specific-namespace list empty allows the agent to read only basic cluster metadata.
+    Choose **All namespaces** or **Specific namespaces**. All namespaces applies one permission level to current and future namespaces. With specific namespaces, set **Read-only**, **Read + limited modifications**, or **Full access** for each namespace. Leaving the specific-namespace list empty allows the agent to read only basic cluster metadata. **Full access** means unrestricted cluster administrator access: on a specific namespace it applies only inside that namespace (cluster metadata stays read-only), while **All namespaces + Full access** grants `cluster-admin` via a `ClusterRoleBinding`, including cluster-scoped resources and cluster RBAC (available only with All namespaces). Open **View Kubernetes RBAC details** in the form to see exactly what each level allows.
   </Step>
   <Step title="Run the installation command">
     Save the App, copy the generated installation command, and run it in the target cluster. Installation commands expire; reopen the installation setup or view the manifest to generate a new command without rotating the token.
   </Step>
 </Steps>
 
 <Warning>
-After changing namespace access or permissions, run the installation command again so the in-cluster RBAC is updated. Before choosing **Read + limited modifications**, confirm that AI SRE is allowed to perform those actions in the namespace.
+After changing namespace access or permissions, run the installation command again so the in-cluster RBAC is updated. Before choosing **Read + limited modifications**, confirm that AI SRE is allowed to perform those actions in the namespace. **Full access** is a high-risk option: on a specific namespace it lets this App read, create, modify, and delete every resource in that namespace; **All namespaces + Full access** escalates to cluster administrator access (`cluster-admin`), so choose it with care.
 </Warning>
 
 ### Edit and revoke

en/ai-sre/automations.mdx

@@ -239,13 +239,13 @@ Automation rules share the same two-level scope model as the other resources und
 |---|---|
 | Ownership | **Personal rules** (`team_id=0`) belong to their creator; **team rules** (`team_id>0`) belong to that team. To create a team rule, the rule Owner must be a real member of the target team; account Owners and admins have no exemption. You can change a rule's scope: personal rules can be moved to a team and team rules to another team — in both cases the rule Owner must belong to the destination team. However, a **team rule cannot be taken personal**: when editing a team rule, the scope selector no longer offers the "Personal" option (the backend rejects the conversion as well), and the rule stays with its team. If you need a personal copy, use the **Clone** button on the rule's detail page and pick the Personal scope in the prefilled create form before saving. Before every run, the system also checks that the Owner of a team rule still belongs to its team. |
 | Visibility / list | The account Owner and admins see all rules; ordinary members see rules they created and rules of teams they belong to. |
-| Edit / manage (team rules) | The account Owner and admins can manage any team rule; ordinary team members can manage rules of teams they belong to (enable / disable, edit, delete). |
+| Edit / manage (team rules) | Only members of the rule's owning team or its creator can act on the rule (enable / disable, edit, delete); the account Owner and admins have no exemption and must join the team first. |
 | Edit / manage (personal rules) | Only the creator can manage a personal rule. The account Owner and admins have **no** exemption for other members' personal rules — they cannot even view its detail page; opening one returns "access denied" outright, not just a grayed-out button. |
 | HTTP POST trigger | When initiating a real run through the trigger URL, authorization is only the trigger's Bearer Token. Any external system holding that Token can trigger the rule, and the run creates a hidden session under the rule's personal or team scope. |
 | On-call incident trigger | Started by a registered incident subscription, not by an HTTP POST Bearer token. The run still creates a hidden session under the rule's personal or team scope. |
 
 <Note>
-The account Owner / admins can see other members' personal rules in the list (see "Visibility / list" above), but clicking into the detail page is denied — the "Edit / manage" exemption that applies to Owner / admins on team rules does not extend to personal rules.
+The account Owner / admins can see other members' personal rules in the list (see "Visibility / list" above), but clicking into the detail page is denied — the "Edit / manage" permission is not exempted for the Owner / admins on personal rules, just as it is not on team rules.
 </Note>
 
 <Warning>

en/ai-sre/environments.mdx

@@ -382,6 +382,15 @@ permission:
 Command permission is currently configured only through this file — there is no console UI for it yet.
 </Note>
 
+### File-system boundary
+
+Permission configuration governs **commands**; the agent's **file read/write tools** follow their own path semantics, matching `bash`:
+
+- **Relative paths** are confined to the workspace root with symlink-escape protection — through a relative path the agent can only read and write files inside the workspace.
+- **Absolute paths** are passed through to the host filesystem by design, matching `bash`.
+
+So the real file-access boundary is the **OS user** the Runner runs as, plus the deployment isolation (the systemd user and directory protections, or Docker mounts and container boundary) — not the permission configuration file.
+
 ## Selecting an environment in a session
 
 ---
@@ -413,8 +422,8 @@ Each BYOC Environment has account-level or team-level scope:
 
 Edit permissions follow the unified rule:
 
-1. Account owners and account admins can edit any Environment.
-2. Team members can edit team-scoped Environments for their team.
+1. Team-scoped Environments can be acted on only by members of that team — organization admins must join the team first.
+2. Account-scoped Environments (shared scope) can be acted on only by organization admins.
 3. There is no "creator extra permission"; you do not need to be the creator if the rules above allow the edit.
 
 <Note>

en/ai-sre/insight.mdx

@@ -117,6 +117,8 @@ Friction cards ranked **from highest to lowest importance**, up to approximately
 
 About **2–3** forward-looking, grounded suggestions. These are **strategic** (a shift in *how* you work with AI SRE, higher-leverage), distinct from the tactical, file-level fixes in the friction cards; each names the exact observation it's grounded in (a stat from the overview or a friction cluster) and maps to a real AI SRE capability.
 
+When the report surfaces the `expensive-automation` emergent pattern — an automation-entry session that pulls raw listings into context and counts / groups / ranks them itself instead of scripting the aggregation — the next steps include a **Script-first automation rewrite**: ask the agent in chat to rewrite that automation's task prompt script-first, turning the deterministic collection and aggregation into an embedded, tested script.
+
 <Note>
 Every friction and win must be grounded in at least one real session and carry a verbatim quote as evidence — the report never fabricates sessions, facts, or runbook gaps. If no rankable friction is found, the frictions part displays an empty-state message while the rest of the report still renders — in that case, "the overview itself is the report."
 </Note>

en/ai-sre/knowledge.mdx

@@ -133,11 +133,11 @@ Every Knowledge Pack has a scope: account-level (visible across the entire accou
 | Dimension | Account-level | Team-level |
 | --- | --- | --- |
 | Visibility | All agents / sessions within the account | Sessions and members of that team only |
-| Edit permission | Account Owner or account admin | Members of that team, or Account Owner / admin |
+| Edit permission | Account Owner or account admin | Only members of that team — organization admins must join the team first |
 | Loaded in session | All sessions | Only sessions bound to that team |
 | Readable at runtime | Entire account | Entire account (mounting occurs on read) |
 
-**Edit permissions**: the Account Owner or account admin can edit any Knowledge Pack; team members can edit their team's team-level pack; there is no "creator retains extra rights" rule. The console grays out rows the current user cannot edit, and disables toggles and action buttons when you lack edit permission.
+**Edit permissions**: team-level packs can be acted on only by members of that team — organization admins must join the team first; account-level packs can be acted on only by the Account Owner or admins; there is no "creator retains extra rights" rule. The console grays out rows the current user cannot edit, and disables toggles and action buttons when you lack edit permission.
 
 **Create and reassign**: to create a new team-level pack, you must belong to the target team; account-level creation is limited to the Account Owner or admins. When editing an existing pack, the Account Owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to. Promoting an existing pack to account scope (**Set to Shared**) carries the same gate as creating an account-scope pack: only the Account Owner or admins can do it — a regular member cannot self-serve this even for their own team's pack.
 

en/ai-sre/mcp.mdx

@@ -102,6 +102,10 @@ Each MCP server also has an **AI description**: after an agent first lists a ser
 **stdio is only available for BYOC environments** (Runner deployed on your own machine). Cloud Sandboxes cannot launch local subprocesses. If you are using a cloud environment, use **HTTP Streaming** or **SSE** instead, and ensure the MCP server is reachable from the Sandbox network. For differences between environments, see [Environments (BYOC)](/en/ai-sre/environments).
 </Warning>
 
+<Note>
+stdio server commands run on the **machine where the Runner is deployed**, not on the machine of the person who configured them. Shared configuration must be portable: do not write personal machine paths into commands or arguments (e.g., `/Users/your-name/...`, `/home/your-name/...`), and make sure the executing environment has the runtime the command needs (`uv` / `uvx` / `node` / `npx`). A missing runtime makes the server fail to connect.
+</Note>
+
 There is a default timeout for both connection and tool calls: 10 seconds for connection, 60 seconds for tool invocation.
 
 <Warning>
@@ -114,7 +118,7 @@ MCP servers support three **authentication modes** that determine how credential
 
 <Tabs>
   <Tab title="Shared (default)">
-    All users share the same credentials. Credentials are written directly into the server configuration — for HTTP/SSE transport, in the **Headers** (JSON) (e.g., `{ "Authorization": "Bearer xxx" }`); for stdio transport, in the **environment variables** (JSON) (e.g., `{ "API_KEY": "xxx" }`). Suitable for internal systems accessed with account-level service tokens.
+    All users share the same credentials. Credentials are written directly into the server configuration — for HTTP/SSE transport, in the **Headers** (JSON) (e.g., `{ "Authorization": "Bearer xxx" }`); for stdio transport, in the **environment variables** (JSON) (e.g., `{ "API_KEY": "xxx" }`). Suitable for internal systems accessed with account-level service tokens. Note that shared credentials are stored in **plaintext** in the server configuration (per-user keys are encrypted instead). For sensitive secrets, prefer "Per-User API Key" or "Per-User OAuth".
   </Tab>
   <Tab title="Per-User API Key">
     Each user provides their own key the **first time** they invoke a tool on this server. Keys are encrypted and stored at the account level, isolated per user.
@@ -201,7 +205,7 @@ MCP shares the same **two-level scope** model as other resources (Skills, Knowle
 | Account-level | Visible to all members of the account |
 | Team-level | Visible only to members of that team |
 
-**Edit permissions**: Account owners or account admins can edit any MCP server; team members can edit team-level MCP servers that belong to **their team**. There is no creator-retains-rights exception. When you lack edit permission, the toggle and action buttons for that row appear as **read-only**.
+**Edit permissions**: team-level MCP servers can be acted on only by members of that team — organization admins must join the team first; account-level MCP servers can be acted on only by the account owner or admins. There is no creator-retains-rights exception. When you lack edit permission, the toggle and action buttons for that row appear as **read-only**.
 
 **Create and reassign**: to create a new team-level MCP server, you must belong to the target team; account-level creation is limited to the account owner or admins. **Marketplace installs are the exception**: they are always account-scope, and any account member can install one (no owner/admin permission required). When editing an existing MCP server, the account owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to. However, **Marketplace-installed MCP servers cannot be reassigned to a team** — their scope is shown as a fixed account value in the edit form. A small number of legacy team-scoped Marketplace rows from earlier versions can still be changed back to account scope (promoted to shared); the reverse is not allowed. **Promoting to shared carries the same gate as account-level creation: only the account owner or admins can do it** — a regular member is denied even for servers belonging to their own team, and the prompt now reads "ask an admin to make it shared" instead of naming the owning team.
 

en/ai-sre/sandbox.mdx

@@ -17,6 +17,8 @@ The **cloud sandbox** is a **temporary execution environment** managed by Flashd
 
 It is AI SRE's **default fallback**: when no usable self-hosted Runner ([BYOC Runner](/en/ai-sre/environments#byoc-runner)) is online for the current member, sessions automatically run in the cloud sandbox; you can also **pin a session to it manually**.
 
+The cloud sandbox executes on the hosting provider's serverless platform, in **Hong Kong** by default (Tencent AGS Hong Kong); when that region is unavailable, provisioning falls back to **Guangzhou** (Tencent AGS) and then **Beijing** (Aliyun FC), in that order.
+
 <CardGroup cols={2}>
   <Card title="Zero install, ready to use" icon="cloud">
     No process to deploy and no credentials to enter. New accounts, ad-hoc investigations, and demos can start chatting right away on a clean sandbox the system allocates.