docs(doc-review): 43 documentation fixes from the 2026-09-18 → 2026-09-22 diff audit

[flashduty]

Doc Review — 2026-09-22

Mode: diff (since 2026-09-18T08:02:02Z) · Window: last successful run 2026-09-18T08:02Z → 2026-09-22T08:03Z
Scope: all modules · Findings: 46 total — 0 high, 20 medium, 26 low
Applied: 43 findings, 52 files touched (26 zh/en page pairs) · Not applied: 1 (d001) · Cross-repo follow-ups: 2

Changes

Finding	Severity	Type	Module	Doc	Action
f001	medium	missing_coverage	ai-sre	ai-sre/artifacts.mdx	Added pinning (list column + subsection + card menu + corrected read-only permissions sentence)
f002	medium	stale_content	ai-sre	ai-sre/artifacts.mdx	Rewrote the card preview bullet: real-content thumbnail + type badge on the divider, scope caption line
f003	medium	feature_drift	ai-sre	ai-sre/artifacts.mdx	Split the two publish paths: publish_artifact accepts HTML/Markdown only, console button keeps the wide table
f004	low	missing_coverage	ai-sre	ai-sre/artifacts.mdx	New 更新已发布产物 section: artifact_id + if_revision outcomes table, review states, present_files does not update
f005	low	missing_coverage	ai-sre	ai-sre/artifacts.mdx	Added page-size options (12/24/48) and the mobile read-only detail-page note
f006	medium	missing_coverage	ai-sre	ai-sre/automations.mdx	Added the 相似故障合并分析 switch, its field-table row, the fan-in subsection and corrected the reuse sentence
f007	medium	missing_coverage	ai-sre	ai-sre/automations.mdx	New run-history reason line section (5 codes) + added the missing blocked / 已阻塞 status row
f008	low	missing_coverage	ai-sre	ai-sre/automations.mdx	Merged-run rows: 名称 fallback, joined_session_* fields, row-click target, and the two fan-in limits
f009	medium	missing_coverage	ai-sre	ai-sre/im.mdx	New reply-only delivery + mid-turn progress sections (draft never posted, one-shot correction, waiting reminder)
f010	low	missing_coverage	ai-sre	ai-sre/im.mdx	Note on the reply reading-length budget and the artifact-pointer guidance
f011	medium	missing_coverage	ai-sre	ai-sre/agents.mdx	Added the agent_dispatch environment argument and cross-environment child-session semantics
f012	low	missing_coverage	ai-sre	ai-sre/mcp.mdx	New cross-environment connectors subsection
f013	low	missing_coverage	ai-sre	ai-sre/mcp.mdx	New systems-only-Monitors subsection (plugin catalog rows, monit_available)
f014	low	config_drift	ai-sre	ai-sre/environments.mdx	Added the reserved environment-variable table incl. FLASHDUTY_DOCS_URL
f015	low	missing_coverage	ai-sre	ai-sre/environments.mdx	New child-session environment subsection (read-only bound-environment chip, A2A shows none)
f016	low	missing_coverage	ai-sre	ai-sre/sessions.mdx	Note on session-stream is_error / error_code frames
f017	low	missing_coverage	ai-sre	ai-sre/sessions.mdx	Dispatch reference line now leads with the destination environment
f018	low	missing_coverage	ai-sre	ai-sre/skills.mdx	Added the bundled flashduty-docs skill and made the built-in list explicitly non-closed
f019	medium	missing_coverage	on-call/integration/webhooks	on-call/integration/webhooks/jira-sync.mdx	状态映射 is now per-integration configurable: rewrote the bullet, re-cast the fixed table as the default, fixed 已解决→已关闭
f020	low	missing_coverage	on-call/integration/webhooks	on-call/integration/webhooks/jira-sync.mdx	自定义字段映射 gains the 故障属性 source group (故障 ID / 故障链接)
f021	low	missing_coverage	on-call/integration	on-call/integration/webhooks/alert-webhook.mdx	Note that 自定义请求体 / 值映射 are 故障-Webhook-only
f022	low	missing_coverage	on-call	on-call/integration/webhooks/incident-webhook.mdx	Added assigned_to.effective_person_ids to the AssignedTo table
f023	medium	missing_coverage	platform	platform/pricing.mdx	New 订阅过期后会发生什么 umbrella section (banners table, 10 frozen create entries, renewal recovery)
f024	medium	missing_coverage	on-call	on-call/analytics/insights.mdx	Note: expired subscription, empty board, history intact
f025	medium	missing_coverage	statuspage	on-call/statuspage/statuspage.mdx	Note: the two admission rules on the status-page create page
f026	medium	missing_coverage	platform	platform/team-members.mdx	Added the 邀请成员 expired gate
f027	low	missing_coverage	platform	platform/permission-design.mdx	Data-permission row + Note for channel-exclusive integrations (OR semantics — finding premise corrected)
f028	medium	config_drift	monitors	monitors/data-sources/data-sources.mdx	Rewrote 如何配置: the console DOES offer 负责团队 / 可查询团队; documented both selects and the client-side rule
f029	medium	missing_coverage	monitors	monitors/data-sources/data-sources.mdx	New 只读视图 section (查看数据源 drawer, masked credentials, no detail call)
f030	medium	stale_content	monitors	monitors/data-sources/data-sources.mdx	Deleted the 名称列的反向入口 section — the component is gone from origin/main
f031	low	missing_coverage	monitors	monitors/data-sources/data-sources.mdx	Added 名称列上的授权标签
f032	low	missing_coverage	monitors	monitors/explore/explore.mdx	New 数据源权限与拒绝提示 section with the real denial copy
f033	low	stale_content	on-call/integration/sso	on-call/integration/sso/keycloak.mdx	SSO login test step now says the page defaults to 企业邮箱, with 使用企业域名登录 as the switch
f034	low	missing_coverage	on-call	on-call/quickstart/mobile-app.mdx	Split the App filter row into 故障标题 / 故障 ID and documented the ID matching semantics
f035	low	missing_coverage	rum	rum/others/data-collection.mdx	session_duration now measured from the session's earliest view
f036	medium	stale_content	cli	developer/cli.mdx	340→338 spec operations, 336→334 generated commands
f037	low	missing_coverage	cli	developer/cli.mdx	--data body-only list now includes repositories, with a full repositories paragraph
f038	low	stale_content	go-sdk	on-call/comparison/vs-pagerduty.mdx	CLI cell 336→334 generated API operation commands
f039	medium	missing_coverage	go-sdk	developer/go-sdk.mdx	AlertRuleV2 investigation_targets rework documented as a Note
f040	low	missing_coverage	go-sdk	developer/go-sdk.mdx	MemberNotify response: recipients[] + optional agent_instructions
f041	low	missing_coverage	go-sdk	developer/go-sdk.mdx	Applications repositories field documented
f042	low	stale_content	go-sdk	openapi/api-catalog.mdx	api-catalog export/import note moved to present tense
f043	low	missing_coverage	ai-sre	openapi/api-catalog.mdx	Added gallery/pin + gallery/unpin rows to the 产物 table

Every edit was written from source read at origin/main (or the fc-foundation-app submodule's origin/main). 52 files, 26 zh + 26 en.

Review checklist

• Config field names and defaults match current code — the riskiest numbers were recounted by the automation: oncall_incident_merge_similar defaults on (*bool, nil→true in logic/automation/service.go), and the CLI counts (340→338 spec operations, 336→334 generated) were recounted from go-flashduty/openapi/openapi.en.json paths×methods and flashduty-cli/internal/cli/zz_generated_manifest.go.
• Feature descriptions reflect user-facing behaviour — f013 (Monitors-only catalog rows) and f027 are the most judgement-dependent edits. f027's original premise was falsified during the fix pass: the channel-integration rbac is a 2-element array and Auth.tsx:190 defaults mode='or' with hasPermission using .some(), so it is an or, not an added requirement. The verified semantics were documented instead. f007's suggested wording for blocked was likewise contradicted by code and replaced with what model/automation/tables.go says.
• Tone and style match the rest of the docs — zh written first, en derived. Where the product has no official English string (src/i18n.ts falls back to zh_CN for several new banners), the en page describes the message instead of quoting an invented translation.
• Decide what to do about changelog.mdx — see Not applied.

Cross-repo follow-ups (flashduty-website)

• d002 · medium/missing_coverage · target content/changelog/

  • Surface: a derivative surface (website content), not module docs.
  • Feature / gap: flashduty-website/content/changelog/ holds one dated .mdx + .zh.mdx pair per entry; the newest is 2026-08-11. None of this window's user-facing features (artifact pinning, configurable Jira status mapping, similar-incident fan-in, subscription-expired gate, IM progress replies) has an entry.
  • Suggested action: Add a dated changelog entry (+ .zh.mdx) in flashduty-website covering this release. Not applied here: target_repo is flashduty-website.

• d003 · medium/missing_coverage · target lib/integrations/catalog.ts

  • Surface: a derivative surface (website content), not module docs.
  • Feature / gap: A new alert source (Sumo Logic) is documented on the docs site and registered in fc-datasource, but the marketing integrations catalog lists 74 integrations and Sumo Logic is not among them. The '60+ 原生集成' count claims still hold, so only the catalog row is missing.
  • Suggested action: Add a sumo-logic entry to flashduty-website lib/integrations/catalog.ts (alert-source category) linking to the docs page. Not applied here: target_repo is flashduty-website.

Further follow-ups outside both repos (surfaced by writers; not actionable from a docs PR):

• api-reference/* must be regenerated for the new artifact endpoints (/safari/artifact/gallery/pin, /gallery/unpin): the fc-pgy registry rows exist (artifact:write:pin / artifact:write:unpin) but grep -c gallery/pin api-reference/*.json is 0, so the new 产物 rows carry plain paths instead of links. Owner: api-review.
• The same regeneration is needed for AutomationRunItem.joined_session_id / joined_session_name in api-reference/safari.openapi.*.json.
• A dangling prose string 兼容 POST /monit/rule/import survives in the generated specs (api-reference/monitors.openapi.zh.json:3069, api-reference/openapi.zh.json:2491, en mirrors) and upstream in go-flashduty's AlertRuleExportListResponse description on origin/main. Source-side fix + regeneration.
• fc-foundation-app frontend RESERVED_KEYS (src/Packages/ai-sre/src/utils/envVars.ts) omits FLASHDUTY_DOCS_URL, so a cloud environment template that sets it is rejected only at save time, not in the form.

Mapping warnings

• fc-foundation-app — src/Packages/saas/pages/Dashboard (mapped to the statuspage module)
  the status-page console UI actually lives in src/Packages/saas/pages/StatusPage; pages/Dashboard is the analytics/insights dashboard (on-call module). Verified on origin/main: both directories exist side by side. This stale path routed the on-call dashboard hunks to the statuspage batch and left the real StatusPage changes unreviewed; covered this round by a manual pass.

• flashduty-docs — zh/on-call/quickstart/comparison.mdx (derivative_surfaces.comparison_page)
  the comparison pages live in zh/on-call/comparison/{vs-pagerduty,vs-opsgenie}.mdx and en/on-call/comparison/

• flashduty-docs — .cursor/skills/translate-zh-to-en/glossary.md and .cursor/skills/polish-document/standards.md
  no .cursor/ directory exists; the skills moved to .claude/skills/translate-zh-to-en/ and .claude/skills/polish-document/, plus the root glossary.md

• fc-safari — logic/tool/, logic/middleware/, logic/automation/, logic/artifact/, logic/agent/, logic/task/, logic/share/, logic/marketplace/, model/artifact/, types/
  mapping.yaml's ai-sre module lists only cmd/api + a subset of logic/*; the window touched ~14k lines across fc-safari of which only ~5k were mapped. Five extra batches covered logic/tool, logic/middleware, logic/automation, logic/agent and logic/artifact+model/artifact+logic/share this round, producing 12 findings (im.mdx, automations.mdx, agents.mdx, mcp.mdx, artifacts.mdx). Widen the module's paths.

Not applied

• d001 (docs changelog) — the newest <Update> block is 2026-09-16, so none of this window's user-facing features (artifact pinning, configurable Jira status mapping, similar-incident fan-in, the subscription-expired gate, IM progress replies) appear there. No entry was written: the changelog is dated by release, and whether this window's merges have shipped cannot be established from code on main, so dating an entry would be a guess. A human should decide the grouping and the date.
• zh/en/changelog/changelog.mdx:46 — the 2026-09-16 bullet still says the console data source form has no inputs for 负责团队 / 可查询团队, which FormDrawer.tsx:288-309 now contradicts. Left untouched deliberately: it is a dated historical entry and rewriting it would falsify a past release note. The live reference page (monitors/data-sources/data-sources.mdx) was corrected under f028. The same tension exists at changelog.mdx:464 — 可发布为产物的文件类型不再限于 HTML 与 Markdown holds for the console button but not for the publish_artifact tool after f003.
• sp1-002 (analytics-board AI-governance default question) — dropped as marginal: the mechanism is already documented generically in ai-sre/sessions.mdx; only the entry-page enumeration would change.