docs: fix documentation deviations from source code

[CyberScrubber]

Summary

• Fixed conversation/ docs (multi-turn, streaming, the-loop) to match actual source code behavior
• Fixed extensibility/ docs (hooks, skills, mcp-protocol) to match actual source code behavior
• Improved Boundary section readability in system-prompt.mdx with better structure and explanation

Test plan

• Review each doc file diff against source code for accuracy
• Verify no broken links or formatting in Mintlify dev server (bun run docs:dev)

Summary by CodeRabbit

• Documentation
  • Improved documentation across system prompt boundaries, multi-turn conversations, streaming behavior with enhanced stall detection, main loop control flow, and Skills lifecycle.
  • Expanded Hook event coverage from 22 to 27 events with detailed JSON output contracts.
  • Updated MCP configuration pipeline and clarified API documentation for QueryEngine and cost tracking.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates documentation across multiple subsystems to reflect implementation details: clarifying boundary removal semantics for dynamic prompts, revising QueryEngine signatures and internal state tracking, replacing the stall detection model with a two-tier approach, rewriting termination and recovery paths, expanding hook event coverage from 22 to 27, updating MCP configuration merging, and refining skill permission layers and field counts.

Changes

Cohort / File(s)	Summary
System Prompt Documentation docs/context/system-prompt.mdx	Clarified that SYSTEM_PROMPT_DYNAMIC_BOUNDARY is removed before API request and used solely for splitting prompts; reformatted boundary insertion section as blockquote callout.
Multi-turn Conversation Logic docs/conversation/multi-turn.mdx	Updated QueryEngine.submitMessage() signature (prompt: string | ContentBlockParam[], options?: { uuid?: string; isMeta?: boolean }), expanded internal state documentation, revised transcript storage path description, replaced TranscriptWriter with Project-based write architecture, and modified StoredCostState type (added lastDuration, made modelUsage optional).
Streaming Implementation docs/conversation/streaming.mdx	Replaced single SSE watchdog model with two-tier approach: passive stall detection (threshold raised from 10s to 30s) and active idle timeout watchdog (default 90s via STREAM_IDLE_TIMEOUT_MS); updated implementation reference from line range to queryStreamRaw() function.
Main Loop Control Flow docs/conversation/the-loop.mdx	Removed hardcoded line references; rewrote termination conditions section (removed "7种终止条件" enumeration, added renamed/reordered paths like aborted_tools, hook_stopped, max_turns); expanded recovery paths with explicit phases (max_output_tokens_escalate, collapse_drain_retry, token_budget_continuation); updated State object documentation.
Hook Events and Execution docs/extensibility/hooks.mdx	Expanded Hook event coverage from 22 to 27 (added Notification, PermissionRequest, SubagentStart, ElicitationResult, PostToolUseFailure, Setup, CwdChanged, FileChanged, WorktreeCreate); refined event-specific JSON contract fields; changed deduplication key from pluginRoot\0command to four-part key including shell and ifCondition.
MCP Protocol Configuration docs/extensibility/mcp-protocol.mdx	Updated getAllMcpConfigs() documentation to indicate support for additional configuration sources (plugin and claude.ai) alongside user/project/local tiers.
Skill Framework docs/extensibility/skills.mdx	Updated parseSkillFrontmatterFields() from extracting 17 to 16 fields; revised permission-checking from four to five layers with remote canonical Skill auto-allow path; expanded SAFE_SKILL_PROPERTIES whitelist from 28 to 30 properties.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• docs: 完善上下文工程核心定义与架构说明文档(docs/context) 补充Provider 系统、Boundary 条件及兼容层说明 #204: Related through SYSTEM_PROMPT_DYNAMIC_BOUNDARY documentation updates and boundary insertion-condition logic clarifications.

Suggested reviewers

• KonghaYao

Poem

📚 Seven scrolls the rabbit did refine,
From streaming stalls to hooks align,
Each boundary cleared, each flow rerouted,
The loop's true path—at last—shouted!
With QueryEngine's signature revised,
Our documentation's now advised. 🐰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main objective: fixing documentation to align with actual source code behavior across multiple docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/conversation/multi-turn.mdx (1)

178-178: Consider replacing the hard-coded $5 warning threshold with a symbol reference.

Line 178 may drift if the threshold changes. Referencing the underlying config/constant name in prose would be safer.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conversation/multi-turn.mdx` at line 178, The docs currently mention a
hard-coded "$5" threshold; update the prose to reference the actual constant
used in the REPL instead of the literal so it won't drift — e.g., mention the
REPL threshold constant used in src/screens/REPL.tsx (the useEffect billing
threshold symbol) or the related config symbol QueryEngineConfig.maxBudgetUsd;
also note that the popup only appears when hasConsoleBillingAccess() is true.
Replace the literal "$5" with the constant/identifier name and a short
explanation that it reflects the REPL billing threshold.

docs/conversation/streaming.mdx (1)

100-107: Consider deduplicating stall-threshold snippets to reduce drift risk.

STALL_THRESHOLD_MS = 30_000 appears in multiple snippets (Line 101 and Line 143). Keeping one canonical snippet and cross-referencing it would be easier to maintain.

Also applies to: 142-144

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conversation/streaming.mdx` around lines 100 - 107, Multiple
documentation snippets repeat the same constant STALL_THRESHOLD_MS, causing
drift risk; consolidate by creating a single canonical definition of
STALL_THRESHOLD_MS (e.g., export from a shared constants module or a single
documented snippet) and update the duplicated snippets (the ones that reference
STALL_THRESHOLD_MS and STREAM_IDLE_TIMEOUT_MS) to reference or import that
canonical symbol instead of redefining it, ensuring all documentation and code
examples use the same source of truth (look for symbols STALL_THRESHOLD_MS and
STREAM_IDLE_TIMEOUT_MS and replace inline duplicates with references to the
canonical constant).

docs/conversation/the-loop.mdx (1)

71-88: Avoid hard-coding source line numbers in termination tables.

Entries like “第 646 行 / 第 1714 行” can go stale quickly and become misleading. Prefer symbol/branch anchors (function + condition) for longer-lived accuracy.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conversation/the-loop.mdx` around lines 71 - 88, The table should not
reference hard-coded source line numbers; replace each “第 N 行” entry with
durable anchors describing the function/branch or condition that triggers the
termination (e.g., "Token count exceeds hard limit in loopTokenCheck()" instead
of "第 646 行", "ImageSizeError / ImageResizeError thrown in image handling code"
for image_error, "callModel() throws unrecoverable exception" for model_error,
"abortController.signal.aborted during streaming" for
aborted_streaming/aborted_tools, "413 prompt_too_long handling in reactive
compact path", "API error handling (rate limit/auth) in model call" for
completed, "stop hook returns preventContinuation in stop hooks" for
stop_hook_prevented/hook_stopped, and "turn counter exceeds maxTurns" for
max_turns) so the doc points to symbols/conditions (callModel,
abortController.signal.aborted, ImageSizeError/ImageResizeError, stop hooks,
maxTurns) rather than line numbers.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/extensibility/hooks.mdx`:
- Line 133: 文档中把 PermissionRequest.decision 描述为 `allow/deny` 是错误的；根据 types
定义（PermissionRequest 和其 decision 字段在 src/types/hooks.ts 中），decision 应为对象形式且其
behavior 值为 "approve" | "block"（并可包含可选 message 字段）。请修正文档表格中对应单元格，改为说明 decision
是一个对象并列出 decision.behavior: "approve" | "block" 及可选 decision.message，引用
PermissionRequest 和 decision.behavior 来定位并替换错误描述。

---

Nitpick comments:
In `@docs/conversation/multi-turn.mdx`:
- Line 178: The docs currently mention a hard-coded "$5" threshold; update the
prose to reference the actual constant used in the REPL instead of the literal
so it won't drift — e.g., mention the REPL threshold constant used in
src/screens/REPL.tsx (the useEffect billing threshold symbol) or the related
config symbol QueryEngineConfig.maxBudgetUsd; also note that the popup only
appears when hasConsoleBillingAccess() is true. Replace the literal "$5" with
the constant/identifier name and a short explanation that it reflects the REPL
billing threshold.

In `@docs/conversation/streaming.mdx`:
- Around line 100-107: Multiple documentation snippets repeat the same constant
STALL_THRESHOLD_MS, causing drift risk; consolidate by creating a single
canonical definition of STALL_THRESHOLD_MS (e.g., export from a shared constants
module or a single documented snippet) and update the duplicated snippets (the
ones that reference STALL_THRESHOLD_MS and STREAM_IDLE_TIMEOUT_MS) to reference
or import that canonical symbol instead of redefining it, ensuring all
documentation and code examples use the same source of truth (look for symbols
STALL_THRESHOLD_MS and STREAM_IDLE_TIMEOUT_MS and replace inline duplicates with
references to the canonical constant).

In `@docs/conversation/the-loop.mdx`:
- Around line 71-88: The table should not reference hard-coded source line
numbers; replace each “第 N 行” entry with durable anchors describing the
function/branch or condition that triggers the termination (e.g., "Token count
exceeds hard limit in loopTokenCheck()" instead of "第 646 行", "ImageSizeError /
ImageResizeError thrown in image handling code" for image_error, "callModel()
throws unrecoverable exception" for model_error, "abortController.signal.aborted
during streaming" for aborted_streaming/aborted_tools, "413 prompt_too_long
handling in reactive compact path", "API error handling (rate limit/auth) in
model call" for completed, "stop hook returns preventContinuation in stop hooks"
for stop_hook_prevented/hook_stopped, and "turn counter exceeds maxTurns" for
max_turns) so the doc points to symbols/conditions (callModel,
abortController.signal.aborted, ImageSizeError/ImageResizeError, stop hooks,
maxTurns) rather than line numbers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 186f6a70-7fa4-4721-9a3a-cc6130580c39

📥 Commits

Reviewing files that changed from the base of the PR and between f17b7c7 and 3c97632.

📒 Files selected for processing (7)

• docs/context/system-prompt.mdx
• docs/conversation/multi-turn.mdx
• docs/conversation/streaming.mdx
• docs/conversation/the-loop.mdx
• docs/extensibility/hooks.mdx
• docs/extensibility/mcp-protocol.mdx
• docs/extensibility/skills.mdx

[coderabbitai]

⚠️ Potential issue | 🟠 Major

PermissionRequest 的决策值写错了

Line 133 把 PermissionRequest.decision 写成了 allow/deny，但 src/types/hooks.ts 中该结构是 decision.behavior: "approve" | "block"（可选 message）。这里会直接误导 Hook 实现方产出错误 JSON。

✏️ Suggested doc fix

-| `PermissionRequest` | `decision`（含 `allow`/`deny` 子字段） | 权限请求的 Hook 决策 |
+| `PermissionRequest` | `decision`（`behavior: approve/block`，可选 `message`） | 权限请求的 Hook 决策 |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| `PermissionRequest` | `decision`（含 `allow`/`deny` 子字段） | 权限请求的 Hook 决策 |
	| `PermissionRequest` | `decision`（`behavior: approve/block`，可选 `message`） | 权限请求的 Hook 决策 |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/extensibility/hooks.mdx` at line 133, 文档中把 PermissionRequest.decision
描述为 `allow/deny` 是错误的；根据 types 定义（PermissionRequest 和其 decision 字段在
src/types/hooks.ts 中），decision 应为对象形式且其 behavior 值为 "approve" | "block"（并可包含可选
message 字段）。请修正文档表格中对应单元格，改为说明 decision 是一个对象并列出 decision.behavior: "approve" |
"block" 及可选 decision.message，引用 PermissionRequest 和 decision.behavior
来定位并替换错误描述。