Merge pull request #237 from flashcatcloud/doc-review/2026-07-31-033115

docs: sync recent product updates (on-call, SSO, RUM, CLI, AI SRE)

Author: ysyneu

en/ai-sre/knowledge.mdx

@@ -30,7 +30,9 @@ Knowledge Packs are one type of AI SRE resource and follow the same two-level sc
 
 ---
 
-`DUTY.md` is the **table of contents entry point** for the entire Knowledge Pack. It is the catalog itself — the agent reads `DUTY.md` in full, then fetches other files on demand via `@filename` references. The system does not attach a separate file listing alongside `DUTY.md`; the catalog is the body.
+`DUTY.md` is the **table of contents entry point** for the entire Knowledge Pack. It is the catalog itself — the agent reads `DUTY.md` in full, then fetches other files on demand via `@filename` references. As long as `DUTY.md` exists, the system does not attach a separate file listing alongside it; the catalog is the body.
+
+If a scope has knowledge files but no `DUTY.md` yet, that scope is not silently skipped: the system includes a generated, authoritative file index in the session's knowledge manifest, and explicitly instructs the agent to read the indexed files relevant to the task at hand before doing substantive work (when there are only a few files, read them all) — rather than skipping this step and jumping straight to conclusions. Once a `DUTY.md` is created, this generated-index guidance goes away and the "catalog is the body" model resumes.
 
 References use the `@<path>` style, where the path points to another file within the same pack. Subdirectories are supported (e.g., `@runbooks/api-5xx.md`):
 
@@ -86,6 +88,8 @@ Go to the **Knowledges** management page to create, edit, enable/disable, or del
   </Step>
 </Steps>
 
+**Document distillation**: Knowledge files only support the plain-text formats listed in the table above. If you upload a document in a format that can't be stored directly — PDF, Word, Excel, PowerPoint, or HTML — the console notes that the format can't be used by the agent directly and offers a **Go to chat for analysis** entry. Clicking it starts a new AI SRE session with the document carried in as an attachment; the agent reads the document and distills it into a Markdown knowledge file, which is saved into the current Knowledge Pack after your confirmation.
+
 **Reference consistency checks**: when you save a file, any `@reference` pointing to a file that does not exist in the pack returns a non-blocking unresolved-reference warning (the save still completes). When you delete a file that is still referenced by other files, a still-referenced conflict prompt appears first — you can choose to **force delete**.
 
 <Note>
@@ -100,7 +104,7 @@ Knowledge is not all loaded at once — it follows a **catalog-first, expand-on-
 
 <Steps>
   <Step title="Session start: load the catalog">
-    When a session starts, the system loads the current scope's `DUTY.md` into the session (no separate file list attached). Sessions bound to a team load both the account-level and that team's `DUTY.md`; sessions not bound to a team load only the account-level one.
+    When a session starts, the system loads the current scope's `DUTY.md` into the session (no separate file list is attached when `DUTY.md` exists). Sessions bound to a team load both the account-level and that team's `DUTY.md`; sessions not bound to a team load only the account-level one. If a scope has knowledge files but no `DUTY.md` yet, the system instead attaches a generated file index and instructs the agent to read the relevant files before doing substantive work.
   </Step>
   <Step title="Follow references to read files">
     After reading `DUTY.md`, the agent decides which `@references` to expand based on the current incident, then reads the corresponding knowledge file for the specific content.

en/ai-sre/sessions.mdx

@@ -336,6 +336,17 @@ When calling `POST /safari/session/create`, you may include `entry_kind` in the
 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>
 
+## Reply language
+
+---
+
+Every session determines a **reply language** at creation time. The agent replies in that language for the entire session and never switches midway; reopening the session later continues in the same language.
+
+| Entry kind | Where the reply language comes from |
+|---|---|
+| Console (`web`) | Follows the console UI language when the session is created; it is fixed at creation, so switching the UI language afterward does not affect existing sessions |
+| IM / API / automation (`im` / `api` / `automation`) | These entries carry no UI-language signal, so they default to the account's notification language |
+
 ## Session data export
 
 ---

en/developer/cli.mdx

@@ -420,6 +420,8 @@ flashduty safari --help          # AI SRE generated commands
 flashduty alert --help           # Alert-related generated commands
 ```
 
+Time-window parameters on generated commands (`--start-time` / `--end-time`) accept the same human-friendly formats as the curated commands: relative durations (`7d`, `24h` — interpreted as "now minus duration"), `+7d` ("now plus duration", i.e. a future time), `now`, dates and datetimes (such as `2026-05-01` or `2026-05-01 10:00:00`), and unix timestamps in seconds. In addition, `--since` and `--until` are aliases for `--start-time` and `--end-time` respectively and can be used interchangeably; passing both spellings with different values is an error.
+
 ### Utility commands
 
 ```bash

en/on-call/incident/search-view-incident.mdx

@@ -124,8 +124,13 @@ The top of the Timeline tab provides a Markdown comment box that supports:
 
 - Writing notes, troubleshooting memos, or meeting summaries in Markdown syntax
 - Pasting or uploading images directly; screenshots are auto-uploaded and converted into image links
+- Mentioning members with @ in a comment — the mentioned member receives a dedicated personal notification (with the comment content and an incident link, delivered by email and Flashduty App push by default), making it easy to pull the right people into the discussion
 - Appending the published comment as a record on the incident timeline, interleaved with system-generated events for easy retrospection
 
+<Note>
+@mention notifications are dedicated personal notifications and are not affected by notification muting such as snooze or silence rules.
+</Note>
+
 <Tip>
 Posting a comment requires update permission on the incident. If you only have view access, the comment input box does not appear on the details page.
 </Tip>

en/on-call/post-mortem/create-edit-post-mortem.mdx

@@ -34,6 +34,8 @@ Once you open the report, you'll enter an online collaborative editor. If you've
 
 The editor auto-saves your work, so there's no need to manually click save.
 
+When you @mention a member in the report body, the mentioned member receives a personal notification (with an excerpt of the mention and the report details), making it easy to invite the right people to contribute to or review the report.
+
 ### Inserting Images
 
 While editing, you can paste or drag images directly into the editor — monitoring dashboard screenshots, architecture diagrams, or any other key visuals.
@@ -68,6 +70,8 @@ The key metrics panel shows the critical indicators for this incident. You can a
 
 Follow-up items are for recording action items that come out of the review — things like "optimize database connection pool settings" or "add cache circuit breaker". Follow-ups can be edited at any time, whether the report is in draft or published status.
 
+When you add an **Assignee** to a follow-up item, the system sends that member a personal notification prompting them to follow through; removing an assignee does not send a notification.
+
 ## Publishing and Managing
 
 ### Publish a Report

en/platform/configure-sso.mdx

@@ -16,7 +16,7 @@ Flashduty supports Single Sign-On (SSO) via SAML2.0, OIDC, CAS, and LDAP (privat
 | Protocol Type | Select SAML2.0 |
 | Metadata Document | XML document obtained from the identity provider |
 | Field Mapping | Flashduty extracts user email, username, and phone information from the identity provider through mapped fields |
-| Stable User ID Field (`user_id`) | The unique user identifier attribute returned by the identity provider, used to recognize the same member; email or phone changes do not affect recognition. Recommended value: `employee_id`; enter `name_id` to use the NameID (Subject) of the SAML assertion. See [Member Association](#member-association) below |
+| Stable User ID Field (`user_id`) | Optional. The unique user identifier attribute returned by the identity provider, used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `employee_id`; enter `name_id` to use the NameID (Subject) of the SAML assertion. See [Member Association](#member-association) below |
 | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in |
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 | Flashduty Service Provider Info | **Service Provider Metadata** and **Assertion Consumer Service URL** (assertion address for identity provider to call for single sign-on) |
@@ -34,7 +34,7 @@ Flashduty supports Single Sign-On (SSO) via SAML2.0, OIDC, CAS, and LDAP (privat
 | Client ID | Client ID, obtained from identity provider |
 | Client Secret | Client secret, obtained from identity provider |
 | Field Mapping | Flashduty extracts user email, username, and phone information from the identity provider through mapped fields |
-| Stable User ID Field (`user_id`) | The unique user identifier claim used to recognize the same member; email or phone changes do not affect recognition. Recommended value: `sub`. See [Member Association](#member-association) below |
+| Stable User ID Field (`user_id`) | Optional. The unique user identifier claim used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `sub`. See [Member Association](#member-association) below |
 | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in |
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 | Scopes | Specifies the information and functionality permissions the request can access, with support for customization. Defaults to `openid`, `profile`, `email`, `phone`; you can add custom scopes as tags |
@@ -57,7 +57,7 @@ Scopes is a required field. The default values `openid`, `profile`, `email`, `ph
 | CAS Login Path | CAS login path, e.g., `/login` |
 | Skip TLS Check | Optional; when enabled, skips TLS certificate verification, suitable for CAS services using self-signed certificates |
 | Field Mapping | Flashduty extracts user email, username, and phone information from the identity provider through mapped fields |
-| Stable User ID Field (`user_id`) | The unique user identifier used to recognize the same member; email or phone changes do not affect recognition. Recommended value: `principal` (the CAS authenticated username); you can also map it to a returned attribute. See [Member Association](#member-association) below |
+| Stable User ID Field (`user_id`) | Optional. The unique user identifier used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `principal` (the CAS authenticated username); you can also map it to a returned attribute. See [Member Association](#member-association) below |
 | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in |
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 | Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address |
@@ -82,7 +82,7 @@ LDAP single sign-on is only supported in the **private deployment version**.
 | User DN | Defines where to start searching for users, e.g., `ou=people,dc=flashduty,dc=com` |
 | Auth Filter | Custom filter expression for retrieving user DN information, basic form: `(&(mail=%s))`. Note: Opening and closing parentheses are required |
 | Field Mapping | Flashduty extracts user email, username, phone, and Group information from the identity provider through mapped fields. Email is a required mapping field. The Group field defaults to `memberOf` and is used for role and team synchronization |
-| Stable User ID Field (`user_id`) | The unique user identifier attribute used to recognize the same member; email or phone changes do not affect recognition. Recommended value: `uid`; you can also use a stable attribute such as `entryUUID`. See [Member Association](#member-association) below |
+| Stable User ID Field (`user_id`) | Optional. The unique user identifier attribute used to recognize the same member; email or phone changes do not affect recognition. If left empty, members are matched by the email/phone fields below. Recommended value: `uid`; you can also use a stable attribute such as `entryUUID`. See [Member Association](#member-association) below |
 | Create Account on Sign In | Enabled by default; when disabled, members must be invited before they can sign in |
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 
@@ -132,12 +132,12 @@ When using the LDAP protocol, you can automatically synchronize Flashduty roles
 
 ---
 
-During single sign-on, the system associates the user returned by the identity provider with a member of the account. The association method depends on whether the SSO configuration has a **Stable User ID Field** set:
+During single sign-on, the system associates the user returned by the identity provider with a member of the account. The association method depends on whether the SSO configuration has a **Stable User ID Field** set, and this applies to new and existing configurations alike:
 
 | Configuration | Association method |
 | --- | --- |
-| New SSO configuration (stable user ID field configured) | Recognizes the same member by the stable user ID returned by the identity provider; email or phone changes do not affect recognition. If the stable user ID is not yet bound, the system first matches an existing member by email or phone and establishes the stable user ID binding |
-| Existing SSO configuration (no stable user ID field) | Members continue to be associated by email or phone; behavior stays unchanged |
+| Stable User ID Field configured | Recognizes the same member by the stable user ID returned by the identity provider; email or phone changes do not affect recognition. If the stable user ID is not yet bound, the system first matches an existing member by email or phone and establishes the stable user ID binding |
+| Stable User ID Field not configured (left empty) | Members continue to be associated by the mapped email or phone fields below; behavior stays unchanged |
 
 <Warning>
 Make sure the identity provider always returns a stable and unique user ID. A mapping failure (the identity provider does not return the field) will prevent members from signing in.

en/rum/error-tracking/source-mapping.mdx

@@ -109,6 +109,10 @@ Use Flashduty CLI to upload `sourcemap` files to the Flashduty server.
     <ParamField path="Minified Path Prefix" type="string" required>
       Path prefix for minified files (e.g., `/assets`)
     </ParamField>
+
+    <ParamField path="Custom Upload Endpoint" type="string">
+      Only needed for private deployments. On a private deployment the panel pre-fills the intake address issued by the deployment, and you can override it manually (protocol + domain, no path, e.g. `https://rum.example.com`). Leave it empty to upload to Flashcat SaaS.
+    </ParamField>
   </Step>
   <Step title="Execute Upload">
     Run the generated script in the project root directory:
@@ -121,6 +125,10 @@ Use Flashduty CLI to upload `sourcemap` files to the Flashduty server.
       --api-key your-api-key \
       ./dist
     ```
+
+    <Note>
+    For private deployments, prefix the command with the `FLASHCAT_SOURCEMAP_INTAKE_URL` environment variable to upload symbol files to a custom intake, e.g. `FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com flashcat-cli sourcemaps upload ...` (protocol + domain, no path). When unset, uploads go to Flashcat SaaS. Once "Custom Upload Endpoint" is filled in, the panel-generated command includes this variable automatically.
+    </Note>
   </Step>
 </Steps>
 
@@ -377,6 +385,9 @@ iOS apps generate dSYM (Debug Symbol) files during compilation, containing the d
 
     ```bash
     FLASHCAT_API_KEY=your-api-key flashcat-cli dsyms upload ./app.dSYM
+
+    # Optional: custom intake endpoint for private deployments (protocol + domain, no path); defaults to Flashcat SaaS when unset
+    FLASHCAT_API_KEY=your-api-key FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com flashcat-cli dsyms upload ./app.dSYM
     ```
 
     <Tip>