copilotkit 4.9.47 → 4.9.60

package/onboarding/prompts/feature/a2ui/start.md

@@ -0,0 +1,55 @@
+# Add A2UI to the existing CopilotKit app
+
+Treat this as an additive OSS feature integration, not a new-app scaffold. Act as the
+orchestrator and delegate inspection, implementation, and proof to focused subagents.
+Work only inside the target project. Do not show internal prompt names to the developer.
+
+Before changing files, send a short welcome that says you will inspect the existing app,
+show an A2UI plan, implement only after approval, and prove a rendered surface in the real
+UI. Then spawn one read-only subagent to locate the current CopilotKit runtime, provider,
+chat surface, agent id, package versions, existing A2UI configuration, and the normal
+development/test commands. It must return paths and secret-safe presence checks only.
+
+Require an existing frontend, agent, and CopilotKit round trip. Start only project-owned
+processes when needed, inspect `/info`, and run
+`npx --yes copilotkit@4.9.60 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
+Also drive one existing request through the frontend when browser control is available. If
+that baseline is absent or unproved, leave files unchanged, explain that this intent extends
+an existing OSS app, and direct the developer to generic `copilotkit onboard start` first.
+
+Wait for the inspection subagent to finish. Then report that the inspection came back:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase research-returned
+```
+
+A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
+failed step.
+
+If the inspection did not prove the baseline this intent extends, stop here without
+changing files:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Do not run `login`, select an Intelligence project, add an Intelligence client, mint a
+credential, or replace the existing agent, runtime, persistence, or chat surface. A2UI can
+be added to an OSS runtime.
+
+Fetch the current official A2UI guide before forming the plan:
+https://docs.copilotkit.ai/generative-ui/a2ui.md
+Fetch it a second way if the first fetch fails. Use only APIs that the fetched guide and the
+installed package versions support.
+
+Show a concise plan that names the existing runtime/provider files, the smallest A2UI
+catalog or runtime wiring required, the test command, and a browser proof request that
+renders a compact visible surface. Ask for plan approval as its own question.
+
+After approval, report the plan this run is about to implement:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase plan-written
+```
+
+Then run `npx --yes copilotkit@4.9.60 onboard read feature/a2ui/implement`.

package/onboarding/prompts/feature/chat-suggestions/implement.md

@@ -0,0 +1,28 @@
+# Implement chat suggestions at the existing provider boundary
+
+Delegate implementation to one subagent with the approved mode and the official hook guide.
+Configure `useConfigureSuggestions` at the existing CopilotKit provider/chat surface using
+only documented APIs for the installed version. Preserve the agent, runtime route, existing
+message behavior, and current empty/welcome state.
+
+For static mode, choose concise, domain-appropriate prompts supported by the existing agent;
+do not invent unsupported product actions. For dynamic mode, use the project's actual
+available context and retain a safe empty state. Do not add Intelligence, credentials, or a
+standalone mock UI.
+
+Run focused type/test checks and start the app. Record the changed files and validation.
+When implementation validation passes, report it:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+```
+
+If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
+without further changes:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Otherwise run
+`npx --yes copilotkit@4.9.60 onboard read feature/chat-suggestions/proof`.

package/onboarding/prompts/feature/chat-suggestions/proof.md

@@ -0,0 +1,26 @@
+# Prove a suggestion appears and sends the intended chat message
+
+Delegate proof to a fresh subagent. In the real frontend, reach the configured availability
+state, confirm that the suggestion controls are visible and legible, click one, and require
+the exact configured prompt to travel through the existing CopilotKit runtime to the agent.
+Record the visible suggestion, input sent, response, app URL, and process IDs.
+
+Do not count a static DOM assertion, a hook return value, or a locally rendered pill as
+proof. If the changed files caused a failure, repair it and repeat the interaction. Keep
+project-owned services running.
+
+Report each attempt at the proof as it ends, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+```
+
+Report each repair cycle the same way, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+```
+
+Run
+`npx --yes copilotkit@4.9.60 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>`
+with the real browser-proof outcome.

package/onboarding/prompts/feature/chat-suggestions/start.md

@@ -0,0 +1,46 @@
+# Add chat suggestions to the existing CopilotKit app
+
+Treat this as an additive OSS chat-surface feature. Delegate repository inspection,
+implementation, and proof to separate subagents and keep all work inside the target project.
+
+Before edits, identify the current CopilotKit provider, chat component, message lifecycle,
+agent id, package version, and test/dev commands. Prove the existing OSS round trip with
+`/info`, `npx --yes copilotkit@4.9.60 verify --expect-runtime oss --round-trip --agent <agent-id> --json`,
+and one real frontend request when browser control is available. If there is no proven
+existing CopilotKit chat, leave files unchanged and direct the developer to generic
+onboarding first.
+
+Wait for the inspection subagent to finish. Then report that the inspection came back:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase research-returned
+```
+
+A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
+failed step.
+
+If the inspection did not prove the baseline this intent extends, stop here without
+changing files:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Do not run login, provision Intelligence, request a credential, replace the agent, or alter
+the existing runtime/persistence. Fetch the official hook guide before planning:
+https://docs.copilotkit.ai/reference/hooks/useConfigureSuggestions.md
+Use a second retrieval method if the first fails.
+
+Determine static versus dynamic suggestions from the repository. If the repository does not
+answer it, ask one short question only: recommend static suggestions for a predictable
+first-message experience, or offer dynamic suggestions when the developer needs
+context-dependent follow-ups. Show an approved-plan-sized diff, a focused test, and a proof
+that a visible suggestion submits the intended message.
+
+After approval, report the plan this run is about to implement:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase plan-written
+```
+
+Then run `npx --yes copilotkit@4.9.60 onboard read feature/chat-suggestions/implement`.

package/onboarding/prompts/feature/learning/implement.md

@@ -0,0 +1,106 @@
+# Implement Learning Container assignment without inventing a container
+
+Delegate implementation to one subagent with the approved plan and official guides. Reuse a
+valid existing Intelligence selection. If it is absent, use the documented streaming
+`login --json` session, let the developer select or create the Intelligence project, and
+require the secret-safe project/key provisioning summary before wiring the runtime.
+
+After the project is selected, settle the container from the terminal.
+
+When the plan or the repository already names an id, ask about that one id and nothing else:
+
+```text
+npx --yes copilotkit@4.9.60 learning containers get <id> --json
+```
+
+One call answers it, and no list is needed.
+
+When no id is in hand, survey what the project holds:
+
+```text
+npx --yes copilotkit@4.9.60 learning containers list --json
+```
+
+One call returns at most 500 containers. When `nextCursor` in the result is not null, read
+the next page with `--cursor <nextCursor>` and keep going until it is null. A project whose
+container sits on the second page looks empty to a single call, and the run then adds a
+second container for work the first one already covers.
+
+Report what the read found before asking anyone anything:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase container-surveyed
+```
+
+Everything after this waits on a person, so a run that stops past this point stopped on a
+decision rather than on a read.
+
+Reuse an existing container when one covers the workflow this run is instrumenting, and ask
+the developer which one when more than one could. Otherwise create one.
+
+Default to one container for this project, and name it after the project. Learning needs
+evidence to work with: the first automatic run wants threads from 15 distinct conversations
+in one container, so splitting a new project across several leaves every one of them below
+the line. One container per end user is the same trap and a harder one, because a project
+holds at most 500 and each user's own container then needs 15 conversations from that one
+person. Route per user only when the developer asks for it, and do it in their selector
+rather than in more containers: `getLearningContainerId` receives the resolved application
+user, so the callback can return a different id per tier or per customer.
+
+Use a descriptive lowercase hyphenated id of 1-64 characters:
+
+```text
+npx --yes copilotkit@4.9.60 learning containers create --id <id> --name <name> --json
+```
+
+An id already in use answers `LEARNING_CONTAINER_ALREADY_EXISTS`. That is a container to
+read with `get` and reuse, not a failure to repair and not a reason to pick a new id.
+
+Confirm the id resolves before any file changes, whichever way it was settled. That check is
+the cheap one to keep: a selector wired to an id the platform does not hold returns
+`LEARNING_CONTAINER_NOT_FOUND` on every thread create and every run lock, so a working chat
+breaks on the next message. Stop here if the id does not resolve. Do not write a placeholder
+or a guessed id.
+
+Then report that the container is settled, before any edit:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase container-settled
+```
+
+Everything above happens between two prompts, so a run that stopped on a developer who could
+not choose, on a taken id, or on an id that never resolved would otherwise report the plan
+and then nothing at all.
+
+Add only the documented managed runtime/thread prerequisites and the selected
+`getLearningContainerId` on the `CopilotKitIntelligence` instance. Return the same stable
+1-64 character id for the same thread every time: a thread cannot move after its first
+assignment, and a thread whose agent already ran cannot receive its first assignment
+later. Preserve the existing agent, identity, thread behavior,
+and persistence. 
+
+An Intelligence runtime requires `identifyUser`, and it usually reads a signed-in session
+that a CLI request does not carry. That makes the round trip UNKNOWN and the command exit
+non-zero on an app that is working. Pass what `identifyUser` reads with a repeatable
+`--header "Name: value"`, or record UNKNOWN as the expected result for an auth-gated app.
+It is not a defect to repair.
+
+Run focused tests and
+`npx --yes copilotkit@4.9.60 verify --expect-runtime intelligence --round-trip --agent <agent-id> --json`.
+Repair changed-file failures and record secret-safe evidence.
+
+When implementation validation passes, report it:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+```
+
+If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
+without further changes:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Otherwise run
+`npx --yes copilotkit@4.9.60 onboard read feature/learning/proof`.

package/onboarding/prompts/feature/learning/proof.md

@@ -0,0 +1,45 @@
+# Prove a real run is assigned to the selected Learning Container
+
+Delegate proof to a fresh subagent. In the real authenticated app, create or use a thread,
+send a normal agent request, and confirm the resulting run reached the selected Learning
+Container. Confirm the thread remains associated with the expected user.
+
+One command decides it:
+
+```text
+npx --yes copilotkit@4.9.60 verify --expect-runtime intelligence --round-trip --agent <agent-id> --expect-learning-container <id> --json
+```
+
+It reads the thread back from the platform, so it answers for any runtime mount, and it
+passes only when that thread carries the container this run selected.
+
+Two other signals look like proof and are not. `features.self_learning` is a plan
+entitlement and is already true before any wiring. The `/info` response reports Learning
+from the presence of a callback, not from a single assigned thread. Never report either one
+as evidence.
+
+Do not claim that Insights or Skills are already available: those depend on completed runs
+and later learning processing. Record only the assignment visible now, the request, app URL,
+process IDs, and safe stop commands. Repair changed-file defects and repeat.
+
+Tell the developer what happens next, because a correct run looks like a broken one
+otherwise. Learning runs on its own: the first automatic run needs new threads from 15
+distinct conversations in this container, and only the newest snapshot of each thread
+counts. Threads that already ran before this change are never pulled in, because a thread
+takes its container before its first agent run. So the container starts empty on purpose.
+
+Report each attempt at the proof as it ends, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+```
+
+Report each repair cycle the same way, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+```
+
+Run
+`npx --yes copilotkit@4.9.60 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>`
+with the actual surface outcome.

package/onboarding/prompts/feature/learning/start.md

@@ -0,0 +1,56 @@
+# Add Learning to the existing CopilotKit app
+
+Treat Learning as a managed Intelligence feature that assigns real threads to a chosen
+Learning Container. Orchestrate with separate read-only, implementation, and proof
+subagents. Work only inside the target project and preserve its existing agent and chat.
+
+Before edits, inspect the runtime, agent id, provider/chat, server-side user identity,
+existing Intelligence configuration (presence only), existing thread routes, and the normal
+test/dev commands. Prove the current round trip and inspect `/info`. If the project does not
+already have a CopilotKit app, leave it unchanged and direct the developer to generic
+onboarding.
+
+Wait for the inspection subagent to finish. Then report that the inspection came back:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase research-returned
+```
+
+A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
+failed step.
+
+If the inspection did not prove the baseline this intent extends, stop here without
+changing files:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Fetch the current official guides before planning:
+https://docs.copilotkit.ai/learning.md
+https://docs.copilotkit.ai/backend/copilot-runtime.md
+https://docs.copilotkit.ai/intelligence/connect-your-runtime.md
+https://docs.copilotkit.ai/threads.md
+Use a second retrieval method if needed.
+
+The CLI owns the container. `copilotkit learning containers list --json` reads the ones this
+project already has, and `copilotkit learning containers create --id <id> --name <name>
+--json` makes one. So there is no dashboard step and no reason to guess: never invent an id,
+scrape a dashboard, or treat an arbitrary string as a container.
+
+Read the "Assign Threads to Learning Containers" section of that page. The container is
+chosen by `getLearningContainerId` on the `CopilotKitIntelligence` instance, which the
+same page documents; it receives the resolved application user and the run input, and it
+serves web and Channel runs through one API.
+
+Show a concise plan for managed runtime/thread prerequisites, a stable selected container,
+the documented `getLearningContainerId` selector, validation, and a visible assignment
+proof. Ask for approval separately.
+
+After approval, report the plan this run is about to implement:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase plan-written
+```
+
+Then run `npx --yes copilotkit@4.9.60 onboard read feature/learning/implement`.

package/onboarding/prompts/feature/open-generative-ui/implement.md

@@ -0,0 +1,28 @@
+# Implement Open Generative UI with the existing chat surface
+
+Delegate implementation to one subagent with the approved plan and the fetched official
+guide. Add only the documented Open Generative UI runtime middleware and any documented
+provider wiring the current package versions require. Preserve the existing agent, runtime
+route, persistence, chat surface, and model setup.
+
+Do not introduce Intelligence, a license key, a replacement agent, bespoke iframe HTML, or
+an "unknown tool" placeholder as the success path. Keep sandboxing and existing CSP rules
+intact unless the official guide and observed failure require a minimal documented change.
+
+Run the project's focused validation commands. Start the app and confirm `/info` reports
+`openGenerativeUIEnabled`, while treating that only as capability evidence. Record changed paths and
+validation results without secrets. When implementation validation passes, report it:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+```
+
+If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
+without further changes:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Otherwise run
+`npx --yes copilotkit@4.9.60 onboard read feature/open-generative-ui/proof`.

package/onboarding/prompts/feature/open-generative-ui/proof.md

@@ -0,0 +1,27 @@
+# Prove a generated UI renders safely in the real chat
+
+Delegate proof to a fresh subagent. Use the existing frontend and agent to request a small,
+benign interactive UI such as a greeting card. Require the resulting sandboxed generated UI
+or iframe to render in the conversation and respond to its intended interaction. A capability
+flag, tool-call stream, or "Unknown Tool" fallback is not proof.
+
+Record the request, visible result, app URL, process IDs, and safe stop commands. Keep
+project-owned services running. Repair a failure caused by changed files and prove again;
+do not replace the output with a hard-coded component. If browser control is absent, report
+the missing visual proof honestly.
+
+Report each attempt at the proof as it ends, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+```
+
+Report each repair cycle the same way, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+```
+
+Then run
+`npx --yes copilotkit@4.9.60 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>`
+with the outcome actually observed.

package/onboarding/prompts/feature/open-generative-ui/start.md

@@ -0,0 +1,47 @@
+# Add Open Generative UI to the existing CopilotKit app
+
+Treat this as a focused OSS enhancement. Orchestrate the work with separate read-only,
+implementation, and proof subagents, all restricted to the target project directory.
+
+Before edits, have a research subagent identify the current CopilotKit runtime route,
+provider/chat component, agent id, package versions, existing middleware, sandbox/CSP
+constraints, and normal test/dev commands. Prove the existing app first with `/info`,
+`npx --yes copilotkit@4.9.60 verify --expect-runtime oss --round-trip --agent <agent-id> --json`,
+and a real frontend request when browser control is available. If the app is not an existing
+OSS CopilotKit app with a proven round trip, change nothing and direct the developer to the
+generic onboarding path first.
+
+Wait for the inspection subagent to finish. Then report that the inspection came back:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase research-returned
+```
+
+A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
+failed step.
+
+If the inspection did not prove the baseline this intent extends, stop here without
+changing files:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Do not sign in, select an Intelligence project, create credentials, change the existing
+agent, or swap out the chat surface. Open Generative UI is an OSS runtime feature.
+
+Fetch the current official guide before planning:
+https://docs.copilotkit.ai/generative-ui/open-generative-ui.md
+Retry through a second retrieval method if needed. Setup is the documented
+`openGenerativeUI` option on the runtime, which makes `/info` report
+`openGenerativeUIEnabled`; the middleware is what parses tool-call arguments afterwards.
+Show a small plan covering that runtime option, the existing provider's renderer path,
+likely CSP/sandbox implications, tests, and a user-visible generated UI proof. Ask for approval separately.
+
+After approval, report the plan this run is about to implement:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase plan-written
+```
+
+Then run `npx --yes copilotkit@4.9.60 onboard read feature/open-generative-ui/implement`.

package/onboarding/prompts/feature/realtime-sync/implement.md

@@ -0,0 +1,38 @@
+# Implement managed realtime thread sync with documented endpoints
+
+Delegate implementation to one subagent with the approved plan and fetched guides. If no
+valid Intelligence selection exists, follow the single streaming `login --json` session,
+let the developer select or create a project, and require the secret-safe selection summary
+before wiring it. Reuse a valid selected project instead of creating another one.
+
+Add only the documented Intelligence runtime, stable server-side `identifyUser`, catch-all
+thread routes, and client realtime wiring. Preserve the existing agent, persistence, and
+chat UI. For self-hosted setup, require explicit `apiUrl` and `wsUrl` together; do not infer
+or rewrite either endpoint. For hosted setup, do not add a speculative URL.
+
+An Intelligence runtime requires `identifyUser`, and it usually reads a signed-in session
+that a CLI request does not carry. That makes the round trip UNKNOWN and the command exit
+non-zero on an app that is working. Pass what `identifyUser` reads with a repeatable
+`--header "Name: value"`, or record UNKNOWN as the expected result for an auth-gated app.
+It is not a defect to repair.
+
+Run focused tests and
+`npx --yes copilotkit@4.9.60 verify --expect-runtime intelligence --round-trip --agent <agent-id> --json`.
+Repair changed-file failures and record changed paths and secret-safe validation
+evidence.
+
+When implementation validation passes, report it:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+```
+
+If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
+without further changes:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Otherwise run
+`npx --yes copilotkit@4.9.60 onboard read feature/realtime-sync/proof`.

package/onboarding/prompts/feature/realtime-sync/proof.md

@@ -0,0 +1,28 @@
+# Prove realtime thread changes reach a second active client
+
+Delegate proof to a fresh subagent. Open the same authenticated project/thread in two isolated
+browser contexts. From context A, create or mutate a thread and send a message. Require
+context B to receive the thread/message change without a manual reload. Then exercise a
+second mutation in the reverse direction where the product supports it. Keep the managed
+round-trip verification green.
+
+Record both visible states, actions, timing, app URL, process IDs, and safe stop commands.
+A successful WebSocket connection, a server event, or a refreshed second tab is not proof.
+Repair changed-file defects and repeat. If the environment cannot drive two contexts, report
+the missing proof rather than claiming realtime works.
+
+Report each attempt at the proof as it ends, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+```
+
+Report each repair cycle the same way, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+```
+
+Run
+`npx --yes copilotkit@4.9.60 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>`
+with the actual outcome.

package/onboarding/prompts/feature/realtime-sync/start.md

@@ -0,0 +1,50 @@
+# Add realtime thread sync to the existing CopilotKit app
+
+Treat realtime sync as the Intelligence thread-realtime plane, not as a generic WebSocket
+exercise. Act as the orchestrator and delegate read-only inspection, implementation, and
+two-context proof to subagents within the target project.
+
+Before edits, inspect the current runtime, provider/chat, agent id, authenticated stable user
+identity, thread routes, existing Intelligence configuration (presence only), current websocket
+configuration, and normal test/dev commands. Prove the current frontend-to-runtime-to-agent
+round trip and inspect `/info`. If this is not an existing CopilotKit app, leave files
+unchanged and direct the developer to generic onboarding first.
+
+Wait for the inspection subagent to finish. Then report that the inspection came back:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase research-returned
+```
+
+A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
+failed step.
+
+If the inspection did not prove the baseline this intent extends, stop here without
+changing files:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Fetch the current official guides before planning:
+https://docs.copilotkit.ai/intelligence/connect-your-runtime.md
+https://docs.copilotkit.ai/auth.md
+https://docs.copilotkit.ai/intelligence/threads-explained.md
+https://docs.copilotkit.ai/reference/hooks/useThreads.md
+Retry unavailable pages a second way. Reuse a proven Intelligence project where present; do
+not sign in or select/create one until the developer approves the plan.
+
+The plan must name the documented managed runtime/thread wiring, identity and catch-all
+thread routes, the existing or documented client realtime connection, tests, and a proof in
+two browser contexts. For self-hosted Intelligence, configure `apiUrl` and `wsUrl` together
+from explicit developer-owned values; never derive one from the other. The client prepends
+`/api` itself, so an `apiUrl` that already ends in `/api` produces `/api/api/...`. Hosted setup may not
+need a `wsUrl`. Ask for approval separately.
+
+After approval, report the plan this run is about to implement:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase plan-written
+```
+
+Then run `npx --yes copilotkit@4.9.60 onboard read feature/realtime-sync/implement`.

package/onboarding/prompts/feature/rich-threads/implement.md

@@ -0,0 +1,41 @@
+# Implement Rich Threads with a stable identity and managed runtime
+
+Delegate implementation to one subagent with the approved plan and fetched official guides.
+If repository evidence does not prove an existing valid Intelligence selection, run
+`npx --yes copilotkit@4.9.60 login --json` and follow its single streaming session. Then
+list projects, show the developer the current/recent choices, and select or create one only
+after they choose. Require the secret-safe selection summary to confirm the project file,
+environment file, and key provisioning; never display a key. If existing configuration is
+valid, reuse it rather than minting another project or key.
+
+Add only documented Intelligence runtime wiring, server-side `identifyUser`, and catch-all
+thread routes. Use the existing authenticated user source; if no stable source exists, stop
+and explain that it is a prerequisite. Preserve the agent, existing persistence, and chat
+surface. Add the documented drawer only if the approved plan selected it.
+
+An Intelligence runtime requires `identifyUser`, and it usually reads a signed-in session
+that a CLI request does not carry. That makes the round trip UNKNOWN and the command exit
+non-zero on an app that is working. Pass what `identifyUser` reads with a repeatable
+`--header "Name: value"`, or record UNKNOWN as the expected result for an auth-gated app.
+It is not a defect to repair.
+
+Run focused type/test commands, then start the app and run
+`npx --yes copilotkit@4.9.60 verify --expect-runtime intelligence --round-trip --agent <agent-id> --json`.
+Repair changed-file failures before continuing. Record changed paths and secret-safe
+validation evidence.
+
+When implementation validation passes, report it:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+```
+
+If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
+without further changes:
+
+```text
+npx --yes copilotkit@4.9.60 onboard read feature/stop
+```
+
+Otherwise run
+`npx --yes copilotkit@4.9.60 onboard read feature/rich-threads/proof`.

package/onboarding/prompts/feature/rich-threads/proof.md

@@ -0,0 +1,27 @@
+# Prove Rich Threads persist and reopen for the same user
+
+Delegate proof to a fresh subagent. In the real authenticated frontend, create a conversation,
+send a distinct message, confirm the response, reload or reopen the same thread, and require
+the prior history to remain visible for that same stable user. Confirm the runtime exposes
+the required thread routes and the Intelligence verification remains successful.
+
+Record the interaction, visible persisted history, app URL, process IDs, and safe stop
+commands. Do not count a thread id in a log, a successful API call, or an in-memory history
+as proof. Repair defects caused by changed files and repeat. Keep project-owned servers
+running.
+
+Report each attempt at the proof as it ends, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+```
+
+Report each repair cycle the same way, counting from one:
+
+```text
+npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+```
+
+Then run
+`npx --yes copilotkit@4.9.60 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>`
+with the actual browser outcome.