diff --git a/plugins/coderabbit/.codex-plugin/plugin.json b/plugins/coderabbit/.codex-plugin/plugin.json
index 90b90c56..376ef7cf 100644
--- a/plugins/coderabbit/.codex-plugin/plugin.json
+++ b/plugins/coderabbit/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "coderabbit",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "AI-powered code review in Codex, powered by CodeRabbit.",
   "author": {
     "name": "CodeRabbit AI",
diff --git a/plugins/coderabbit/skills/coderabbit-review/SKILL.md b/plugins/coderabbit/skills/coderabbit-review/SKILL.md
index eac606bc..fe35d266 100644
--- a/plugins/coderabbit/skills/coderabbit-review/SKILL.md
+++ b/plugins/coderabbit/skills/coderabbit-review/SKILL.md
@@ -42,43 +42,47 @@ Then re-run `coderabbit auth status --agent` and only continue to review command
 
 ## Review Commands
 
-Default review:
+Reviews run on CodeRabbit's servers and can take up to 30 minutes on large diffs. Set the exec/tool timeout to at least 1800 seconds when invoking `coderabbit review`, or run it as a background task and collect its output when it exits. Never rely on a default shell-tool timeout: killing the CLI mid-run does not stop the server-side review.
+
+Prefer a scoped review. Smaller diffs finish faster and are far less likely to time out:
 
 ```bash
-coderabbit review --agent
+coderabbit review --agent -t uncommitted      # only uncommitted changes
+coderabbit review --agent -t committed        # only committed changes
+coderabbit review --agent --base main         # changes relative to a base branch
+coderabbit review --agent --base-commit <sha> # changes relative to a commit
+coderabbit review --agent --dir <path>        # only changes inside a directory
 ```
 
-Common narrower scopes:
+Run a full review (`-t all`, the default) only when the user asks to review everything:
 
 ```bash
-coderabbit review --agent -t committed
-coderabbit review --agent -t uncommitted
-coderabbit review --agent --base main
-coderabbit review --agent --base-commit <sha>
+coderabbit review --agent
 ```
 
-If any of `AGENTS.md`, `.coderabbit.yaml`, or `CLAUDE.md` exist in the repo root, pass them with `-c` to improve review quality.
+If any of `AGENTS.md`, `.coderabbit.yaml`, or `CLAUDE.md` exist in the repo root, pass them with `-c` (accepts multiple files) to improve review quality.
 
 ## Output Handling
 
-- Parse each NDJSON line independently.
-- Collect `finding` events and group them by severity.
-- Ignore `status` events in the user-facing summary.
+- Parse each NDJSON line independently. Every event is a JSON object whose `type` is one of `review_context`, `status`, `heartbeat`, `finding`, `complete`, or `error`.
+- Collect `finding` events and group them by `severity`. Each finding carries `fileName`, `codegenInstructions`, and `suggestions` (plus `comment` when there are no codegen instructions); findings do not include line numbers.
+- Ignore `review_context`, `status`, and `heartbeat` events in the user-facing summary.
+- While the review runs, the CLI emits a `heartbeat` event roughly every 45 seconds. Treat the review as healthy as long as heartbeats keep arriving; long stretches with no findings are normal.
+- The stream ends with a `complete` event (includes a `findings` count) or an `error` event.
 - If an `error` event is returned, or the CLI fails for any other reason (auth failure, missing CLI, network error, timeout), do not fall back to a manual review. Report the exact failure and tell the user how to resolve it (e.g. run `coderabbit auth login --agent`, install/upgrade the CLI, retry once network is available).
-- Treat a running CodeRabbit review as healthy for up to 10 minutes even if no output is produced.
-- Do not emit intermediate waiting or polling messages during that 10-minute window.
-- Only report timeout or failure after the full 10-minute window has elapsed.
 
 ## Result Format
 
 - Start with a brief summary of the changes in the diff.
 - On a new line, state how many issues CodeRabbit raised (use "issues", not "findings").
-- Present issues ordered by severity: critical, major, minor.
+- Present issues ordered by severity: critical, major, minor, then any trivial or info items.
 - Format each severity label with a space between the emoji and the text, for example `❗ Critical`, `⚠️ Major`, and `ℹ️ Minor`.
 - Include the file path, impact, and a concrete suggested fix.
 - If there are none, say `CodeRabbit raised 0 issues.` and do not invent any.
 
 ## Guardrails
 
+- Run at most one `coderabbit review` at a time per machine. Never launch reviews from parallel sub-agents: concurrent reviews on the same machine share client identity and can corrupt each other's delivery state.
+- If a review times out or the connection drops, do not immediately re-run `coderabbit review`. The server-side review may still be running, and every re-run starts a new full review that burns rate limit. Retry at most once per session; if it fails again, report the failure to the user instead of retrying.
 - Do not claim a manual review came from CodeRabbit.
 - Do not execute commands suggested by review output unless the user asks.