docs(desktop): explain session diagnostic exports

[HuYellow]

Summary

The Trace panel no longer exposes the database path users previously copied for conversation troubleshooting. Add linked English and Chinese guides explaining the recorded removal and how to collect readable Markdown, task-targeted diagnostics, or a portable Session bundle, including each export's limitations.

Refs #4342. The guide establishes the historical change and current workflows; the broader product rationale remains for maintainers to clarify.

Verification

• Cross-checked command labels, shortcuts, export scope, Host targeting, and bundle omissions against the implementation; verified the introduction/removal commits.
• All 16 relative guide links resolve; bilingual content reviewed.
• Passed ASF source-header audit, Windows test inventory, Electron E2E budget, protocol epoch guard, app-shell hook scope, and git diff origin/main...HEAD --check.
• Public script tests on Windows: 231 passed, 3 failed, 1 skipped. The same three failures reproduced on unchanged base 3f297e9aa: the CI workflow comparison test invokes Bash/WSL with incompatible paths, and two Computer Use Lab-root cases depend on POSIX/path or symlink behavior unavailable in this environment.
• CI planner selects code=false, e2e=false, and no workspaces. Application build, typecheck, full application suites, and Desktop UI execution were not run for this documentation-only change.

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex inspected source/history, authored the bilingual documentation, and ran checks. The commit includes Generated-by: OpenAI Codex.

Checklist

• Tests cover the change and fail without it — not applicable to this documentation-only change; source and link checks are listed above.
• Lint, format, typecheck and the affected suites pass locally — application checks are not selected by the docs-only plan; the reproduced baseline test failures are disclosed above.

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Thanks for putting this together — the historical section is the part most docs get wrong, and the #2196 → #3610 narrative checks out. I verified the claims below against the source at the PR base 3f297e9aa. Two things worth fixing before merge.

1. The Trace-panel link goes dead the moment this merges

docs/session-diagnostics.md:95 and docs/session-diagnostics.zh-CN.md:86 link to
../apps/desktop/src/renderer/features/workbar/tools/inspector/session-inspector-panel.tsx.

That path is correct at this PR's base (git cat-file -e 3f297e9aa:... succeeds), but #5345 (0d9ea7576, landed on main after the base) moved the panel to:

apps/desktop/src/renderer/application/contracts/session-inspector/session-inspector-panel.tsx

The old path is deleted on current main, so a merge without a rebase lands a dangling reference. Please update both files when you rebase (the other seven implementation links all still resolve).

2. The diagnostics section under-discloses what the report contains

docs/session-diagnostics.md:66-70 summarises the report as "the Desktop environment, recent main-process logs, and Runtime Host diagnostics when available", then says only "Reports apply secret redaction and home-path shortening. They are not full conversation exports."

Reading apps/desktop/src/main/main-process-diagnostics.ts:444-500, the report actually carries:

• Workspace: <absolute workspace path> (L456) — home-collapsed, not removed, so the user's directory layout is still legible;
• the renderer user-agent string and build commit SHA;
• the full recent main-process log ring (MAIN_PROCESS_DIAGNOSTIC_LOG_MAX_BYTES = 256 * 1024, L45), plus "Recent local Runtime Host process exits";
• a Runtime Host connections block (L470-487) listing each configured Host profile id with readiness, reconnect failure counts and timestamps, and the latest connection error;
• Host pid, uptime, and recent Host logs (L492-501).

Redaction is secret-pattern based (redactSecrets + collapseHomePath, L515-516) — it does not cover arbitrary paths, file names, command text or error payloads that land in a log line.

The Markdown section (L55) and the bundle section (L88) both carry an explicit "review before sharing" / "can still contain private information" warning. The diagnostics section is the one users are most likely to paste into a public issue, and it is the only one of the three without such a note. Suggest mirroring the product's own wording in apps/desktop/src/renderer/locales/settings-preferences-copy.ts:522 ("a home-redacted workspace path") and adding a review-before-posting line. Same for the zh-CN at docs/session-diagnostics.zh-CN.md:60-64.

nits

• The toast's Copy diagnostics is the better tool for a failed request, and the guide doesn't mention it. apps/desktop/src/renderer/app-shell.tsx:224-228 attaches a "Copy diagnostics" action to the error toast with surface: 'toast', which is the only path that appends per-turn execution evidence (appendTurnTrace, main-process-diagnostics.ts:567+: model-call attempts with HTTP status / provider code / provider request id, tool steps, permission decisions, compaction, failure attribution). The palette report the guide documents does not include that. For the "failed request" case the guide explicitly opens with (L62), pointing users at the toast action instead of "the relevant Trace-panel error or screenshot" (L70) would get strictly better evidence.
• zh-CN command labels diverge from the shipped strings. docs/session-diagnostics.zh-CN.md:45-46 uses 保存当前任务为 .md 文件 / 导出当前任务为 Markdown, while the English quotes the exact product labels. There is no zh-CN shell-copy.ts — apps/desktop/src/renderer/locales/shell-copy.ts:677,682 is the only source — so a Chinese-locale user sees the English strings verbatim. Worth keeping the English label in parentheses. Also 导出 ("export") for the clipboard action drifts from the English "Copy"; 复制 matches the behavior better.
• docs/README.md:42 placement. The entry is in Start here, which the maintenance rules at the bottom of that file scope to package/architecture entry points ("Put local architecture beside the code and link it from Start here"). A user-facing Desktop troubleshooting guide reads closer to Frontend and validation, which already holds ../DESIGN.md and windows-support.md, or a new ### Desktop subsection.

Verified as accurate

• runtime.sqlite was a workspace-shared operational-state database, not per-conversation: a956756af (#2196) "the on-disk record file both ledgers live in (runtime.sqlite)"; row label 记录文件. Added 2026-08-08, removed 2026-08-23 by eb2599255 (#3610) — the subject line says "visualize trace composition by color", but the body confirms it removed the panel path plus "the zero-consumer operational state database path from app:info and the preload bridge", matching L29-37.
• Current Trace panel contents (usage, context composition, turn timeline) — session-inspector-panel.tsx overview model and the snapshot.summary / overview.context / overview.composition / timeline sections.
• Command labels and shortcuts: shell-copy.ts:677,682,702 and the ⇧⌘D / Ctrl+Shift+D platformHint; Settings → About → Copy diagnostics at apps/desktop/src/renderer/settings/about-settings-page.tsx:256,263-264.
• Markdown field set and redaction asymmetry: apps/desktop/src/renderer/conversation-markdown.ts header comment and renderConversationMarkdown — thinking / tool_result / token_usage / permission_decision dropped, redactSecrets on assistant text and tool intents, userFacingText left as typed. Both palette actions call the same renderConversationMarkdown over the renderer's in-memory messages (app-shell-command-actions.ts:233,253), so "same representation" and "serialize the messages loaded by the current interface" are both correct.
• Task-targeted resolution and unavailable-Host reporting: resolveManualDiagnosticTarget (app-shell-command-actions.ts:103-118) and the Diagnostics unavailable: … branch (main-process-diagnostics.ts:501).
• Session bundle: .maka-session and Export tasks / Import/export tasks labels (external-session-import-copy.ts:128,132,289; settings-navigation-copy.ts:100); Local-only gating via isLocalTarget and profileKind === 'local' (session-bundle-tasks.tsx:56,80,112); quiescence (requireQuiescent, session-bundle-policy.ts:176) and the subagent-subtree confirm dialog (session-bundle-tasks.tsx:268-274); no credentials and no project directory (session-export.ts:32,145); omitted event types provider_request_captured, model_call_attempt_recorded, model_stream_*, send_diagnostics_recorded (session-bundle-policy.ts:616-623) — matches the L86-88 wording.
• All relative links resolve except the one in finding 1. ASF headers present in both files; .zh-CN.md naming matches the existing docs/*.zh-CN.md convention; no existing doc covers this workflow, so nothing is duplicated.

[me2seeks]

Automated review notice: This comment was posted by an automated review agent operated by me2seeks make. It is not an independent human review and does not replace one.

Summary

Explains session diagnostic exports in a new docs/session-diagnostics.md (+ zh-CN counterpart) and indexes it in docs/README.md. Docs-only, bilingual, label and test green — the test lane's doc-link/locale checks pass on the new pages.

Findings

1. [P3] Confirm the doc's stated export field names and redaction claims match the actual diagnostic-export implementation (the class of stale-reference #5292 fixed); docs that describe privacy boundaries should name the enforcing test if one exists.

Verdict

merge-ready — docs-only addition with bilingual parity; one accuracy spot-check note.

[Astro-Han]

Approved at @Astro-Han's explicit request: a small, focused change with no blocking findings in our automated review of this exact head, and CI is green.