Merge pull request #164 from flashcatcloud/doc-review/2026-07-11-004443

docs(ai-sre): fix drift and coverage gaps from doc-review audit (35 findings)

Author: ysyneu

docs.json

@@ -587,7 +587,8 @@
                 "pages": [
                   "zh/ai-sre/sessions",
                   "zh/ai-sre/im",
-                  "zh/ai-sre/automations"
+                  "zh/ai-sre/automations",
+                  "zh/ai-sre/artifacts"
                 ]
               },
               {
@@ -1794,7 +1795,8 @@
                 "pages": [
                   "en/ai-sre/sessions",
                   "en/ai-sre/im",
-                  "en/ai-sre/automations"
+                  "en/ai-sre/automations",
+                  "en/ai-sre/artifacts"
                 ]
               },
               {

en/ai-sre/agents.mdx

@@ -70,8 +70,9 @@ On the A2A Agents list page, click **Add A2A Agent** and fill in the form:
 | --- | --- | --- | --- |
 | Name | string | — | A2A agent identifier (e.g., `metrics-analyzer`). Required |
 | Scope | Account / Team | — | Scope: **Account** (visible account-wide) or a specific **Team** (visible and editable only to members of that team). Required — see "Scope" below |
+| Execution Environment | Auto / BYOC Runner | `Auto` | Pins this A2A agent's delegated requests to a specific online BYOC Runner; defaults to **Auto** (no environment pinned — the backend picks one automatically per call), and a Cloud Sandbox cannot be selected. This controls which Runner the agent's outbound calls run from, which is a different concept from the per-user-OAuth execution environment picker in "Auth Modes" below — that one only decides which environment a given OAuth network request is issued from |
 | Instructions | string | — | The agent-selection signal shown to AI SRE. It is inserted into AI SRE's system prompt and available-agent list to decide when to call this A2A agent. Required; write prescriptive guidance that explains when to use the agent, its capability boundaries, and when not to use it. Maximum 2,000 characters |
-| Card URL | string | — | The Agent Card URL of the remote A2A agent, or just the service origin for agents that follow the default well-known location (for example, `https://agents.example.com`). If the URL includes a path, the platform reads that exact URL; if only an origin is provided, it resolves `/.well-known/agent-card.json` by A2A convention. Required. The platform validates that it is a legitimate http/https address and rejects loopback, private, link-local, or cloud-metadata addresses |
+| Card URL | string | — | The Agent Card URL of the remote A2A agent, or just the service origin for agents that follow the default well-known location (for example, `https://agents.example.com`). If the URL includes a path, the platform reads that exact URL; if only an origin is provided, it resolves `/.well-known/agent-card.json` by A2A convention. Required. The platform only validates that the URL is well-formed (scheme is http/https, host is non-empty) — it does not classify hosts or IPs; actual network reachability and egress restrictions depend on the network boundary of the selected **execution environment** (Cloud Sandbox / BYOC Runner) |
 | Auth Type | enum | `none` | Credential type attached to outbound requests: `none` / `bearer` (Bearer Token) / `api_key` (custom Header + Key) |
 | Streaming | bool | on | Whether to communicate with the remote agent in streaming mode |
 | User Auth Mode | enum | `shared` | See "Auth Modes" below |

en/ai-sre/apps.mdx

@@ -49,7 +49,7 @@ Start the authorization from the GitHub card. The whole install completes in a p
 
 <Steps>
   <Step title="Start the authorization">
-    Click **Authorize** on the GitHub card (if the App already has an installation, the button reads **Connect another organization**). The frontend opens a popup that loads GitHub's official install page.
+    Click **Authorize** on the GitHub card (if the App already has an installation, the button reads **More repositories**, with a + icon). The frontend opens a popup that loads GitHub's official install page.
   </Step>
   <Step title="Pick the organization and repositories on GitHub">
     Choose the **organization** (or personal account) to install into, and grant a repository scope — **All repositories** or **Only select repositories**. The set of granted repositories determines which repositories AI SRE can access afterward.
@@ -88,7 +88,7 @@ Each authorized organization adds one installation row under the GitHub card. Ea
 
 ### Adding or Adjusting Repository Access
 
-The organization is already connected, but you want AI SRE to reach more of its repositories — you don't need to revoke and reconnect. In **Plugins → Apps**, click **Authorize / Connect another organization** again for that organization (or open the App's **Configure** page on GitHub directly). GitHub shows the **Repository access** screen; select the additional repositories and save, and AI SRE **re-syncs** the granted repository list automatically — the new repositories become available without re-creating the connection.
+The organization is already connected, but you want AI SRE to reach more of its repositories — you don't need to revoke and reconnect. In **Plugins → Apps**, click **More repositories** again for that organization (or open the App's **Configure** page on GitHub directly). GitHub shows the **Repository access** screen; select the additional repositories and save, and AI SRE **re-syncs** the granted repository list automatically — the new repositories become available without re-creating the connection.
 
 <Note>
 **Fallback**: if a newly added repository still reports "cannot access / 404 / 403" in a session, open the App's page on GitHub (e.g. `github.com/apps/flashduty`) → **Configure** → select the organization → scroll to the **Danger zone** → **Uninstall**. Then return to **Plugins → Apps** in Flashduty and authorize the organization again, granting **all** the repositories you need in one pass.
@@ -129,6 +129,8 @@ An account can connect **only one** GitLab instance at a time (GitLab.com or one
 
 After you save the repository selection, Flashduty provisions a dedicated bot for the account inside those groups / projects (a service account where the instance supports it, falling back to a group- or project-level access token otherwise) for AI SRE sessions to use. Either way, the bot's permissions are capped at **Developer** level — the same minimum access you'd grant it in GitLab yourself. Tokens are **rotated automatically** before they expire; there's nothing for you to manage.
 
+If the instance doesn't support service accounts, the bot falls back to a group- or project-level token — and a token like that can only ever bind to a single group or project, so the repository picker limits you to selecting at most **one** group or project. If you select multiple groups / projects while in multi-select mode and save, Flashduty shows "This GitLab instance doesn't support service accounts; select only one group or project and retry," and switches the picker to **single-select mode**: checking a new group or project after that automatically clears any other selection, so you need to leave just one group or project checked before saving again.
+
 <Warning>
 **One restriction on GitLab.com**: GitLab's own policy limits group- and project-level access tokens to **paid (non-free, non-trial) namespaces**. Connecting GitLab.com itself is unaffected, but if the group / project you authorize lives in a free or trial namespace, bot provisioning fails and the UI shows GitLab's own explanation ("provisioning_denied"). Upgrade that namespace to a paid plan and re-authorize to resolve it.
 </Warning>

en/ai-sre/artifacts.mdx

@@ -0,0 +1,119 @@
+---
+title: Artifacts
+description: The artifact gallery collects web pages and reports that AI SRE sessions produce with the present_files tool and publish with the publish_artifact tool (for example, /insight reports). Search, filter by scope, rename, share, download, and delete them here.
+keywords: ["AI SRE", "Artifacts", "present_files", "publish_artifact", "insight report", "artifact gallery"]
+sidebarTitle: Artifacts
+---
+
+<Info>
+  **Private beta**: AI SRE is currently in private beta. Pro or higher accounts can apply for free beta access through the [AI SRE private beta application form](https://c9xudyniiq.feishu.cn/share/base/form/shrcn0ngCfdoygiaHnAT80BfZiH); after approval, Flashduty will add your account to the whitelist. Features and the UI may change during the beta.
+</Info>
+
+## Overview
+
+---
+
+An artifact is a file AI SRE produces in a session with the `present_files` tool and then publishes to the artifact gallery with the `publish_artifact` tool — typically a self-contained HTML report or page. For example, the operational insight report generated by typing `/insight` in a session is an artifact.
+
+A published artifact inherits its source session's scope: artifacts from a personal session belong to their creator ("Personal"); artifacts from a session bound to a team belong to that team and can be shared with other account members.
+
+Entry point: **AI SRE → Artifacts** in the left navigation, route `/ai-sre/artifacts`.
+
+<Note>
+The artifact gallery has no entry point for manually uploading or creating files — every artifact is produced and published by the agent using tools during a session. The console only lets you browse, search, and manage artifacts that already exist.
+</Note>
+
+## List Page
+
+---
+
+### Search and scope filter
+
+- **Search box**: fuzzy-search published artifacts by title; the query fires automatically 300ms after you stop typing.
+- **Scope**: a three-way **All / Personal / Team** switch (the same two-level scope shared with other resources under Customize). Selecting "Team" expands a searchable, multi-select team picker; selecting no team means "all teams visible to me."
+
+### Artifact cards
+
+Each card shows:
+
+- A kind icon in the preview area: a code icon when the content type or file name is HTML, otherwise a document icon;
+- The title (up to two lines, truncated beyond that);
+- An "Edited …" relative timestamp — just now / N minutes ago / N hours ago / N days ago, or a specific date beyond 30 days;
+- A scope badge in the bottom right: team artifacts show the team name (highlighted green); personal artifacts show the creator's name (gray).
+
+Clicking the card body opens the artifact's detail page. Hovering over a card reveals a "More actions" button in the top-right corner (always visible on touch devices).
+
+### Creating an artifact
+
+Click **New artifact** in the upper-right corner of the page to jump to the chat page with a prefilled draft prompt:
+
+> I want to build a publishable Artifact in Flashduty AI-SRE: a self-contained web page or report published with the publish_artifact tool. Ask me a few focused questions about the audience, content/data, interactions, and visual style, then build it and publish it.
+
+The agent first asks you about the target audience, content/data source, interactions, and visual style, then builds and publishes the artifact — there is no form to fill out directly.
+
+<Tip>
+Separately, any file shown in a session with `present_files` also has a "Publish to artifact gallery" button next to it, letting you publish a file that session already produced directly as an artifact — a more direct path than "New artifact" when you don't need a fresh conversation.
+</Tip>
+
+## Card Actions
+
+---
+
+The "More actions" menu on each card offers:
+
+| Action | Notes |
+|---|---|
+| Copy link | Copies the full URL of the artifact's detail page, which you can share with other account members |
+| Download | Only appears when the artifact is linked to a file (`file_id` is non-empty); downloads the original file |
+| Rename | Only appears when you have edit permission on the artifact; opens a dialog to change the title |
+| Delete | Only appears when you have edit permission on the artifact; requires confirmation. Deleting removes the artifact from the gallery, but the source session and underlying file are unaffected |
+
+## Detail Page
+
+---
+
+The detail page route is `/ai-sre/artifacts/:artifactId`. The top toolbar offers:
+
+- **Title**: if you have edit permission, click the title to edit it inline (no separate form) — press Enter to save, Esc to cancel;
+- **Creator**: shown below the title as "Artifact by [creator]";
+- **Share**: copies the link to the artifact's detail page;
+- **Delete**: shown only when you have edit permission; requires confirmation;
+- **More actions**: this menu appears only when at least one of the following is available —
+  - **Open session**: shown when you still have access to the artifact's source session; opens that session's full conversation (messages, tool calls, artifact history);
+  - **Download**: shown when the artifact is linked to a file.
+
+The body renders the artifact according to its actual content type (for example, an HTML report renders inline as a page).
+
+## Permissions
+
+---
+
+Whether an artifact is editable (rename, delete) is determined by the `can_edit` field returned by the backend. Any one of the following grants management access:
+
+| Condition | Notes |
+|---|---|
+| Creator | The owner of the session the artifact was published from |
+| Account Owner / admin | Has management access to any artifact in the account, personal or team scope |
+| Team member (team artifacts only) | When an artifact belongs to a team (`team_id > 0`), other members of that team can also manage it |
+
+Artifacts you cannot edit only expose read-only actions such as "Copy link" and "Download" — the "Rename" and "Delete" buttons do not appear.
+
+<Note>
+This differs from the automation rule permission model: the account Owner / admins have management access to **any** artifact, including other members' personal artifacts — there is no "no exemption for personal resources" restriction here.
+</Note>
+
+## Related Pages
+
+---
+
+<CardGroup cols={2}>
+  <Card title="Console" icon="comments" href="/en/ai-sre/sessions">
+    Learn how sessions surface files with the present_files tool — the source of every published artifact.
+  </Card>
+  <Card title="Usage Insights" icon="gauge-high" href="/en/ai-sre/insight">
+    The operational insight report generated by `/insight` is itself an artifact, manageable from the gallery like any other.
+  </Card>
+  <Card title="Automations" icon="calendar-clock" href="/en/ai-sre/automations">
+    Reports produced by scheduled automation runs can also be published as artifacts, giving them a permanent home in the gallery.
+  </Card>
+</CardGroup>