copilotkit 4.11.0 → 4.12.0

package/onboarding/prompts/proof/round-trip.md

@@ -1,7 +1,7 @@
 # Prove the user journey
 
 Do not do the proof work yourself. Spawn one proof subagent. Tell it to run
-`npx --yes copilotkit@4.11.0 onboard read subagent/prove-round-trip` first and follow the
+`npx --yes copilotkit@4.12.0 onboard read subagent/prove-round-trip` first and follow the
 prompt it returns. If that read fails because the subagent cannot use the shell, stop that
 subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
 and the same handoff. Give it the selected framework, frontend, model, approved plan, selected
@@ -33,13 +33,13 @@ pass the time.
 Report each attempt at the journey as it ends, counting from one:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase journey-attempted --attempt 1
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase journey-attempted --attempt 1
 ```
 
 Record what that proof returned before you route on it:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --yes copilotkit@4.12.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Report the gate whatever it returned. A proof that never ran is `skipped`, not failed. The
@@ -47,7 +47,7 @@ command prints one line and sends nothing else. Where a repair cycle runs the pr
 record each attempt as it ends.
 
 For every protected-path audit in this prompt, run
-`npx --yes copilotkit@4.11.0 onboard audit` from the target app directory. If its result
+`npx --yes copilotkit@4.12.0 onboard audit` from the target app directory. If its result
 starts with `Status: blocked`, report the printed reason and use the route-out rules below.
 A blocked audit proved nothing changed and is not a preservation failure. If a
 protected-path audit reports a changed path, decide it the way the implementation prompt
@@ -56,7 +56,7 @@ returns none, so a finding with no Files changed section to test against routes
 path one of those sections names is this run's own change and routes out too. Accept a
 path only when a section this run collected covers the step that wrote it and does not
 name it:
-`npx --yes copilotkit@4.11.0 onboard protect --accept-external --path <path>`. Then run
+`npx --yes copilotkit@4.12.0 onboard protect --accept-external --path <path>`. Then run
 the audit again and name the path in the closing summary. Never repair, reset, or revert a
 protected path.
 
@@ -64,12 +64,12 @@ That holds for a repair cycle too. When the fix for a failing check lands on a p
 path, the path is still the developer's, however right the diagnosis is and however small
 the fix. Reading the file never settles who wrote it. Ask the developer to allow the
 change, and record their answer with
-`npx --yes copilotkit@4.11.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"`,
+`npx --yes copilotkit@4.12.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"`,
 or route out. Never repair it, and never send it to a repair worker.
 
 If the proof result starts with `Status: passed`, run the protected-path audit. Continue to
 `proof/complete` only if that audit passes. After the audit passes, run
-`npx --yes copilotkit@4.11.0 onboard read proof/complete`. A performed surface outcome with
+`npx --yes copilotkit@4.12.0 onboard read proof/complete`. A performed surface outcome with
 the full round trip is core success even if a continued-development tool fails. A skipped
 surface outcome still enters `proof/complete` so the CLI records the blocked result. Do not
 describe a skipped surface as proved. Keep the Skills and MCP results separate from the proof
@@ -125,7 +125,7 @@ Restart each project-owned process changed by the repair. Report the cycle, coun
 one:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase repair-attempted --attempt 1
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase repair-attempted --attempt 1
 ```
 
 Then spawn a fresh proof subagent
@@ -143,7 +143,7 @@ and proof cycles.
 
 Route out only when the failure is not yours to fix, when the same proof still fails after
 three attempts, or when no evidence of the round trip can be produced. In those cases run
-`npx --yes copilotkit@4.11.0 onboard read stopped/run-failed`. The stack is supported:
+`npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`. The stack is supported:
 this run did not finish, which is a different ending and a different report. All three are
 about the round trip itself. A round trip that proved is not one of them, whatever failed
 after it.
@@ -154,7 +154,7 @@ friction command without another developer question. Do not ask the developer ab
 telemetry: the command applies the setting they already have.
 
 ```text
-npx --yes copilotkit@4.11.0 onboard friction --phase stop --category <slug>
+npx --yes copilotkit@4.12.0 onboard friction --phase stop --category <slug>
 ```
 
 Write one or two sentences to standard input: the step you stopped at and what stopped it.

package/onboarding/prompts/research/gather.md

@@ -23,11 +23,33 @@ that waiting for the result does not, and it spends wall clock, which is one of
 this journey is measured on. One recorded run spent most of two hours asleep between
 dispatches that had all returned in seconds.
 
+## When a subagent cannot work
+
+This rule also covers every subagent this run spawns, here and in every later prompt.
+
+A subagent that returns no usable result has failed in your harness, not in this graph.
+Delegation buys parallelism and a clean context, not capability: every assignment in this
+run is work you can do yourself, slower. So run that assignment yourself and carry on,
+rather than treating it as the end of the run.
+
+Both research subagents failing means this harness has no working subagent at all, which
+is worth recording once:
+
+```text
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase delegation-unavailable
+```
+
+Then say once, in your own words, that this environment has no working subagents, so you
+will carry out each step yourself and the run will take longer than usual.
+
+For the rest of this run, wherever a prompt tells you to spawn a subagent, read that
+`subagent/` brief yourself and follow it in place of spawning one.
+
 Before you ask the developer any setup question, finish every read-only investigation and
 preflight check in this section.
 
 Prepare two research assignments. Give each research subagent one assignment. Tell it to run
-`npx --yes copilotkit@4.11.0 onboard read subagent/inspect-repository` first and follow the
+`npx --yes copilotkit@4.12.0 onboard read subagent/inspect-repository` first and follow the
 prompt it returns. If that read fails because the subagent cannot use the shell, stop that
 subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
 and the same handoff. Require only its assigned packet.
@@ -106,7 +128,7 @@ Project selection is where the settled port is written down, through `--runtime-
 Then report that the research came back:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase research-returned
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase research-returned
 ```
 
 A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
@@ -122,14 +144,24 @@ the item, both cited findings, and the research limits. Require its result to st
 not inspect the project to settle the conflict yourself. Use the stop route for a non-pass
 verifier result.
 
-Match environment evidence to the target app directory from the project packet. Require one
-target app directory and one matching environment row. If either packet gives no match or
-more than one match, send each research worker a focused directory check. Continue only when
-both workers return the same one target app directory. Both results must start with
-`Status: passed`. Otherwise, use the stop route.
+A target project directory that holds no project has no app directory to key on, and
+that is a merged result rather than a failed merge. Record that this run has no target app
+directory and no environment row, then take the read below. Do not send a focused directory
+check, and do not use the stop route: neither worker can find a directory a developer has
+not created yet, and the route below is where such a project picks its starter.
+
+A directory holding only a Git repository, a coding agent's own configuration, editor
+settings or scratch notes holds no project. `onboard inspect` reports that as
+`appDiscovery.reason` of `no-project`.
+
+For a target project that does hold an app, match environment evidence to the target app
+directory from the project packet. Require one target app directory and one matching
+environment row. If either packet gives no match or more than one match, send each research
+worker a focused directory check. Continue only when both workers return the same one target
+app directory. Both results must start with `Status: passed`. Otherwise, use the stop route.
 
 When both research results are merged, run
-`npx --yes copilotkit@4.11.0 onboard read research/route`.
+`npx --yes copilotkit@4.12.0 onboard read research/route`.
 
 If inspection stops onboarding, run
-`npx --yes copilotkit@4.11.0 onboard read stopped/run-failed`.
+`npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/route.md

@@ -9,7 +9,7 @@ sends the run down one path.
 Before you route on, run this from the target app directory:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect
+npx --yes copilotkit@4.12.0 onboard protect
 ```
 
 It reads the working tree itself, records every changed or untracked path with a digest,
@@ -37,6 +37,27 @@ The findings must cover what the project is for, the agent, frontend, CopilotKit
 authentication, credential names, and validation path. Do not ask the developer for facts
 that the repository answers.
 
+## What the CLI proposed for the framework and frontend
+
+`onboard inspect` matched the project's manifests against the framework and frontend sets
+this graph serves, and its `detection` block carries the result with the dependency and
+directory behind each answer. Read it as a proposal.
+
+- `match` names the one slug that fits. Confirm it against the findings before you use it.
+- `matched` holds more than one slug where more than one fits. `langgraph-python` and
+  `langgraph-fastapi` are two ways of serving one framework and no dependency tells them
+  apart, so pick by how the agent is actually served.
+- `match: null` with an empty `matched` means the CLI placed nothing. This is never a
+  stop, and never a reason to route out on its own. It says only that no dependency
+  matched. Whether the project can be onboarded is your judgment, not its.
+- `unmatched` names the dependencies it did not place. Use them as evidence for what the
+  project runs.
+
+Detection proposes and you dispose. Keep the documentation-gap exception exactly as it is:
+an agent framework outside this set that speaks AG-UI is still yours to recognize and
+route to best effort. Where your reading disagrees with the proposal, record your own
+answer and say that the two disagreed.
+
 ## Route on the merged findings
 
 Read the route off the merged findings. Three of them decide it, and you already hold all
@@ -51,7 +72,7 @@ settle these three from your own reading of the project. Each one comes from the
 packets or it is not proved.
 
 If all three are proved, prove the live starting state before any project file changes. Run
-`npx --yes copilotkit@4.11.0 onboard read proof/oss-baseline`.
+`npx --yes copilotkit@4.12.0 onboard read proof/oss-baseline`.
 
 Route there before you ask the developer anything else. The questions after this prompt
 select a framework and a frontend that the findings already name, so a developer who
@@ -64,7 +85,7 @@ developer nor the repository findings prove what the project is for, ask one gui
 question about the user outcome. This asks what the developer wants to build before you
 select a framework. Give two or three short examples and offer a minimal starter. Record
 the answer and give it to each later subagent. Then run
-`npx --yes copilotkit@4.11.0 onboard read credentials/plan`.
+`npx --yes copilotkit@4.12.0 onboard read credentials/plan`.
 
 Do not ask that question on the route above. A project carrying all three states its
 purpose in the application it already serves.
@@ -76,5 +97,5 @@ A purpose question here names a domain before that choice.
 Take the same read named above without asking.
 
 If authentication or inspection stops onboarding, run
-`npx --yes copilotkit@4.11.0 onboard read stopped/run-failed`. Neither says anything
+`npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`. Neither says anything
 about whether this project's stack is supported, which is not yet known at this point.

package/onboarding/prompts/starter/clone.md

@@ -46,7 +46,7 @@ the derived name.
 Only if the developer asks for an existing project, or asks to see the projects they have,
 read the choices:
 
-`npx --yes copilotkit@4.11.0 project list --json`
+`npx --yes copilotkit@4.12.0 project list --json`
 
 Then ask which one to use. Do not order the projects by creation time. If the developer
 already gave this answer, do not ask again. Do not read a secret value. Do not show or
@@ -56,7 +56,7 @@ Run the command from the parent directory. Do not inspect another entry in the p
 directory. Replace each placeholder with the recorded value. Do not run a placeholder as
 a shell argument.
 
-`npx --yes copilotkit@4.11.0 init --name <project-name> --framework <framework-id> --channel none --no-banner --create <name> --install`
+`npx --yes copilotkit@4.12.0 init --name <project-name> --framework <framework-id> --channel none --no-banner --create <name> --install`
 
 Pass the confirmed name to both `--name` and `--create`: the app directory and its
 Intelligence project take the same name here. If the developer names an existing project,
@@ -72,7 +72,7 @@ account. The command does not need terminal input.
 Report the clone before you inspect anything:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase starter-cloned
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase starter-cloned
 ```
 
 This is its own step, not an aside. A run that clones and then goes quiet is
@@ -82,10 +82,10 @@ separates them.
 Do not rebuild the starter by hand. Then inspect only the generated
 paths inside the target directory. Record the files, install result, project connection,
 and validation commands. Then run
-`npx --yes copilotkit@4.11.0 onboard read proof/round-trip`.
+`npx --yes copilotkit@4.12.0 onboard read proof/round-trip`.
 
 If the command fails, report its exact error and do not claim that the starter is ready.
 Then run
-`npx --yes copilotkit@4.11.0 onboard read stopped/run-failed`. The starter is one this
+`npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`. The starter is one this
 graph ships and the stack was chosen from its own supported list, so a command that
 returned an error is a run that broke, not a setup this release does not support.

package/onboarding/prompts/stopped/run-failed.md

@@ -23,13 +23,42 @@ Say what the developer has now. Name the processes still running and the files t
 changed, so they can carry on by hand or start again from a known state. A run that stops
 without saying what it left behind leaves the developer to discover it.
 
+## If one scoped fix can finish this run
+
+Do not decide this yourself. This run refused to widen its own scope, and that refusal
+stands. The developer is the one who can widen it.
+
+Name the one fix you propose, and say which file or process it touches. Ask the
+developer whether they approve that one fix. If they decline, or the question cannot be
+put to them, stop here and send the report below.
+
+If they approve it, make that one fix and nothing else. Then come back into this run:
+
+```text
+npx --yes copilotkit@4.12.0 onboard resume
+```
+
+Write the developer's approval to standard input, in one or two sentences: the fix they
+approved and what it touches. Send no secrets, source code, logs, or command output. The
+command refuses an approval that carries any of those, prints the reason, exits zero, and
+serves nothing. Reword it and send it again.
+
+The command prints the run id, the step it puts you back on, and that step's prompt.
+Follow that prompt. This is the same run, so do not run `onboard start` again, and keep
+the run id you already have.
+
+If the command refuses for any other reason, it says so and serves nothing. Report what it
+said and stop.
+
+## If no fix is approved
+
 Stop onboarding without making more repository changes.
 
 Send one short report. Run the friction command without another developer question. Do not
 ask the developer about telemetry: the command applies the setting they already have.
 
 ```text
-npx --yes copilotkit@4.11.0 onboard friction --phase stop --category <slug>
+npx --yes copilotkit@4.12.0 onboard friction --phase stop --category <slug>
 ```
 
 Write one or two sentences to standard input: the step you stopped at and what stopped

package/onboarding/prompts/subagent/create-plan.md

@@ -153,7 +153,7 @@ here is work the developer did not ask for.
 Plan the threads drawer itself: add it from the selected drawer page, where this frontend
 does not already render one. Where this journey's frontend framework ships no threads
 drawer -- React Native --, plan that the thread is proved by
-`npx --yes copilotkit@4.11.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --yes copilotkit@4.12.0 verify --round-trip`, which needs no browser. Do not plan a
 step that opens the managed Intelligence dashboard.
 
 ## Order the plan into steps
@@ -179,6 +179,12 @@ and one sentence saying what the step changes there and why no other file will d
 step in the plan. Return `Status: blocked` only when the plan needs a protected path you
 cannot justify in that sentence.
 
+Authorization covers changing a protected path, not removing it. Do not plan the deletion
+of a protected path, and do not plan a step that moves or renames one, which removes it
+under its captured name. If a step cannot be written any other way, return
+`Status: blocked` and name the path. The developer approves a plan that changes their
+files, and a plan that deletes one asks for something the audit cannot pass.
+
 Return the protected path list as part of the plan.
 
 Keep final validation and proof outside the implementation steps. The developer approves

package/onboarding/prompts/subagent/implement-and-validate.md

@@ -3,7 +3,8 @@
 Implement every step of the approved plan in plan order, and run the full validation list.
 Do not repeat the full repository inspection.
 
-Do not change a protected path.
+Do not change a protected path. Do not delete, move, or rename one either, whatever the
+plan says: a protected path that is gone fails the audit and no command clears that.
 Do not change a path that overlaps a protected path. Paths overlap when they are equal or
 either path is an ancestor directory on a path-segment boundary. `apps/a` overlaps
 `apps/a/src`, but not `apps/ab`. `app.ts` does not overlap `app.tsx`.

package/onboarding/prompts/subagent/inspect-repository.md

@@ -2,16 +2,41 @@
 
 Work only on the packet you were assigned. Inspect the repository without changing it.
 
+## Start with what the CLI already knows
+
+Run this first, from the target project directory:
+
+```text
+npx --yes copilotkit@4.12.0 onboard inspect --json
+```
+
+It answers the deterministic half of both packets exactly, from the same code
+`copilotkit verify` uses: the project record by presence, and, for each app or runtime
+directory on its own, the env files, which variable carries the Intelligence key and which
+file it came from, whether that directory's own process can load it, the package manager
+its lockfile proves, the port it declares, and the exact installed version of every
+`@copilotkit/*` dependency. It reads only and prints no secret value.
+
+Carry those readings into your findings as they came back. Do not work one of them out
+again by reading files. The directory that owns `.env` is the hard case and the CLI holds
+the fixes for it, so a second answer derived here is a guess competing with a proof.
+
+An empty `apps` array is an answer, not a failed probe. App discovery keys on a declared
+`@copilotkit/*` dependency, so a project that has not installed CopilotKit reports no apps
+however much else its tree holds. `appDiscovery` says why it is empty: `no-project` for a
+target directory that holds no project yet, and `no-declared-dependency` for a project
+where no directory declares one. Report that reason as the finding. Do not report that
+the inspection found nothing.
+
 ## Project evidence packet
 
 Find evidence for:
 
 - what the project is for, in the project's own words
-- the target app or runtime directory that owns `.env` and the CopilotKit setup
 - whether the target project directory contains any entries
-- any existing agent framework and frontend
-- current CopilotKit integration and configuration, including whether
-  `.copilotkit/project.json` has `projectId`, `projectSlug`, and `clerkOrgId`
+- any existing agent framework and frontend, confirming or contradicting the
+  `detection` block the CLI proposed
+- current CopilotKit integration and configuration
 - authentication boundaries
 - initial changed and untracked paths, without file contents
 
@@ -21,25 +46,27 @@ protected-path audit compares against, so nothing later in the run depends on th
 subagent still existing, and a path that can hold secrets is captured as a digest you
 never read.
 
+Take the target app or runtime directory from the CLI packet rather than working it out
+here. `copilotkit verify` resolves it, and two fixes live in that resolution which a
+reading of the files will not reproduce.
+
 ## Environment evidence packet
 
-- names of required credential variables and whether `.env` has a non-empty
-  `CPK_INTELLIGENCE_API_KEY`
+- names of required credential variables, beyond the Intelligence key the CLI reported
 - retain the `.env` modification time for a later comparison without returning it
-- package manager and lockfile
 - required toolchains and their installed versions
-- declared ports and whether each port is available
+- whether each port the CLI reported as declared is free
 - whether the runtime constructor uses a `runner` option, an `intelligence` option, or
   neither can be proved from project files
-- CopilotKit package versions and package compatibility risks
+- package compatibility risks, and whether any `@copilotkit/*` version the CLI reported is
+  below 1.70.0
 
 Key every environment finding by its app or runtime directory. Do not combine findings
-from different directories.
+from different directories. The CLI packet keys its own readings the same way.
 
-For the CopilotKit versions, report the exact installed version of every `@copilotkit/*`
-dependency, read from the lockfile rather than a manifest range, and state whether any of
-them is below 1.70.0. The conversion decides its upgrade from exactly that, and a caret
-range does not answer it.
+The CLI reports the exact installed version of every `@copilotkit/*` dependency, read from
+the installed tree rather than from a manifest range. The conversion decides its upgrade
+from exactly that, and a caret range does not answer it.
 
 A project states what it is for in its `README.md`, in its package description, or in
 the prompt of an agent it already has. Quote that statement rather than rewriting it. An
@@ -59,5 +86,5 @@ Return one row for each assigned item with its status, evidence path, and a shor
 Use only `proved`, `absent`, or `unproved` for the status. State each absent or unproved item.
 Do not read, print, or return secret values. For `.env` and `.copilotkit/project.json`
 checks, return only paths, presence checks, and missing field names. Do not read a file
-outside the project directory. Do not run or return another onboarding command. Stop after
-returning the findings to the main coding agent.
+outside the project directory. Do not run or return an onboarding command other than
+`onboard inspect`. Stop after returning the findings to the main coding agent.

package/onboarding/prompts/subagent/prove-oss-baseline.md

@@ -19,7 +19,7 @@ Prove the live runtime in this order:
 4. Confirm from project files that the runtime constructor passes a `runner` option rather
    than an `intelligence` option. A package, import, project file, or key is not use proof.
 5. Run
-   `npx --yes copilotkit@4.11.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --yes copilotkit@4.12.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
    with the runtime URL or auth header options that this project needs. Require exit zero
    and the JSON `ok` field to be `true`.
 6. Drive one real request through the existing frontend, CopilotKit runtime, and expected

package/onboarding/prompts/subagent/prove-round-trip.md

@@ -135,7 +135,7 @@ IPv6 only, so an IPv4 literal fails against the correct port.
 ## Step 4 -- Check the wiring
 
 With both running, check the wiring in one command before you open a browser:
-`npx --yes copilotkit@4.11.0 verify --json`. It reads the port from this project, so a
+`npx --yes copilotkit@4.12.0 verify --json`. It reads the port from this project, so a
 non-default port needs no flag. The payload reports `runtimeUrl` and `runtimeUrlSource`. A
 `runtimeUrlSource` of `default` means nothing in the project named a port, so pass
 `--runtime-url` with the URL from step 1 in that case. Read the individual checks rather than
@@ -149,10 +149,11 @@ used the Intelligence credential. `api_key_authenticates` proves only that the k
 `api_key_loadable_by_app` fails when the key is in a file the application's own process
 will not read. `verify` searches upward for the credential and a framework's env loader
 does not, so a key at the repository root is invisible to an app in a subdirectory. The
-check names the file to write instead. Write the key there, or run
-`npx --yes copilotkit@4.11.0 project select` from the app directory. Do not link,
-copy, or symlink the file to work around it, and do not treat the credential as missing:
-the check above already reported that it exists.
+check names the file to write instead, and it names the exact command to re-run with this
+project already chosen. Write the key there, or run the command the check names, from the
+app directory. Do not run a bare `project select`: with no project named it needs a
+terminal you do not have. Do not link, copy, or symlink the file to work around it, and do
+not treat the credential as missing: the check above already reported that it exists.
 
 `intelligence_thread_routes` fails when a licensed runtime serves no thread routes. A missing
 `identifyUser` is the usual cause: it gates the whole web surface. Return the check for
@@ -168,7 +169,7 @@ named no port the CLI can read: keep step 2's URL, and rewrite its host as `loca
 before you use it.
 
 Then run the command once more with the URL you are about to open:
-`npx --yes copilotkit@4.11.0 verify --frontend-url <that url> --json`. The
+`npx --yes copilotkit@4.12.0 verify --frontend-url <that url> --json`. The
 `frontend_assets_served` check asks that server for its page and for one of the page's own
 assets, on that exact host. A `fail` there means the dev server refuses its own static
 assets on the host you were about to use, and the check names the URL to use instead. This
@@ -176,7 +177,7 @@ is the cheapest step that can save the most expensive one, so run it before the
 
 ## Step 5 -- Prove that the agent runs
 
-Run `npx --yes copilotkit@4.11.0 verify --round-trip --json`. It sends one request through
+Run `npx --yes copilotkit@4.12.0 verify --round-trip --json`. It sends one request through
 the runtime and reads the answer back from the thread, so it separates an agent that is
 configured from an agent that works. Use `--agent <id>` when the runtime declares more
 than one. If it reports `user-not-identified`, this project's `identifyUser` reads a
@@ -189,7 +190,7 @@ Where this run settled a Learning Container, add the flag to the call above rath
 running a second round trip:
 
 ```text
-npx --yes copilotkit@4.11.0 verify --round-trip --expect-learning-container <container id> --json
+npx --yes copilotkit@4.12.0 verify --round-trip --expect-learning-container <container id> --json
 ```
 
 The check reads the thread that this run created, so a second round trip proves a second
@@ -217,6 +218,22 @@ callback rather than from an assigned thread. Never report either one as proof.
 
 Where this run skipped the Learning step, leave the flag off.
 
+Where the runtime answers with a 401 from the model provider, check the processes before
+you change anything. A process reads its env file once, at launch, so one started before
+the credential was written holds an empty key while the file beside it carries the real
+one. Run this from the target app directory:
+
+```text
+npx --yes copilotkit@4.12.0 onboard env-staleness
+```
+
+A `stale` line names the env file and how long after launch it was written. Report that,
+with the process and the file it named, and say the process has to be started again before
+the 401 means anything. Do not restart it yourself and do not stop it: the reading names a
+process and never its owner, and one project's dev script often serves the agent and the
+frontend together. Editing a file to answer a 401 that a restart clears changes the project
+for a fault it does not have.
+
 ### Step 5a -- Prove that the page's data reaches the model
 
 `verify --round-trip` sends `context: []` and asks a question that needs no context. It
@@ -285,7 +302,7 @@ For a recorded `both-oss` starting state, this step has no component to render.
 same request the baseline recorded, require the same kind of user-visible result the
 baseline produced, and require that the thread for that request is listed in the drawer.
 Where this journey's frontend framework ships no threads drawer -- React Native --, prove
-that thread with `npx --yes copilotkit@4.11.0 verify --round-trip`, which reads the
+that thread with `npx --yes copilotkit@4.12.0 verify --round-trip`, which reads the
 answer back off the thread and needs no browser. Record which of the two you proved.
 
 Use the surface control the main coding agent recorded for your environment. It either had
@@ -313,7 +330,7 @@ request never exercises. Drive it with the browser control step 6 named.
    the page to finish loading. Do not retype the host, and do not substitute a URL a tool
    offers you by default. Where the page loads but its styling is missing or the chat
    control is dead, run
-   `npx --yes copilotkit@4.11.0 verify --frontend-url <the url you opened> --json`
+   `npx --yes copilotkit@4.12.0 verify --frontend-url <the url you opened> --json`
    before you diagnose anything else. A dev server can serve its page and refuse every
    static chunk behind it, and on screen that is indistinguishable from a broken
    integration. The `frontend_assets_served` check tells the two apart.

package/onboarding/prompts/unsupported/no-validated-path.md

@@ -30,13 +30,13 @@ Before you show the best-effort plan, require this complete packet:
 - Give the ordered proof rules.
 
 After the developer approves the best-effort plan, run
-`npx --yes copilotkit@4.11.0 onboard read fallback/best-effort`.
+`npx --yes copilotkit@4.12.0 onboard read fallback/best-effort`.
 
 Send one short report. Run the friction command without another developer question. Do not
 ask the developer about telemetry: the command applies the setting they already have.
 
 ```text
-npx --yes copilotkit@4.11.0 onboard friction --phase stop --category <slug>
+npx --yes copilotkit@4.12.0 onboard friction --phase stop --category <slug>
 ```
 
 Write one or two sentences to standard input: the step you stopped at and what stopped it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilotkit",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -10,7 +10,8 @@
   "bin": {
     "copilotkit": "./index.js"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "@microsoft/teams.cli": "3.0.3"
-  }
+  },
+  "license": "SEE LICENSE IN LICENSE"
 }

package/release/release-tool.js

@@ -14698,7 +14698,7 @@ import * as path4 from "node:path";
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "dc1238c0bd473e259c992b85026cb30fe6b3b726" : "main";
+  return true ? "0048ba241fdf14a9036cdad11a4f31aa021a9c8d" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts