docs: reduce default messaging skill context

.changeset/compact-messaging-guidance.md

@@ -0,0 +1,5 @@
+---
+"grok-bot-cli": patch
+---
+
+Reduce the messaging skill's default context by loading bridge administration and diagnostic procedures only when needed.

artifact/skills/talk-to-grok-bot/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: talk-to-grok-bot
-description: Send or read Grok Bot threads via gbot_send/gbot_thread and Codex daemon threads via codex_send/codex_threads. Use when handing off to a named bot/group or posting a status note agents watch — not for work you can finish yourself.
+description: Message Grok Bot, Codex threads, or opted-in local Claude Code channels. Use when handing off to a named bot/group or posting a status note agents watch — not for work you can finish yourself.
 ---
 # Talk to Grok Bot
 
-MCP tools on the `grok-bot` server use the same gateway as the `gbot` CLI.
+The `grok-bot` MCP server and `gbot` CLI share Grok gateway access and local
+Codex/Claude transports.
 
 ## When to load this
 
 - The repo or task names a bot as owner, or you need a decision only that thread holds.
 - You want a short status note in a shared group other agents watch.
 
-Do not ping a bot for work you can finish yourself. Replies are asynchronous — never block a turn waiting.
+Do not ping a bot for work you can finish yourself. Grok replies are asynchronous;
+continue useful work instead of waiting or polling.
 
 ## How
 
@@ -27,89 +29,24 @@ Do not ping a bot for work you can finish yourself. Replies are asynchronous —
    Read `gbot_thread` later, using `after` for a known cursor and `full: true` only
    when entry bodies are needed. `replyMode: manual` explicitly requests this flow.
 
-Automatic routes start a durable background worker that survives the calling tool.
-Use `gbot_bridge_status` to distinguish delivery from execution and return delivery,
-and to inspect gaps, paused routes and pending interactions. Do not resend unknown
-submissions under a new identity. A provided `requestId` safely replays identical
-tracked input; `controlRequestId` is returned independently of the gateway request ID.
-`gbot_bridge_stop` stops a `bindingId`; `worker: true` explicitly stops the process.
-Neither deletes receipts nor interrupts a Codex turn. No login service is installed;
-if the process dies, the next tracked send/start resumes saved routes.
+Never resend an unknown submission under a new identity. Inspect delivery with
+`gbot_bridge_status`. Never infer permission from chat replies or auto-approve a
+Codex/Grok interaction; keep approvals in the owning UI unless the user explicitly
+authorizes a scoped response.
 
-`gbot_codex_respond` is only for an explicit operator response to a current scoped
-interaction. Copy the advertised interactionId, generation, threadId, turnId and
-bindingId/exchangeId. Use one-time `decision: accept|decline|cancel`, or `answersJson`
-with exact question IDs mapped to `{"answers":["answer"]}`. Never auto-approve,
-change session permissions, or respond to an unsupported interaction; use its owning UI.
-
-Bot replies are `send-message` entries; yours are `message` with `role: user`.
-
-Grok-origin approvals are separate from Codex interactions. `gbot_grok_approvals`
-(CLI: `gbot approvals list TARGET`) lists pending auto-review and local-tool cards in
-the latest 200 entries. Linked/tracked routes forward new pending cards as notices;
-their chat answers never authorize an action. After an explicit user decision, use
-`gbot_grok_respond` (CLI: `gbot approvals respond --target TARGET --entry-id ID
---request-id ID --decision accept|decline`). Copy the exact IDs from the current
-card. Accept grants once; persistent grants are unavailable. Responses recheck the
-card before sending; delivery success does not prove execution. Older cards,
-cookie/payment approvals and other unsupported requests require the owning Grok UI.
+Read [bridge administration](references/bridge-administration.md) before starting,
+stopping, diagnosing or answering approvals on a managed bridge, or using direct
+Codex conversation tools. It covers exact approval IDs, idempotent requests, guarded
+steering, CLI output, and host limitations. Ordinary Grok sends need no reference.
 
 List targets with `gbot bots list` / `gbot groups list` when the name is ambiguous.
 
-## CLI automation
-
-The bundled `gbot` and `gbot-install` executables require Node.js 22.19.0 or newer.
-For `gbot send`, `gbot codex status`, and `gbot codex send` with `--json`, read the result
-document from stdout and branch on its `exitCode`, `mode`, `reason`, and `delivery`.
-Framework argument/schema errors use stderr and exit 2. `--json` is reserved before
-`--`; put `--` before flag-like message text.
-
 ## Auth
 
 Same order as `gbot`: `GROK_BOT_GATEWAY_URL` plus `GROK_BOT_GATEWAY_TOKEN`,
 else the Grok Bot app session, else `CURSOR_ACCESS_TOKEN`. `gbot doctor` shows
 which source is present.
 
-## Codex conversation tools
-
-The generated Codex, Cursor, and Claude plugins and portable MCP artifact expose these
-additional tools on the same `grok-bot` MCP server. Codex tools use the local Codex
-app-server control socket; Grok tools use the Grok gateway. Portable MCP artifacts
-must be configured in an MCP-capable host; they are not automatically loaded by the Grok app.
-
-- `codex_threads`: bounded discovery of daemon-managed Codex threads.
-- `codex_send`: submit a message with a correlation envelope. Default delivery is
-  immediate acceptance, which does not mean execution finished. `wait: true` adds
-  bounded execution and final reply fields. An accepted message remains accepted
-  when observation times out or execution fails.
-- `codex_wait`: explicitly observe a known thread/turn and recover its final output.
-- `codex_watch`: diagnostic observation of bounded thread events. It never answers approvals.
-
-Use `expectedCwd` to verify the destination workspace. Busy sends reject by default;
-`whenBusy: queue` needs `GROK_BOT_CODEX_EXPERIMENTAL=1`. Explicit `whenBusy: steer`
-requires `expectedTurnId` and visibly rejects a stale guard without retrying another turn.
-Final replies omit commentary/reasoning; older phase-null agent messages are a fallback
-only after terminal execution. Inspect `reply.truncated` and execution errors for coverage limits.
-
-CLI equivalents are `gbot codex send --wait --timeout-ms 1000 THREAD_ID hello --json`,
-`gbot codex wait --timeout-ms 1000 THREAD_ID TURN_ID --json`, and
-`gbot codex watch --timeout-ms 1000 --max-events 20 THREAD_ID --json`.
-Use framework `--ndjson` for progress. Wait/watch are explicit diagnostics; automatic
-background reply routing uses the managed tools above. `codex_send` with `replyToGrok` or `bindingId` returns its terminal answer automatically; without either it retains the explicit observation flow. Managed routes default to guarded steering; ordinary sends still reject busy work by default.
-
-`gbot codex bridge start/status/stop/respond` provide the same administration controls.
-CLI auto-routing requires explicit `gbot send --reply-mode auto --codex-thread-id ID`.
-`bridge run` is foreground and bounded (`--lifetime-ms`, default/maximum 23 hours).
-The packaged `scripts/gbot-relay.mjs` is the unlimited foreground service entry.
-Grok participation is through its gateway conversation, not an assumed native Grok
-plugin loader or remote MCP tunnel. Never claim a host loaded a plugin from generated
-configuration alone.
-
-Managed Codex return routes reject `expectedTurnId` and legacy `replyTo`/`envelope`
-options before submission; use plain `codex_send` for a caller-selected turn guard.
-An explicit Grok target supplied with `bindingId` must resolve to the binding's
-recipient. A mismatch fails instead of selecting one destination silently.
-
 ## Claude Code channel
 
 `claude_send` sends to a named live Claude Code session on this machine and waits
@@ -121,10 +58,3 @@ retried. Normal Claude tool approvals remain in its session. This does not attac
 to arbitrary Claude Desktop chats or connect a remote Grok runtime to local tools.
 CLI: `gbot claude send NAME "message" --json`.
 
-## Host tool inventory
-
-Codex MCP clients receive Grok messaging and approval tools; truthfully identified
-Grok Bot clients receive Codex messaging and approval tools. Bridge start/status/stop
-remain shared. Cursor and unknown clients retain both sets. Filtering uses negotiated
-client-name prefixes and does not provide authorization. A Grok runtime identifying
-itself as Cursor needs its native MCP identity corrected before this filter applies.

artifact/skills/talk-to-grok-bot/references/bridge-administration.md

@@ -0,0 +1,84 @@
+# Bridge administration and diagnostics
+
+Automatic routes start a durable background worker that survives the calling tool.
+Use `gbot_bridge_status` to distinguish delivery from execution and return delivery,
+and to inspect gaps, paused routes and pending interactions. Do not resend unknown
+submissions under a new identity. A provided `requestId` safely replays identical
+tracked input; `controlRequestId` is returned independently of the gateway request ID.
+`gbot_bridge_stop` stops a `bindingId`; `worker: true` explicitly stops the process.
+Neither deletes receipts nor interrupts a Codex turn. No login service is installed;
+if the process dies, the next tracked send/start resumes saved routes.
+
+`gbot_codex_respond` is only for an explicit operator response to a current scoped
+interaction. Copy the advertised interactionId, generation, threadId, turnId and
+bindingId/exchangeId. Use one-time `decision: accept|decline|cancel`, or `answersJson`
+with exact question IDs mapped to `{"answers":["answer"]}`. Never auto-approve,
+change session permissions, or respond to an unsupported interaction; use its owning UI.
+
+Bot replies are `send-message` entries; yours are `message` with `role: user`.
+
+Grok-origin approvals are separate from Codex interactions. `gbot_grok_approvals`
+(CLI: `gbot approvals list TARGET`) lists pending auto-review and local-tool cards in
+the latest 200 entries. Linked/tracked routes forward new pending cards as notices;
+their chat answers never authorize an action. After an explicit user decision, use
+`gbot_grok_respond` (CLI: `gbot approvals respond --target TARGET --entry-id ID
+--request-id ID --decision accept|decline`). Copy the exact IDs from the current
+card. Accept grants once; persistent grants are unavailable. Responses recheck the
+card before sending; delivery success does not prove execution. Older cards,
+cookie/payment approvals and other unsupported requests require the owning Grok UI.
+
+## Codex conversation tools
+
+The generated Codex, Cursor, and Claude plugins and portable MCP artifact expose these
+additional tools on the same `grok-bot` MCP server. Codex tools use the local Codex
+app-server control socket; Grok tools use the Grok gateway. Portable MCP artifacts
+must be configured in an MCP-capable host; they are not automatically loaded by the Grok app.
+
+- `codex_threads`: bounded discovery of daemon-managed Codex threads.
+- `codex_send`: submit a message with a correlation envelope. Default delivery is
+  immediate acceptance, which does not mean execution finished. `wait: true` adds
+  bounded execution and final reply fields. An accepted message remains accepted
+  when observation times out or execution fails.
+- `codex_wait`: explicitly observe a known thread/turn and recover its final output.
+- `codex_watch`: diagnostic observation of bounded thread events. It never answers approvals.
+
+Use `expectedCwd` to verify the destination workspace. Busy sends reject by default;
+`whenBusy: queue` needs `GROK_BOT_CODEX_EXPERIMENTAL=1`. Explicit `whenBusy: steer`
+requires `expectedTurnId` and visibly rejects a stale guard without retrying another turn.
+Final replies omit commentary/reasoning; older phase-null agent messages are a fallback
+only after terminal execution. Inspect `reply.truncated` and execution errors for coverage limits.
+
+CLI equivalents are `gbot codex send --wait --timeout-ms 1000 THREAD_ID hello --json`,
+`gbot codex wait --timeout-ms 1000 THREAD_ID TURN_ID --json`, and
+`gbot codex watch --timeout-ms 1000 --max-events 20 THREAD_ID --json`.
+Use framework `--ndjson` for progress. Wait/watch are explicit diagnostics; automatic
+background reply routing uses the managed tools above. `codex_send` with `replyToGrok` or `bindingId` returns its terminal answer automatically; without either it retains the explicit observation flow. Managed routes default to guarded steering; ordinary sends still reject busy work by default.
+
+`gbot codex bridge start/status/stop/respond` provide the same administration controls.
+CLI auto-routing requires explicit `gbot send --reply-mode auto --codex-thread-id ID`.
+`bridge run` is foreground and bounded (`--lifetime-ms`, default/maximum 23 hours).
+The packaged `scripts/gbot-relay.mjs` is the unlimited foreground service entry.
+Grok participation is through its gateway conversation, not an assumed native Grok
+plugin loader or remote MCP tunnel. Never claim a host loaded a plugin from generated
+configuration alone.
+
+Managed Codex return routes reject `expectedTurnId` and legacy `replyTo`/`envelope`
+options before submission; use plain `codex_send` for a caller-selected turn guard.
+An explicit Grok target supplied with `bindingId` must resolve to the binding's
+recipient. A mismatch fails instead of selecting one destination silently.
+
+## CLI automation
+
+The bundled `gbot` and `gbot-install` executables require Node.js 22.19.0 or newer.
+For `gbot send`, `gbot codex status`, and `gbot codex send` with `--json`, read the result
+document from stdout and branch on its `exitCode`, `mode`, `reason`, and `delivery`.
+Framework argument/schema errors use stderr and exit 2. `--json` is reserved before
+`--`; put `--` before flag-like message text.
+
+## Host tool inventory
+
+Codex MCP clients receive Grok messaging and approval tools; truthfully identified
+Grok Bot clients receive Codex messaging and approval tools. Bridge start/status/stop
+remain shared. Cursor and unknown clients retain both sets. Filtering uses negotiated
+client-name prefixes and does not provide authorization. A Grok runtime identifying
+itself as Cursor needs its native MCP identity corrected before this filter applies.