copilotkit 4.22.0 → 4.23.1

package/onboarding/prompts/deployment/choose-local.md

@@ -0,0 +1,46 @@
+# Choose local evaluation
+
+This node records the developer's local deployment choice in the onboarding route.
+Use that choice for both new and existing apps throughout this run. Pass it to each
+worker. Do not offer a hosted project later in this run.
+
+Explain these conditions before sign-in:
+
+- The developer supplies Docker with 4 CPUs, 12 GiB RAM, and 40 GiB free storage
+  available for this stack, after other workloads.
+- The CLI installs Threads, Learning, Channels, the dashboard, CLI-approved local sign-in,
+  databases, and persistent object storage. Memory and analytics are excluded.
+- CopilotKit sign-in issues a renewable plan-based license. Local dashboard
+  sign-in is separate. After setup, valid licenses are checked locally.
+- The developer supplies model access. Learning can use compatible app settings,
+  separate settings, or remain configuration incomplete until settings are supplied.
+- Slack and Teams need internet access and a developer-provided public HTTPS endpoint.
+
+Collect a path to the published candidate manifest. There is no selected default.
+Do not substitute an arbitrary chart tag or a checkout build. If no manifest exists,
+report that candidate publication is needed and take the failure path below.
+Never ask the developer to paste credentials into the conversation.
+
+Collect the model choice. For reuse, have the developer place their compatible app
+model settings in a private JSON file with `model`, `provider`, and any needed
+`baseUrl` and `apiKey` fields. Use that file with `--model-config`. Separate settings
+use the same private file format. Deferral uses `--defer-model`.
+
+Record the candidate path and model choice in the plan, but no secret values.
+Create no cluster and change no app files at this step. The developer can still decline sign-in.
+If declined, take the failure path below.
+
+Run `npx --prefer-offline --yes copilotkit@4.23.1 login --json`. Follow the streaming sign-in
+protocol from “Check sign-in” in the start prompt: open the first authentication URL
+once, keep the same process running, and continue only after its completed record.
+Explain that this sign-in obtains the evaluation license, not the local dashboard login.
+On failed or declined sign-in, take the failure path below.
+
+After sign-in completes, continue with
+`npx --prefer-offline --yes copilotkit@4.23.1 onboard read research/gather`.
+Keep the local choice and collected paths in the run's plan and worker context.
+
+## Failure path
+
+If the candidate is missing or sign-in fails or is declined, stop before cluster creation.
+Run `npx --prefer-offline --yes copilotkit@4.23.1 onboard read stopped/run-failed`.

package/onboarding/prompts/deployment/local-evaluation.md

@@ -0,0 +1,71 @@
+# Install and connect the local evaluation
+
+Use this path for the local choice recorded before sign-in. The app directory is now
+known, whether research selected a new starter or an existing app. Keep the app's
+framework and existing code. Do not run the full init command from this graph.
+
+## Approve the app connection
+
+Before changing files, show a short plan with the exact app directory and these writes:
+
+- `.gitignore` and the gitignored `.copilotkit/local.json` stack reference.
+- `.env`: `INTELLIGENCE_API_URL`, `INTELLIGENCE_GATEWAY_WS_URL`,
+  `CPK_INTELLIGENCE_API_KEY`, and `SL_ENABLED`.
+- `.copilotkit/project.json`: the local project selection.
+
+Explain that local setup creates an empty local project. It copies no hosted data.
+Prior connection settings are saved in private CLI state before the app changes.
+`local cancel` restores only settings that still match this setup's writes and reports
+conflicting setting names. It preserves later edits and the stack's data.
+
+Get approval for the local installation and these connection writes. Apply the existing
+protected-path authorization rules to these exact files. Approval for a scaffold alone
+does not authorize replacing an existing app's connection.
+
+## Run the shared installer
+
+From the exact app directory, use the collected candidate and model choice:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 local setup --candidate <manifest.json> --defer-model --json
+```
+
+For supplied model access, replace `--defer-model` with `--model-config <private-file>`.
+Do not print or read the model file into the conversation. Do not install or manage Docker.
+The CLI supplies its pinned Helm and k3d tools and checks the available Docker budget.
+
+On a retry, run `local setup --json` with no new candidate. It uses saved inputs.
+Read blockers and the recorded failed step. Do not delete or recreate a failed stack.
+A copied app needs explicit `--share-stack`. Do not infer sharing from a copied reference.
+
+After setup reports the stack ready, run the approved connection step from that directory:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 local connect --approve-connection --json
+```
+
+Read the local `.copilotkit/project.json` for its project ID and slug. Do not run hosted
+project selection or provision a second app key. The bootstrap already created both.
+Report the dashboard URL. Tell the developer to run `local credentials` themselves for
+the sign-in approval steps. Do not copy its output into the conversation or reports.
+
+## Keep the existing feature proofs
+
+Use the existing Threads round-trip proof against this local project. Verify a real
+message, reply, and saved conversation. Installation readiness alone is not that proof.
+
+Learning needs valid model settings for this installation. A previous local installation
+proves nothing about these settings. If deferred, report “Learning configuration
+incomplete.” No Learning run is required to finish onboarding configuration.
+
+Channels remain incomplete until the existing proof observes a useful reply to a real mention.
+Use the existing approved HTTPS tunnel instructions when inbound traffic needs a public URL.
+The developer supplies and manages the tunnel. Missing ingress or provider credentials
+must not block Threads, the dashboard, or later Learning configuration.
+
+If the developer cancels the connection, run `local cancel --json` from the app directory.
+Report conflict names only. Keep the stack unless deletion is separately confirmed.
+
+Continue with `npx --prefer-offline --yes copilotkit@4.23.1 onboard read credentials/settle-credentials`.
+For this local route, skip the hosted selection-result checks and use the local project
+record. Continue the existing implementation and proof paths against local endpoints.

package/onboarding/prompts/fallback/best-effort.md

@@ -16,7 +16,7 @@ you stop. The friction command follows the telemetry setting the developer alrea
 so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -62,19 +62,19 @@ or frontend, stop onboarding.
 
 Use these rules for every protected-path check in this fallback:
 
-- Run `npx --prefer-offline --yes copilotkit@4.22.0 onboard audit` from the target app directory.
+- Run `npx --prefer-offline --yes copilotkit@4.23.1 onboard audit` from the target app directory.
 - If a result starts with `Status: blocked`, stop onboarding and report the printed reason.
   It proved nothing changed, so do not report a preservation failure.
 - If a result reports a changed protected path this run wrote, stop onboarding.
 - If a result reports a changed env file, this rule replaces the one above, even when this
   run wrote the file. This run asked the developer to place a
   credential there, so take the credential route rather than the external one. Accept it
-  with `npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-credential --path <path>`,
+  with `npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --accept-credential --path <path>`,
   run the audit again, and name it in the closing report. If the command refuses because
   it names a lost variable, stop onboarding.
 - Before any proof subagent runs, a changed path that no Files changed section from this
   run names came from outside the run. Accept it by name with
-  `npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-external --path <path>`, run the
+  `npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --accept-external --path <path>`, run the
   audit again, and name it in the closing report.
 - After a proof subagent runs, a changed path that no Files changed section from this run
   names is unsettled rather than outside the run, because the proof subagent here returns
@@ -133,16 +133,16 @@ that the selected documentation proved an inferred step.
 Record what the proof returned before you complete:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
-When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.22.0 onboard complete`, carrying the
+When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.23.1 onboard complete`, carrying the
 surface-check result the proof subagent returned. Pass exactly one of `--visual-check` or
 `--device-check`, matching this journey's surface:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard complete --visual-check <outcome>
-npx --prefer-offline --yes copilotkit@4.22.0 onboard complete --device-check <outcome>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard complete --visual-check <outcome>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard complete --device-check <outcome>
 ```
 
 `--visual-check` is for a web frontend and takes `performed`, `skipped-no-browser-tool`, or

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

@@ -18,7 +18,7 @@ without exposing secrets.
 Before you spawn the implementation subagent, take the authorized list from the CLI:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.23.1 onboard audit
 ```
 
 From its result, copy the paths under `Authorized to modify:`. A passed or failed audit with
@@ -37,7 +37,7 @@ still go on the record. Name the file and why the work needs it, then end your t
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
 ```
 
 Continue only when the result starts with `Status: passed`. Run the audit again, take the
@@ -49,7 +49,7 @@ feature stop route below.
 After validation and each repair, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.23.1 onboard audit
 ```
 
 Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
@@ -60,7 +60,7 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-external --path <path>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
@@ -73,11 +73,11 @@ Run the audit again after each accepted change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/stop
 ```
 
 If validation cannot pass, or this intent needs a prerequisite the app does not have, use
 the feature stop route above without further changes.
 
 Otherwise run
-`npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/a2ui/proof`.
+`npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/a2ui/proof`.

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

@@ -0,0 +1,72 @@
+# Plan A2UI with the developer
+
+The inspection in `feature/a2ui/start` came back and proved what this intent needs. This
+prompt turns it into a plan, asks the developer to approve it, and records the protected
+paths the plan changes. Do not change project files in this prompt.
+
+## Waits and stops
+
+The rules in `feature/a2ui/start` still hold here.
+
+The approval is a wait for the developer. Before you end your turn to wait, report the
+pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase awaiting-developer
+```
+
+A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
+When the answer arrives, continue from the step that paused. If the developer asks for a
+change, show the changed plan and ask again.
+
+## What this prompt takes from the start
+
+Keep these from `feature/a2ui/start`, and give them to every subagent:
+
+- the protected path list that `onboard protect` printed, and
+- the paths and findings the inspection returned: the CopilotKit runtime, provider, chat
+  surface, agent id, package versions, existing A2UI configuration, development and test
+  commands, and the round trip that `verify` proved.
+
+If you do not hold them, as after `onboard resume` in a new session, get them back before
+you plan. Run `onboard protect` again from the target app directory: on the same run it
+prints the baseline the run already holds.
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect
+```
+
+Then have one read-only subagent repeat the inspection for the findings above, and wait
+for it. It changes no files.
+
+## Plan the change
+
+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 approval as its own question.
+
+The plan must list every protected path it needs to change under `Authorization requested`,
+with one sentence explaining why. Write `None` when it needs none. Authorization covers
+changing a protected path, not removing it, so the plan must not delete, move, or rename
+one.
+
+After approval, record each approved path before implementation:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+```
+
+If an approved path changed after capture and no implementation step has run, add
+`--with-prior-change`. Continue only when every result starts with `Status: passed`. Do not
+authorize a path the approved plan did not list.
+
+Then run `npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/a2ui/implement`.

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

@@ -27,7 +27,7 @@ still go on the record. Name the file and why the fix needs it, then end your tu
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
 ```
 
 Continue only when the result starts with `Status: passed`. Run the audit again, take the
@@ -40,11 +40,11 @@ Report the outcome of each attempt as it ends, before any repair. The command co
 attempts and the repairs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Use `passed` only for a proved A2UI surface, `failed` for an attempted proof that failed,
-and `skipped` when the proof could not run. Then run `npx --prefer-offline --yes copilotkit@4.22.0 onboard audit`.
+and `skipped` when the proof could not run. Then run `npx --prefer-offline --yes copilotkit@4.23.1 onboard audit`.
 Continue only when it starts with `Status: passed`.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -59,9 +59,9 @@ the path and the change the audit reports. Run the audit again after each accept
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/stop
 ```
 
 When the audit passes, run
-`npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/complete` with the actual browser-proof
+`npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/complete` with the actual browser-proof
 outcome.

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

@@ -21,13 +21,13 @@ carry on. Keep a read-only assignment read-only. If no subagent works at all, re
 once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase delegation-unavailable
 ```
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase awaiting-developer
 ```
 
 A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
@@ -37,7 +37,7 @@ If you stop this run, send one short report before you stop. The friction comman
 the telemetry setting the developer already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -51,7 +51,7 @@ one scoped fix, and sends the report itself when no fix is approved.
 Before any subagent or project process runs, capture the developer's existing work:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect
 ```
 
 Keep the exact protected path list it prints and give that list to every subagent. No
@@ -66,48 +66,27 @@ development/test commands. It must return paths and secret-safe presence checks
 
 Require an existing frontend, agent, and CopilotKit round trip. Start only project-owned
 processes when needed, inspect `/info`, and run
-`npx --prefer-offline --yes copilotkit@4.22.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
+`npx --prefer-offline --yes copilotkit@4.23.1 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
 Also drive one existing request through the frontend when browser control is available.
 
 Wait for the inspection subagent to finish. Then report that the inspection came back:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard checkpoint --phase research-returned
+npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase research-returned
 ```
 
 If the inspection did not prove the baseline this intent extends, stop here without
 changing files:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.23.1 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.
-
-The plan must list every protected path it needs to change under `Authorization requested`,
-with one sentence explaining why. Write `None` when it needs none. Authorization covers
-changing a protected path, not removing it, so the plan must not delete, move, or rename
-one.
-
-After approval, record each approved path before implementation:
+When the inspection proved what this intent needs, read the next prompt now, in this turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/a2ui/plan
 ```
 
-If an approved path changed after capture and no implementation step has run, add
-`--with-prior-change`. Continue only when every result starts with `Status: passed`. Do not
-authorize a path the approved plan did not list.
-
-Then run `npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/a2ui/implement`.
+That prompt holds the plan, the developer's approval, and the paths the plan changes.
+Do not write the plan or change project files in this prompt.

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

@@ -19,7 +19,7 @@ On Teams, skip Slack-only tools and the Slack e2e harness. Do not add a CopilotK
 web app to make this run look complete. Do not replace the existing agent.
 
 If repository evidence does not prove an existing valid Intelligence selection, sign in
-yourself with `npx --prefer-offline --yes copilotkit@4.22.0 login --json`: the same single streaming
+yourself with `npx --prefer-offline --yes copilotkit@4.23.1 login --json`: the same single streaming
 session generic onboarding uses. Read its JSON Lines while the process runs. The CLI opens
 the page itself when it can: with `"browser_opened": false` in `action_required`, show the
 developer the clickable URL and ask them to finish sign-in there. If the record carries
@@ -75,7 +75,7 @@ starter to satisfy this rule, and do not report the page that shows it.
 Before you spawn the implementation subagent, take the authorized list from the CLI:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.23.1 onboard audit
 ```
 
 From its result, copy the paths under `Authorized to modify:`. A passed or failed audit with
@@ -94,7 +94,7 @@ still go on the record. Name the file and why the work needs it, then end your t
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
 ```
 
 Continue only when the result starts with `Status: passed`. Run the audit again, take the
@@ -106,7 +106,7 @@ feature stop route below.
 After validation and each repair, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.23.1 onboard audit
 ```
 
 Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
@@ -117,7 +117,7 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-external --path <path>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
@@ -130,17 +130,17 @@ Run the audit again after each accepted change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/stop
 ```
 
 ## Values this run writes, and the one credential the developer supplies
 
-Never ask the developer for `CHANNEL_CODE` or `CPK_INTELLIGENCE_API_KEY`. This run already
-holds both, and writing them is your work, not theirs.
+Never ask the developer for `INTELLIGENCE_CHANNEL_NAME` or `CPK_INTELLIGENCE_API_KEY`. This
+run already holds both, and writing them is your work, not theirs.
 
-`CHANNEL_CODE` is the Channel name `channels add` declared. `.copilotkit/channels.json`
-records the same name. `CPK_INTELLIGENCE_API_KEY` is the project key `project select`
-wrote.
+`INTELLIGENCE_CHANNEL_NAME` is the Channel name `channels add` declared.
+`.copilotkit/channels.json` records the same name. `CPK_INTELLIGENCE_API_KEY` is the project
+key `project select` wrote. These are the names the Channel host reads.
 
 Write both into the environment file the application loads, which is the `.env` of the app
 or runtime directory that reads it. Read the project to find that directory instead of
@@ -148,11 +148,18 @@ defaulting to the repository root, and keep both values in that one file. Carry
 key over only when that file does not already set it, and move the line without displaying
 what it holds.
 
-Check both by name. Never read, print, echo, or log either value, and never put one in a
-report, a command line, or a commit.
+If the folder was empty and this run cloned OpenTag, OpenTag reads the project key as
+`INTELLIGENCE_API_KEY`, not `CPK_INTELLIGENCE_API_KEY`. In that case, write the key under
+both `CPK_INTELLIGENCE_API_KEY` and `INTELLIGENCE_API_KEY`, with the same value. OpenTag also
+requires `AGENT_URL`. Take its line from OpenTag's `.env.example`, which points at the
+bundled agent. The `open-tag` name in OpenTag's `.env.example` is a placeholder. Replace it
+with the Channel name this run declared.
 
-If that file already sets `CHANNEL_CODE` to a different Channel, change nothing. Ask the
-developer which Channel this project serves and wait for their answer.
+Check both by name. Never read, print, echo, or log either value, and never put one
+in a report, a command line, or a commit.
+
+If that file already sets `INTELLIGENCE_CHANNEL_NAME` to a different Channel, change
+nothing. Ask the developer which Channel this project serves and wait for their answer.
 
 The only credential the developer supplies is their model provider key, such as
 `OPENAI_API_KEY`, and the run asks for it once as part of plan approval. Never ask for it
@@ -167,4 +174,4 @@ If validation cannot pass, or this run needs a prerequisite the app does not hav
 the feature stop route above without further changes.
 
 Otherwise run
-`npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/channels/proof`.
+`npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/channels/proof`.

package/onboarding/prompts/feature/channels/plan.md

@@ -0,0 +1,85 @@
+# Plan the managed Channel with the developer
+
+The inspection in `feature/channels/start` came back, and the tools this run needs are
+present. This prompt turns it into a plan, asks the developer to approve it, and records
+the protected paths the plan changes. Do not change project files in this prompt.
+
+## Waits and stops
+
+The rules in `feature/channels/start` still hold here.
+
+The approval is a wait for the developer. Before you end your turn to wait, report the
+pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard checkpoint --phase awaiting-developer
+```
+
+A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
+When the answer arrives, continue from the step that paused. If the developer asks for a
+change, show the changed plan and ask again.
+
+## What this prompt takes from the start
+
+Keep these from `feature/channels/start`, and give them to every subagent:
+
+- the protected path list that `onboard protect` printed,
+- the paths and findings the inspection returned: the target directory, Git state, package
+  manager, Node and Python versions, `uv`, existing agent code, CopilotKit runtime,
+  Channel and Intelligence configuration (presence only), and test and dev commands,
+- the Slack or Teams answer,
+- whether the folder was empty,
+- the docs page or request that named the Channel, and
+- the result of the Node 22, `uv`, and Python check.
+
+If you do not hold them, as after `onboard resume` in a new session, get them back before
+you plan. Run `onboard protect` again from the target app directory: on the same run it
+prints the baseline the run already holds.
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect
+```
+
+Then have one read-only subagent repeat the inspection for the findings above, and wait
+for it. It changes no files. If the Slack or Teams answer is lost, ask it once as its own
+question. That answer stands in for a lost docs page or request. The repeated inspection
+says again whether the folder is empty and which Node, Python, and `uv` versions are
+present.
+
+## Plan the change
+
+Do not run login, select Intelligence, or create a credential until the developer
+approves the plan. Fetch the connect guide for the chosen provider before planning:
+https://docs.copilotkit.ai/slack/connect.md for Slack,
+https://docs.copilotkit.ai/teams/connect.md for Teams.
+Retry it a second way if needed.
+
+For an empty folder, OpenTag runs its own agent on `OPENAI_API_KEY`. State that before the
+plan. Check the target `.env` and the environment for that name. Report presence only, and
+never read, print, or store the value. If it is absent, ask the developer to place it as
+part of the plan approval, not at backend start. Say that the key is never displayed and
+goes only into the project `.env`. Asking for a key the developer already owns is not
+creating a credential.
+
+Show a small plan. For an empty folder, clone OpenTag and do not rewrite it. For an
+existing agent or app, keep that code and wire a managed Channel. Slack or Teams is
+only `channels add <name> --adapter slack|teams`, with the project's directory or package
+name as `<name>`. On Teams, skip Slack-only tools and the Slack e2e harness. Name focused
+tests and a real mention proof on the chosen provider. Ask for approval as its own question.
+
+The plan must list every protected path it needs to change under `Authorization requested`,
+with one sentence explaining why. Write `None` when it needs none. Authorization covers
+changing a protected path, not removing it, so the plan must not delete, move, or rename
+one.
+
+After approval, record each approved path before implementation:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+```
+
+If an approved path changed after capture and no implementation step has run, add
+`--with-prior-change`. Continue only when every result starts with `Status: passed`. Do not
+authorize a path the approved plan did not list.
+
+Then run `npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/channels/implement`.

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

@@ -31,7 +31,7 @@ still go on the record. Name the file and why the fix needs it, then end your tu
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+npx --prefer-offline --yes copilotkit@4.23.1 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
 ```
 
 Continue only when the result starts with `Status: passed`. Run the audit again, take the
@@ -44,11 +44,11 @@ Report the outcome of each attempt as it ends, before any repair. The command co
 attempts and the repairs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.23.1 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Use `passed` only for a proved mention reply, `failed` for an attempted proof that
-failed, and `skipped` when the proof did not run. Then run `npx --prefer-offline --yes copilotkit@4.22.0 onboard audit`.
+failed, and `skipped` when the proof did not run. Then run `npx --prefer-offline --yes copilotkit@4.23.1 onboard audit`.
 Continue only when it starts with `Status: passed`.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -63,11 +63,11 @@ the path and the change the audit reports. Run the audit again after each accept
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/stop
 ```
 
 When the audit passes and the round trip you reported above was `passed`, run
-`npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/complete` and complete with
+`npx --prefer-offline --yes copilotkit@4.23.1 onboard read feature/complete` and complete with
 `--visual-check channels-proof-passed`. The recorded mention and reply are this run's
 proof, so no web app check is missing. Use `--visual-check performed` only when a
 browser drove Slack or Teams web and proved the mention reply. Do not use