Merge pull request #407 from flashcatcloud/doc-review/2026-09-16-081845

docs: daily doc-review 2026-09-16 (31 findings)

Author: ysyneu

en/ai-sre/apps.mdx

@@ -31,7 +31,7 @@ AI SRE sessions run in a **Flashduty cloud sandbox** by default. The sandbox is
 
 ---
 
-Go to **Plugins → Apps**. Apps is the **first and default** tab in the Plugins area — opening Plugins lands you here.
+Go to **Plugins → Apps**. Opening the Plugins area lands on the **Overview** tab by default; Apps is one of its tabs (the tab order is Overview / Apps / Skill / MCP / Agents).
 
 <Note>
 Viewing the Apps tab requires the appropriate permission; without it, the tab is hidden. Authorizing, disconnecting / revoking, and enabling / disabling each require their own action permission — when you lack one, the corresponding button is shown disabled.

en/ai-sre/artifacts.mdx

@@ -60,6 +60,8 @@ The top-right of the list page offers a **Card view / List view** toggle; your c
 
 The **Created at** and **Updated at** columns support header sorting (ascending / descending toggle); sorting is executed server-side, with **Updated at descending** as the default.
 
+Scope, search term, sorting, and page number are all reflected in the page URL (for example `?scope=team&teams=1,2&q=rebuild&page=2`), so copying the address shares or bookmarks a **filtered** list; returning from an artifact's detail page also lands back on the same filters and position instead of resetting to the default view.
+
 ### Artifact cards
 
 Each card shows:

en/ai-sre/automations.mdx

@@ -170,7 +170,7 @@ If you create or update a rule through the API, use these fields:
 
 When a matching event arrives, the system creates a run with `trigger_kind: "oncall_incident"` and passes event context such as `incident_id`, `channel_id`, and `severity` into the session. The same trigger and the same `incident_id` reuse the same run, avoiding duplicate hidden sessions for one incident.
 
-When the run finishes, AI SRE writes one summary comment back to the incident that triggered it: conclusion first, body kept concise, with a link to the full session at the end. The comment travels through the incident's existing notification chain (for example, incident card refreshes and thread replies in IM), so whoever is watching the incident sees the analysis without opening the console. This applies to every rule with the On-call incident trigger enabled — including rules with custom prompts — with no extra configuration.
+When the run finishes, AI SRE writes one summary comment back to the incident that triggered it: conclusion first, body kept concise, with a link to the full session at the end. That write-back record also carries a persistent **Continue conversation** entry, so you can open that session straight from the conclusion on the incident timeline — see [Incident Timeline · AI SRE Action Records](/en/on-call/incident/search-view-incident#ai-sre-action-records). The comment travels through the incident's existing notification chain (for example, incident card refreshes and thread replies in IM), so whoever is watching the incident sees the analysis without opening the console. This applies to every rule with the On-call incident trigger enabled — including rules with custom prompts — with no extra configuration.
 
 ## Run History
 

en/ai-sre/im.mdx

@@ -120,6 +120,21 @@ While any standing task is alive, the IM session's root message stays open (the
 
 Notification rounds follow a silent "no message = no news" semantics: if a notification round has nothing new to deliver, AI SRE closes that round silently — **no placeholder receipt** is posted to the chat, and the monitoring card is not re-posted either. A new message appears in the chat only when there is a real new finding.
 
+## Connections and Authorization
+
+---
+
+When a credential is missing, the console renders inline cards (**"Authorize [resource name] to continue"**, **"Connect [vendor] to continue"** — see [Console](/en/ai-sre/sessions#when-authorization-is-required)). **IM and API channels get no card** — the agent hands the matter to you according to this session's channel, as follows:
+
+| Situation | Behavior on IM / API channels |
+| --- | --- |
+| Your OAuth authorization is missing (`per_user_oauth`) | The agent pastes the authorize link into the chat as a plain message (not a card); open it in a **desktop / PC browser** to complete the authorization, then reply **"已授权"** (or `authorized` in an English session) to continue. Continuing is your explicit action — a successful OAuth callback does not resume the task by itself |
+| Your secret-type credential is missing (`per_user_secret`) | There is no safe way to collect it over IM: the agent simply tells you to open **this same session in the web console** and complete it there. It never asks you to paste the secret into the chat, and never points you at a settings page instead |
+| The whole connection is missing (in the marketplace catalog, not connected in the account) | The agent gives the connect URL (a deep link into the console's plugins page) as a plain link; connect, then reply **"继续"** (or `continue`) to carry on |
+| A shared server's own credentials (environment variables / headers) | Not any of the above: fill them in under **Plugins → MCP** (that server), then tell the agent to retry |
+
+On the automation channel nobody is watching and no reply will ever arrive: the agent does not wait and does not phrase anything as a question — it **records the missing connection or authorization as a blocker** in its final report and delivers whatever the evidence already supports.
+
 ## In-session Switch Commands
 
 ---

en/ai-sre/knowledge.mdx

@@ -71,11 +71,24 @@ After reading `DUTY.md`, the agent decides which `@references` to expand based o
 
 ---
 
-Go to the **Knowledges** management page to create, edit, enable/disable, or delete Knowledge Packs for your account or teams. The list shows each pack's **Name / Scope / Files / Status / Actions**, and a scope filter at the top lets you switch between Shared and Team views.
+Go to the **Knowledges** management page to create, edit, enable/disable, or delete Knowledge Packs for your account or teams. Once packs exist, the list shows each pack's **Name / Scope / Files / Status / Actions**, and a scope filter at the top lets you switch between Shared and Team views.
+
+**First visit (empty state)**: when the current scope has no Knowledge Pack and the account has none at all, the page is taken over by the empty state. It lists five sources that can be drafted automatically — **Code repositories** (services, dependencies, tech stack), **Deployment topology** (environments, clusters, workloads), **Infrastructure** (cloud accounts, databases, middleware), **Changes** (releases and config changes), and **Monitoring** (metrics, logs, alert rules) — each showing how much has already been read from your connected tools and from Flashduty (labels like "N repositories", "N clusters", "N connections", "N in the last 30 days"); a source with nothing yet shows **Connect →**, which jumps to the plugins page to connect it. Below the cards the page notes that unconnected parts are left blank and can be filled in later, and that schedules, escalation rules, and handling records are read straight from Flashduty with no connection needed.
+
+While the empty state owns the page, the only two ways to start a pack are its own buttons:
+
+| Entry | Behavior |
+| --- | --- |
+| **Initialize AI-SRE** | Opens a new AI SRE session and **sends** `/init` immediately: the agent drafts content from those five sources and saves it after confirming each item with you |
+| **Upload existing documents** | Opens a new AI SRE session with `/init` **pre-filled** in the input box (not sent) and the attachment picker open, so you can hand existing documents to the agent for distillation |
+
+**While the empty state owns the page, the 创建 (Create) button in the page header, the scope switcher, and the search box all disappear**: there is nothing to filter over, and a second entry point would only compete with the two buttons in the empty state. Once a pack exists the page returns to its regular layout — **Create** in the top-right corner, the scope filter and search at the top. When you enter within a team scope, the two empty-state entries bind the new session to that selected team.
+
+If you lack account-level edit permission, account scope shows a one-liner — "no account knowledge base yet" — instead of the full empty state; the toolbar stays, so you can switch to a team scope and inspect that team's pack.
 
 <Steps>
   <Step title="Create a Knowledge Pack">
-    Click **Create** in the top-right corner of the page to open the "Create knowledge base" dialog. A Knowledge Pack has no editable name of its own — it's a singleton resource per target (account or team), so the dialog only asks you to choose a **Scope**: Shared or a specific team. To create a team-level pack, you must belong to the target team; Shared-scope creation is limited to the Account Owner or admins. Each target can own only one pack. Accounts and teams that already have a pack remain in the dropdown and are marked as having an existing Knowledge Pack; after you select one, the primary button becomes **Open knowledge base** and opens that pack instead of creating another. Choose a scope without a pack and click **Create** to make one. The console checks again immediately before creation, so if someone else has just created a pack for that scope, it opens the existing pack instead. The console uses the scope (Shared / team name) as the pack's display identifier.
+    Click **Create** in the top-right corner of the page (this button appears only once a pack already exists — see the empty-state note above) to open the "Create knowledge base" dialog. A Knowledge Pack has no editable name of its own — it's a singleton resource per target (account or team), so the dialog only asks you to choose a **Scope**: Shared or a specific team. To create a team-level pack, you must belong to the target team; Shared-scope creation is limited to the Account Owner or admins. Each target can own only one pack. Accounts and teams that already have a pack remain in the dropdown and are marked as having an existing Knowledge Pack; after you select one, the primary button becomes **Open knowledge base** and opens that pack instead of creating another. Choose a scope without a pack and click **Create** to make one. The console checks again immediately before creation, so if someone else has just created a pack for that scope, it opens the existing pack instead. The console uses the scope (Shared / team name) as the pack's display identifier.
   </Step>
   <Step title="Edit Files">
     Click any row in the list to open the inspector. The left panel shows the file tree; the right panel is an inline editor. Click **New File** to enter a filename (e.g., `runbook.md`), or use **Upload** to import a local file. Markdown files support both **Preview** and **Source** views. Click **Save** after editing.