docs: auto doc-review — 3-week diff (14H/15M/8L findings) (#91)

* docs: fix stale knowledge subdir claim and add CLI mirror env vars

- knowledge.mdx: update constraint table and @reference syntax to reflect
  subdir support added in safari#142; remove flat-naming statements in
  best-practices section (zh + en)
- cli.mdx: add MIRROR_URL and FLASHDUTY_UPDATE_BASE_URL to installer
  options table (zh + en)

* docs: auto doc-review diff 3 weeks (37 findings)

Author: ysyneu

docs.json

@@ -67,7 +67,8 @@
                   "zh/platform/team-members",
                   "zh/platform/permission-design",
                   "zh/platform/configure-sso",
-                  "zh/platform/audit-log"
+                  "zh/platform/audit-log",
+                  "zh/platform/custom-menu"
                 ]
               },
               {
@@ -210,6 +211,7 @@
                     "pages": [
                       "zh/on-call/integration/alert-integration/alert-sources/standard alert",
                       "zh/on-call/integration/alert-integration/alert-sources/http-pull",
+                      "zh/on-call/integration/alert-integration/alert-sources/db-pull",
                       "zh/on-call/integration/alert-integration/alert-sources/prometheus",
                       "zh/on-call/integration/alert-integration/alert-sources/grafana",
                       "zh/on-call/integration/alert-integration/alert-sources/zabbix",
@@ -1168,7 +1170,8 @@
                   "en/platform/team-members",
                   "en/platform/permission-design",
                   "en/platform/configure-sso",
-                  "en/platform/audit-log"
+                  "en/platform/audit-log",
+                  "en/platform/custom-menu"
                 ]
               },
               {
@@ -1311,6 +1314,7 @@
                     "pages": [
                       "en/on-call/integration/alert-integration/alert-sources/standard alert",
                       "en/on-call/integration/alert-integration/alert-sources/http-pull",
+                      "en/on-call/integration/alert-integration/alert-sources/db-pull",
                       "en/on-call/integration/alert-integration/alert-sources/prometheus",
                       "en/on-call/integration/alert-integration/alert-sources/grafana",
                       "en/on-call/integration/alert-integration/alert-sources/zabbix",

en/ai-sre/environments.mdx

@@ -66,7 +66,7 @@ Go to **`Environments`** in the AI SRE left sidebar to create and connect a self
 
   | Field | Type | Required | Description |
   |---|---|---|---|
-  | Name | String | Yes | A unique name identifying this Environment; must be unique within the account; max 128 characters |
+  | Name | String | No | A unique name identifying this Environment; must be unique within the account; max 128 characters. If left blank, the system auto-fills it with the Runner's **hostname** on the first heartbeat connection (the same GitHub Actions runner auto-naming convention). If the hostname is already taken, the last 4 characters of the Environment ID are appended as a suffix to disambiguate. |
   | Scope | Account / Team | Yes | Account scope is visible to all members in the account; team scope is visible and editable only by members of that team (see [Scope](#scope) below) |
   | Tags | String list | No | Tags used for task routing, comma-separated, e.g. `linux, docker, gpu` |
 
@@ -108,7 +108,7 @@ Go to **`Environments`** in the AI SRE left sidebar to create and connect a self
   </Tabs>
 
   <Note>
-  The `connect-url` is the address the Runner dials into AI SRE (typically `wss://api.flashcat.cloud/safari/environment/ws`). It is injected by the deployment configuration — you do not need to fill it in manually. The onboarding guide already shows a complete, ready-to-copy command.
+  Both the `connect-url` and the install script URL are sourced dynamically from the server-side deployment configuration (`environment.runner.*` in `etc/srv.yml`) and returned by the backend when you create or retrieve an Environment — **nothing is hardcoded in the frontend bundle**. The onboarding guide already shows a complete, ready-to-copy command with the real values pre-filled.
   </Note>
 </Step>
 
@@ -121,7 +121,9 @@ Go to **`Environments`** in the AI SRE left sidebar to create and connect a self
   | Online | The Runner is currently connected with a healthy heartbeat and ready to accept tasks. |
   | Offline | The Runner connected at some point in the past, but its heartbeat has since been lost. |
 
-  Once online, the list also backfills the machine's **machine info** (OS / architecture / hostname), the Runner **version**, and the **last heartbeat** time ("just now", "N minutes ago", "N hours ago", etc.). When a newer version is available, an "Upgrade available" badge appears in the version column — clicking it reopens the onboarding guide so you can run the same command to upgrade.
+  Once online, the list also backfills the machine's **machine info** (OS / architecture / hostname), the Runner **version**, and the **last heartbeat** time ("just now", "N minutes ago", "N hours ago", etc.).
+
+  Runner upgrades are **server-push advertised on every heartbeat**: the backend compares the version the Runner reports against the system-configured `latest_version` using semver. If the Runner is behind, the backend pushes an upgrade notification to the Runner containing the target version, download URL, and SHA256 checksum. The Runner then downloads, verifies, and replaces itself **without any manual intervention**. Runners built from source with a `dev` version string are intentionally excluded from the comparison. When a newer version is available, an **"Upgrade available"** badge appears in the version column. Clicking it reopens the onboarding guide if you need to reinstall or view the install commands manually.
 </Step>
 </Steps>
 

en/ai-sre/im.mdx

@@ -87,14 +87,41 @@ When you open a **war room** for an incident in IM, AI SRE intervenes **automati
 War room auto-diagnosis is bound to the incident context: when the investigation begins, the corresponding `incident_id` is attached to the run so AI SRE can read the incident details, timeline, and recent changes. For details on how incidents / war rooms interact with A2A, see [Agent · Incident & War Room Integration](/en/ai-sre/agents#incident-and-war-room-integration).
 </Note>
 
+## In-session Switch Commands
+
+---
+
+IM sessions have no picker UI like the console, but they support two slash commands that let you **switch bindings mid-conversation** — neither command is available for console sessions, whose environment and team bindings are set at creation and cannot be changed afterwards.
+
+### /env — Switch Runner Environment
+
+Send `/env <runner-name>` to the bot in a group or DM to rebind the current IM session to a different online BYOC runner. The conversation history and context are preserved in full. After the switch, the previous environment's working directory is no longer accessible: files created or modified during the conversation in the old environment are gone, and skill and knowledge files are re-staged in the new environment on demand.
+
+<Note>
+The switch takes effect after the current turn completes and before the next message is processed — it does not interrupt a tool call that is already running. If the target runner is offline or not found, the command returns an error immediately and the binding remains unchanged.
+</Note>
+
+### /scope — Switch Team Scope
+
+Send `/scope <team-name>` (or `/scope personal` to return to personal scope) to rebind the current IM session to a different team without ending the conversation. Team binding is a **usage operation**: any account member can bind a session to any team in the account — this matches the war-room pattern where responders are often not members of the incident's team.
+
+After the switch, AI SRE:
+
+1. Refreshes the memory snapshot for the new team scope (memories from the previous team scope no longer apply to this session).
+2. Queues the new team's knowledge bundle to be mounted and injected into context when the next message is processed.
+
+<Note>
+Knowledge bundles already mounted into this session are not removed — mounts are conversation-scoped, so switching back to a previously-mounted team will not duplicate the mount reminder.
+</Note>
+
 ## Relationship to Console Sessions
 
 ---
 
 Whether you start a session from IM or the console, it's **the same AI SRE**: messages are handled one at a time, with streaming output, automatic context compaction for long conversations, and optional team and environment bindings. The only difference is the entry point —
 
-- **Console**: ask questions one at a time in the **Chat** workspace and view the full tool-call and sub-session panels.
-- **IM**: @mention it in the group where your team already works; findings are posted back to the thread. Great for grabbing a quick analysis at the incident scene, then diving deeper in the console.
+- **Console**: ask questions one at a time in the **Chat** workspace and view the full tool-call and sub-session panels; environment and team bindings are fixed at creation and cannot be changed.
+- **IM**: @mention it in the group where your team already works; findings are posted back to the thread. Use `/env` and `/scope` to switch bindings mid-conversation. Great for grabbing a quick analysis at the incident scene, then diving deeper in the console.
 
 For more about sessions, see [Conversations](/en/ai-sre/sessions).
 

en/ai-sre/mcp.mdx

@@ -39,6 +39,37 @@ In AI SRE, MCP extends an agent's capability from "built-in tools" to "any exter
 **MCP vs. Skills**: MCP provides **the ability to connect external tools**; a Skill provides **the methodology for orchestrating those tools to accomplish a class of tasks**. A Skill can declare which MCP server tool it needs inside `SKILL.md` using `mcp:server/tool` notation. See [Skills](/en/ai-sre/skills) for details.
 </Tip>
 
+## Installing MCP Connectors from the Marketplace
+
+---
+
+Go to **Plugins → MCP** and click **Browse Marketplace** to open the MCP **connector catalog**, where you can browse Flashduty's curated selection of third-party MCP connector templates.
+
+<Steps>
+  <Step title="Open the catalog">
+    Click **Browse Marketplace** on the MCP list page to open a catalog dialog that displays all available connector templates in a card grid. Each card shows the connector name, vendor, transport, authentication mode, and whether a BYOC Runner is required.
+  </Step>
+  <Step title="View details">
+    Click any connector card to see a full description, connection parameter documentation, and a link to the vendor's official docs. Cards for already-installed connectors display a gear icon; clicking it takes you directly to that connector's edit form.
+  </Step>
+  <Step title="Start an install conversation">
+    For connectors not yet installed, click the **Install** button on the card. The system opens a new AI SRE session and injects the connector's template metadata. The agent then guides you through entering the endpoint URL, completing credential authorization, and calls `mcp_load` to verify connectivity — the entire install flow happens **inside the conversation**, not through a one-click write to the database.
+  </Step>
+  <Step title="Confirm the installation">
+    Once the agent verifies connectivity, it writes the connector into the account via the `/safari/mcp/server/create` endpoint. The connector then appears in the MCP list and is marked as "Installed" on the catalog card.
+  </Step>
+</Steps>
+
+<Note>
+The marketplace catalog is **browse-only** — there is no one-click install endpoint. This is intentional: installing a connector must involve credential entry and connectivity verification. Skipping those steps would leave dead connectors in the account that can never actually connect. Conversational install ensures every connector has been validated by a real agent invocation before it is considered ready.
+</Note>
+
+Installed connectors record a `source_template_name` field that points back to the originating template, making it easy to trace the connector's provenance later. If the same template is installed more than once (for example, into different team scopes), each installation creates an independent connector instance.
+
+<Warning>
+Connectors marked **requires Runner** (typically using `stdio` transport) can only be used in environments where you have a BYOC Runner deployed; cloud Sandboxes do not support them. Before installing, confirm your account has a working BYOC Runner configured. See [Environments (BYOC)](/en/ai-sre/environments).
+</Warning>
+
 ## Adding an MCP Server
 
 ---

en/ai-sre/sessions.mdx

@@ -1,7 +1,7 @@
 ---
 title: Console
-description: An AI SRE session holds one complete conversation between you and the agent, including messages, streaming responses, tool calls, and artifacts. This page covers creating and managing sessions, sending messages, previewing artifacts, context compaction, and team binding.
-keywords: ["AI SRE", "session", "chat", "streaming response", "tool call", "Artifacts", "context compaction", "team binding"]
+description: An AI SRE session holds one complete conversation between you and the agent, including messages, streaming responses, tool calls, and artifacts. This page covers creating and managing sessions, sending messages, previewing artifacts, context compaction, team binding, and session data export.
+keywords: ["AI SRE", "session", "chat", "streaming response", "tool call", "Artifacts", "context compaction", "team binding", "export", "NDJSON"]
 sidebarTitle: Console
 ---
 
@@ -193,6 +193,56 @@ Automatic linking between incidents / war rooms and teams is still evolving. You
 
 For the rules governing team scope for resources (account scope vs. team scope, visibility, and edit permissions), see the "Scope" section on each resource page.
 
+## Session entry kind
+
+---
+
+Every session is created with an **entry kind** (`entry_kind`) that identifies which surface produced it. The value is persisted to the database and returned in the create response.
+
+| Value | Source | Notes |
+|---|---|---|
+| `web` | Console | Default; unknown or missing values are automatically normalized to `web` |
+| `im` | IM platform (Feishu / DingTalk / WeCom / Slack) | Set automatically by the IM path; enables **in-place switching** for the session (see below) |
+| `api` | External API call | For programmatic integration scenarios |
+| `automation` | Automated workflow | Sessions triggered by automation tasks |
+
+When calling `POST /safari/session/create`, you may include `entry_kind` in the request body (optional; defaults to `web`). The `entry_kind` cannot be changed after the session is created.
+
+<Note>
+Sessions with `entry_kind=im` support **in-place environment and team switching** — the IM `/env` and `/scope` commands can rebind the session to a different BYOC runner or team scope without discarding the conversation. Console sessions (`web`) have their environment and team fixed at creation time and do not support in-place switching.
+</Note>
+
+## Session data export
+
+---
+
+`POST /safari/session/export` streams all events from a session as **NDJSON** (`application/x-ndjson`), one JSON object per line. This is intended for auditing, archiving, offline analysis, or feeding session data into external systems.
+
+### Request fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `session_id` | string | Yes | ID of the session to export |
+| `include_subagents` | bool | No | When `true`, recursively includes the event streams of all subagent child sessions; defaults to `false` |
+
+### Response format
+
+The response `Content-Type` is `application/x-ndjson`. The **first line is always** a `session_meta` envelope containing the session's metadata; subsequent lines are session events. When `include_subagents=true`, each `subagent_dispatch` line is immediately followed by the complete event stream of the child session, which also begins with its own `session_meta` line.
+
+```
+{"type":"session_meta","session_id":"...","app_name":"..."}   // first line: session metadata
+{"type":"message","..."}                                       // subsequent: event lines (type varies)
+{"type":"subagent_dispatch","child_session_id":"..."}          // subagent dispatch marker
+{"type":"session_meta","session_id":"<child>","..."}           // child session metadata
+{"type":"message","..."}                                       // child session events
+```
+
+<Warning>
+If an error occurs after streaming has already begun, the server cannot switch to a standard JSON error envelope. Instead, a JSON-encoded error object is appended as the final line of the stream. Consumers must inspect this last line to determine whether the stream completed successfully.
+</Warning>
+
+**Permissions**: the export endpoint uses the same access gate as sending messages (`CanChatSession`), meaning the caller must have message-send permission on the session — read-only access is not sufficient.
+
 ## Related Pages
 
 ---

en/ai-sre/skills.mdx

@@ -124,14 +124,25 @@ At upload time, the system automatically validates that: the archive is a valid
 All metadata other than the skill name (description, version, tags, author, tools, etc.) is parsed from `SKILL.md`'s frontmatter and does not need to be entered separately in the form.
 </Note>
 
+### Overwrite upload (Replace)
+
+When you want to replace an existing skill with a new version, the upload endpoint supports two overwrite modes. The UI presents a "Replace" confirmation dialog at the appropriate moment:
+
+| Mode | Trigger | Behavior |
+| --- | --- | --- |
+| **Replace by name** | Upload with `replace=true` and no `skill_id` | Matches an existing skill in the account by the `name` field in the new archive's `SKILL.md` and overwrites its content. The SkillID remains the same, so all existing references (e.g., `/<skill-name>` triggers) continue to work. |
+| **Replace by ID** | Upload with `replace=true` and a `skill_id` | Ignores the `name` field in the zip and directly targets the skill with the specified ID. Use this when you want to overwrite a specific record even if the skill has been renamed. |
+
+Both modes return the updated skill object on success. If the target skill does not exist, a 404 error is returned — neither mode silently creates a new skill. **Without the `replace` parameter (the default), a name collision is rejected outright**; the upload endpoint never implicitly overwrites an existing skill.
+
 ### Create in conversation (skill-creator)
 
 Besides uploading a zip, you can **create and refine skills right inside an AI SRE session**. `skill-creator` is a Flashduty-provided Marketplace skill, pre-installed into your account by default, that exists specifically to "build skills." Trigger it with `/skill-creator` in any session, or just describe what you want in natural language:
 
 - **Create from scratch**: say "help me create a skill for troubleshooting X," or after an investigation, "turn that workflow into a skill." skill-creator clarifies your intent, drafts the `SKILL.md`, optionally sets up test cases and iterates on them, and saves the result as a skill in your account once you're happy.
 - **Rewrite & optimize**: click **"Edit in Chat"** in a skill's detail panel to have skill-creator rewrite that skill; it can also tune the `description` to improve triggering accuracy.
 
-Once the draft is ready, the agent saves it as a skill with one click; if the name conflicts with an existing skill, a "Replace" confirmation appears first.
+Once the draft is ready, the agent saves it as a skill with one click. If the name conflicts with an existing skill, a "Replace" confirmation dialog appears — under the hood this invokes the replace-by-name mode (`replace=true`, no `skill_id`).
 
 <Warning>
 Skill archive size limits: archives saved by the agent in-conversation are capped at **10 MB**; archives uploaded via the web form or file upload in a session are capped at **100 MB**.