docs(grok): record production qualification and Cloud setup (#16722)

## Thinking Path

> - Paperclip lets people manage AI agents and their work.
> - Grok Bot uses the shared Runner and an agent MCP connection.
> - The experimental Cloud release now passed real production setup and
work.
> - The setup guide does not list the Cloud opt-in controls or the
observed routine-panel workaround.
> - The readiness plan still describes the production rollout as
pending.
> - This pull request records the release evidence and the supported
setup path.

## Linked Issues or Issue Description

**Issue type**
Outdated documentation and missing setup instructions.

**Where is the issue?**
`doc/grok-bot-agent.md` and
`doc/plans/2026-10-13-grok-bot-production-readiness.md`.

**What's wrong?**
The guide starts after the opt-in step. The plan predates completed
production acceptance and the visibility rollout.

**Suggested fix**
List the three opt-ins and the Agents entry path. Record the exact
tested versions, rollout result and limits. Related runtime work:
[#16394](https://github.com/paperclipai/paperclip/pull/16394),
[#16444](https://github.com/paperclipai/paperclip/pull/16444),
[#16445](https://github.com/paperclipai/paperclip/pull/16445).

## What Changed

- Add the Cloud MCP, Runner and Grok opt-in steps.
- Explain the supported external-agent entry and the Grok Webhook-panel
link workaround.
- Record both tested production versions, assigned and proactive
results, cleanup, the 43-target rollout and a fresh-workspace check.
- Keep the historical failure and evidence limits explicit.

## Verification

- `git diff --check origin/master...HEAD` passed.
- Compared the report with saved production receipts, serving-version
observations, provider image digest, authenticated challenge, download
hashes and cleanup receipts.
- Real assigned work, question/answer, document/file delivery and
proactive work passed on Core
`4415665d67b16ffefbe4519c4bdd521f37bb87b9`.
- Current production source CI passed its required lanes. The collected
non-export checks contain 50 successes, 29 skips and no failures.
- A fresh Cloud workspace exposed the opt-ins, saved them after reload
and offered Grok in the external-agent picker. All test switches were
then restored to off.
- This change edits only Markdown. Runtime typecheck, tests, build,
token and Storybook checks were not rerun locally for this documentation
commit. The plan distinguishes earlier staging recovery proof from
current production tests.

## Risks

Low runtime risk. This change edits no source, schema, workflow or
feature setting. The report qualifies the named versions only. The
first-company model wizard still does not offer external agents. Grok
usage, spending and remote termination remain unknown.

## Model Used

OpenAI Codex, GPT-6 family, with reasoning, repository tools and
browser/native-app testing. The session does not expose the exact
deployed model ID or context-window size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used, including the runtime metadata
that is available
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue in-PR following the relevant issue
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run the applicable local documentation checks and they
pass; runtime tests were not rerun for Markdown-only edits
- [x] I have added or updated tests where applicable; no new tests apply
to these documentation edits
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green (55 passed; two optional
Storybook skips)
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <[email protected]>

doc/grok-bot-agent.md

@@ -5,7 +5,11 @@ apps and persistent context. It is separate from the Grok Build coding runtime.
 Paperclip coordinates tasks through the managed Runner. Grok usage and spending
 are not reported.
 
-From **Agents → New agent → Invite external agent → Grok Bot**, name the agent
+On Cloud, open **Settings → Experimental** and enable **Assistant connections
+(MCP)**, **Paperclip Runner**, and **Grok Bot**. These features are opt-in.
+
+Use **Agents → New agent → Invite external agent → Grok Bot** to set up the Bot.
+The first-company dashboard model wizard does not offer external agents. Name the agent
 and select its role and manager. Follow the connection instructions in Grok Bot.
 Approve the fixed Paperclip company and agent in the browser. Copy the one-use
 pairing code with **Copy code**; enter it only on the authorization page.
@@ -14,7 +18,9 @@ between Bots on that Grok account.
 
 Copy the routine instructions into the Bot's chat. Open its desktop routine's
 Webhook panel and paste the URL and key into Paperclip's secure configuration.
-Use a webhook-only routine with no schedule. **Verify connection** must show both
+If selecting the routine row does not open the panel, ask the Bot for a link to
+that routine's Webhook panel and open the link in Grok Bot. Keep the webhook URL and key
+out of chat. Use a webhook-only routine with no schedule. **Verify connection** must show both
 assignment delivery and an authenticated reply before **Done** becomes available.
 Use **Save & exit** to preserve unfinished setup. See the official
 [routine instructions](https://cursor.com/help/grok-bot/routines).

doc/plans/2026-10-13-grok-bot-production-readiness.md

@@ -1,23 +1,43 @@
 # Grok Bot production readiness
 
-Status as of October 15: a real Bot-initiated repeat passed with one task, one run, seven completed operations, canonical Done, no assignment webhook and successful cleanup on packaged Core ea4aa185. The false file-recovery correction is merged and deployed as Core 5a9e6b63; historical inspection archived the incorrect obligation and fresh verification passed. Further assigned work is blocked by a provider-reported routine-start rate limit. Stop then exposed a separate queue-admission defect: pending work repeatedly allocated a Runner before discovering the connection hold. The qualification agent is paused and all affected leases are cleaned up. Production acceptance remains incomplete.
+Status as of October 18, 12:00 UTC: **ready for the opt-in experimental Cloud release**. Real production setup, assigned work and Bot-initiated work passed. Both work directions also passed after the qualification workspace caught up to the current production release. The visibility campaign succeeded on all 43 targeted active workspaces. A workspace created after the durable policy update showed the opt-ins, saved them through normal Settings and offered Grok in the external-agent picker. Its test switches were returned to off. This is an experimental release, with the limitations below.
 
-## Current production finish line — October 14
+## Current production finish line — October 18
 
-Ship Grok Bot as a user-selectable, opt-in experimental agent in production Paperclip Cloud. A user can connect an existing Bot, assign ordinary tasks and receive questions and useful outputs in Paperclip; the Bot can independently initiate governed work. The user selected a dedicated synthetic Grok Qualification production workspace, which has been created without an agent grant or smoke task.
+Ship Grok Bot as a user-selectable, opt-in experimental agent in production Paperclip Cloud. Users connect an existing Bot, assign ordinary tasks and receive questions and outputs in Paperclip. The Bot can independently initiate governed work. The dedicated synthetic production qualification workspace remains available for inspection.
 
-There is no testing call, case-count, token or spending cap. The former six-case/twenty-webhook limit is withdrawn by the user. Test as needed to meet the finish conditions. Normal company permissions, recorded budgets, admission, delivery reconciliation and resource cleanup remain required; Grok spending is unknown.
+There is no testing call, case-count, token or spending cap. The user withdrew the former six-case/twenty-webhook limit. Normal company permissions, recorded budgets, admission, delivery reconciliation and resource cleanup remain required. Grok spending is unknown.
 
-| Finish condition | Evidence required | Current outcome / next action |
+### Identifiable releases and evidence reuse
+
+- Staging recovery candidate: Core `60e03c002da9451326fdf6abc5d8846a8eb30328`, distribution `cloud-38774569747-1`, image `sha256:47e7782b02e42a42c9f46f7112dfd525c6db49238d3464f006841719f4799459`.
+- Current production release: Core `4415665d67b16ffefbe4519c4bdd521f37bb87b9`, distribution `cloud-39040073985-1`, image `sha256:0e30f965291c81417b5fd2c71498328f4c2a966c7a04c81771910a2b3ccfbe60`.
+- Actual production harness: `467c170a9fc28057734edfc4cb926aeda3b75287`. It already contains the reviewed ingress and opt-in policy. No additional harness deployment was needed.
+- The later shared external Runner extraction changed execution after the staging candidate. Current production was therefore tested with actual assigned and proactive Grok work. Do not describe the earlier controller-restart exercise as a restart test of the later revision.
+- Both qualification and newly provisioned production hosts reported the current Core and private distribution through the serving-version observation. The qualification provider deployment also reported the exact current image digest and SUCCESS.
+
+| Required outcome | Verified evidence | Limits / disposition |
 | --- | --- | --- |
-| Ordinary onboarding works | Actual Grok UI, fixed agent consent, saved setup, wrong-key behavior, authenticated challenge, refresh, reconnect and revocation | Resumed real Grok authorization, saved setup Done, authenticated routine challenge and automatic refresh passed on the October 15 serving revision. Runtime reconnect copy fix is merged; verify its published UI and fresh production setup next. |
-| Assigned work reaches a usable result | One actual managed workflow: progress, question and answer, document, downloaded file/hash, canonical completion or review and cleanup | A preliminary comparison task on serving Core ff0 completed progress → question → answer → report/CSV → canonical Done, with both cleanup receipts. The cited CSV downloads with the exact publication hash. Two distinct CSV uploads accompanied an active-session result wake; correct that wake behavior and requalify the final candidate. |
-| Bot initiates governed work | Real-client task creation/claim/completion with stable receipts and no outbound echo or duplicate effects | A real idle-conversation repeat on packaged Core ea4aa185 created one task and one run, read a public source marker with Grok's own tools, saved its report, reached canonical Done and cleaned up. One acceptance and seven operations completed, with no assignment webhook. The earlier duplicate-wake failure remains historical evidence; its correction passed this repeat. |
-| Recovery and authority are reliable | Healthy work past the prior five-minute failure window; actual controller restart preserving assignment/session/process and no duplicate wake; Stop, pause, reassignment, revocation, stale calls, queues and cleanup | The Core 11d diagnostic survived an actual restart and 13 minutes 44 seconds, then completed and cleaned up. Active Stop denied a real stale mutation. Packaged Core 5a9e6b63 later archived the historical false file hold and stopped an unaccepted session without another file obligation. Queued preparation then churned behind the connection recovery hold; correct that admission gate and repeat the final workflow, restart and active Stop. The original October 14 exit cause remains unproven. |
-| One identifiable reviewed candidate passes source gates | Focused protocol/auth/Runner/UI tests, full CI/typecheck/tests/build/token/Storybook evidence and exact artifacts | Active-session wake correction #16394 merged with 55 passing checks, two optional skips and review 5/5. The proactive echo correction started from master 7fc2dc8b3236e1149ae32756b6153a503623404b and was rebased onto freshly fetched master 250429942e27d568f20d3bc7dddcfc84a666480a before submission. Two regression cases reproduce the real delayed-admission wake before the fix. All 214 focused protocol/auth/question checks pass, including 80 Grok and Dot checks. Repository typecheck/build, token gates, the 2,731-story structure and Storybook build pass. Fresh CI, review, publication and the real no-echo repeat remain required. |
-| Production opt-in is delivered and smoke-tested | Staging acceptance, correct served Core/distribution/Runner, normal editable opt-in controls/defaults, actual production Bot workflow and inspectable task/output links | Cloud opt-in policy and release-guide corrections are merged. Staging Cloud provenance and minimal feature values were verified, with Dot disabled and defaults unchanged. The corrected wake candidate, remaining real-client cases, ordinary production opt-in controls and production smoke are outstanding. |
+| Ordinary onboarding | Fresh production setup through Agents → New agent → Invite external agent → Grok Bot; saved setup recovery, fixed agent consent, separate production connector, webhook-only routine and authenticated challenge. Setup created no work task or Runner lease. | No terminal, configuration edit or credential in chat. Grok's routine row did not open the panel; a link to its Webhook panel worked. The first-company dashboard model wizard is a separate entry path and did not offer Grok. Use Agents for this release. |
+| Assigned work | Original production smoke on Core 60 completed progress, question/answer, a 199-word report and a 1,103-byte CSV with matching downloaded hash. Current Core 441 repeated progress, a governed question wait, a saved answer, continuation, a report and a 166-byte CSV with matching downloaded hash. Both reached accepted Done. | The current task used two normal runs across its durable input wait. Both accepted results are expected. No operator result repair, chat nudge or manual disposition. |
+| Bot-initiated work | Original production smoke on Core 60 created one task/run and a 154-word public-source report. Current Core 441 created one task/run and a 128-word report. Each reached accepted Done with zero outbound assignment webhooks and successful cleanup. | Started from the actual idle Grok conversation. No placeholder task, duplicate dispatch or operator result repair. Native GitHub/web use is provider-reported; a complete provider transcript is unavailable. |
+| Recovery and authority | Core 60 survived an actual same-image controller restart with the same run, session, process, assignment and lease. Work completed after 31 minutes 25.7 seconds without assignment resend. Queued work admitted once after cleanup. Stop fenced authority; the real Grok client received a stale-mutation denial. Inspection and re-verification restored readiness. All 18 observed staging leases cleaned up. | The original October 14 exit remains INCONCLUSIVE because its exit code/signal and provider logs were unavailable. The later healthy run spans that failure window. Protocol/authorization tests cover further races and scope checks; do not label those as real-provider experiments. |
+| Reviewed source gates | The Core 60 queue fix passed review 5/5, 55 checks and two optional skips. Its merged-source CI, image/migrator publication, recursive typecheck, build, 547 focused tests, token gates and Storybook build passed. Current Core 441 canonical CI passed typecheck, build, source suites, Runner protocol/Rust/server and recovery chaos lanes. All 79 non-export check rows were success or skipped. | Earlier full-suite coverage was collected across batches with retries and environment corrections. It was not one aggregate first-attempt pass. No runtime source changed during the final production tests. |
+| Existing production opt-in | Canary-led campaign `fleet-campaign-1792272891888` succeeded on 43/43 targets at 11:48:43 UTC. Durable managed-env policy is version 8. Exactly Grok, MCP and Runner became visible; global feature defaults, tenant choices, release defaults and other operator pins were preserved. The qualification pin was restored to its original fleet-managed state before normal catch-up. | Existing model/runtime pins remain outside this visibility-only rollout. Readiness describes observed contact. The final post-rollout verification received an authenticated reply in 12.588 seconds and created no task, run or lease. |
+| Fresh production opt-in | A newly created workspace served Core 441 and showed the five intended experimental cards, all off. MCP, Runner and Grok could be enabled and persisted after reload. The normal external-agent picker offered Grok. The workspace was left empty with all switches restored to off. | Its initial dashboard model wizard was bypassed with the already-known Settings route for this policy check. This proves provisioning, settings and the agent picker, not Grok onboarding through that wizard. A cold-start capacity notice preceded successful provisioning; creation was not submitted twice. |
+| Production cleanup | Four synthetic production tasks reached Done across five admitted runs. All five managed lease cleanup receipts are successful. Final verification showed zero active work, a ready binding and the same persistent agent grant. | The connected qualification Bot and its webhook-only routine are retained for review. The separate empty onboarding workspace has no agent, grant, routine or managed work. Grok usage/spend and remote process termination remain unknown. |
 
-The critical path is to review and publish the proactive-admission echo correction, verify its served identity, then complete the remaining real-client acceptance cases. The selected staging workspace remains the test destination. Preserve one source manifest per case; do not combine incompatible runs into one green release.
+### Release disposition and user path
+
+The supported path is Settings → Experimental: opt into Assistant connections (MCP), Paperclip Runner and Grok Bot. Then use Agents → New agent → Invite external agent → Grok Bot. The product guide is `doc/grok-bot-agent.md`.
+
+The release remains experimental. Grok retains account-wide plugin access, native apps and persistent context. Paperclip does not report its spending, provide a complete transcript, reset its remote context or guarantee remote process termination. Stop revokes Paperclip work authority and future dispatch. These are declared provider limits.
+
+The current production deployment and final authenticated challenge passed after the visibility restart. Further source revisions require an affected-path review and new evidence where needed; this report does not qualify future master automatically. The dedicated source worktree was created from freshly fetched master `1f27427ffdefaf5fb2760d1d53c0d78cb9683d4c`; the primary checkout's existing changes were left untouched. The staging and production temporary management pins have both been restored to their original fleet-managed state.
+
+## Historical qualification and fixes
+
+The following notes retain failed attempts, earlier candidates and their corrections. Later evidence above supersedes their current-status statements; it does not erase their failures.
 
 Real Grok reconnect restored the same agent, plugin and webhook-only routine. Saved setup reached Done after both delivery and authenticated MCP acknowledgement. After the initial access token expired, Grok refreshed it and acknowledged another challenge without reauthorization. Grok/MCP/Runner were enabled with Dot disabled; setup allocated no managed Runner. The operator used the existing saved-invitation path to get the secure pairing-code copy control before the Runtime copy correction published. Record that as assisted recovery, not proof of unassisted fresh onboarding. The copy correction is merged in #16373 after 55 passing CI checks, two optional skips and review 5/5.