copilotkit 4.11.0 → 4.12.0

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

@@ -27,10 +27,10 @@ and validation results.
 After validation and each repair, run:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard audit
+npx --yes copilotkit@4.12.0 onboard audit
 ```
 
-Continue only when it starts with `Status: passed`. A path under `Authorized to change:` is
+Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
 not a finding. Carry it into the final summary with its reason.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -38,7 +38,7 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect --accept-external --path <path>
+npx --yes copilotkit@4.12.0 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
@@ -47,24 +47,24 @@ or its report does not settle who changed it, ask the developer to allow the unp
 change. Only after they agree, record their answer:
 
 ```text
-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>"
 ```
 
 Run the audit again after each accepted or authorized change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When implementation validation passes, report it:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase build-validated
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase build-validated
 ```
 
 If validation cannot pass, or this run needs a prerequisite the app does not have, use
 the feature stop route above without further changes.
 
 Otherwise run
-`npx --yes copilotkit@4.11.0 onboard read feature/channels/proof`.
+`npx --yes copilotkit@4.12.0 onboard read feature/channels/proof`.

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

@@ -16,23 +16,23 @@ route after the audit rules below.
 Report each attempt at the proof 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
 ```
 
 Report each repair cycle the same way, counting from 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
 ```
 
 After the final attempt, report the gate exactly once:
 
 ```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>
 ```
 
 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 --yes copilotkit@4.11.0 onboard audit`.
+failed, and `skipped` when the proof did not run. Then run `npx --yes copilotkit@4.12.0 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
@@ -47,11 +47,11 @@ Run the audit again after each accepted or authorized change.
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When the audit passes and the mention proof passed, run
-`npx --yes copilotkit@4.11.0 onboard read feature/complete` with the actual surface
+`npx --yes copilotkit@4.12.0 onboard read feature/complete` with the actual surface
 outcome. Use `--visual-check performed` only when a browser drove Slack or Teams web
 and proved the mention reply. Use `--visual-check skipped-no-browser-tool` only when
 no browser tool was available.

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

@@ -3,7 +3,7 @@
 First, report your coding agent identity using the same command as generic onboarding:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard identify --coding-agent <coding-agent-slug>
+npx --yes copilotkit@4.12.0 onboard identify --coding-agent <coding-agent-slug>
 ```
 
 Use your own product's slug, such as `codex` or `claude-code`. This also covers entry
@@ -17,7 +17,7 @@ restricted to the target project.
 Before any subagent or project process runs, capture the developer's existing work:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect
+npx --yes copilotkit@4.12.0 onboard protect
 ```
 
 Keep the exact protected path list it prints and give that list to every subagent. Do not
@@ -43,7 +43,7 @@ This one does not.
 Wait for the inspection subagent to finish. Then report that the inspection 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
@@ -54,7 +54,7 @@ without cloning. Do not switch to a custom build in silence. Name the missing to
 Offer a custom headless build as a later path. Then route out:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 Do not run login, select Intelligence, or create a credential until the developer
@@ -69,12 +69,14 @@ Slack e2e harness. Name focused tests and a real mention proof on the chosen
 provider. Ask for approval separately.
 
 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.
+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 --yes copilotkit@4.11.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --yes copilotkit@4.12.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
 ```
 
 If an approved path changed after capture and no implementation step has run, add
@@ -84,7 +86,7 @@ authorize a path the approved plan did not list.
 Then report the plan this run is about to implement:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase plan-written
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase plan-written
 ```
 
-Then run `npx --yes copilotkit@4.11.0 onboard read feature/channels/implement`.
+Then run `npx --yes copilotkit@4.12.0 onboard read feature/channels/implement`.

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

@@ -15,10 +15,10 @@ Run focused type/test checks and start the app. Record the changed files and val
 After validation and each repair, run:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard audit
+npx --yes copilotkit@4.12.0 onboard audit
 ```
 
-Continue only when it starts with `Status: passed`. A path under `Authorized to change:` is
+Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
 not a finding. Carry it into the final summary with its reason.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -26,7 +26,7 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect --accept-external --path <path>
+npx --yes copilotkit@4.12.0 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
@@ -35,24 +35,24 @@ or its report does not settle who changed it, ask the developer to allow the unp
 change. Only after they agree, record their answer:
 
 ```text
-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>"
 ```
 
 Run the audit again after each accepted or authorized change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When implementation validation passes, report it:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase build-validated
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase build-validated
 ```
 
 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 --yes copilotkit@4.11.0 onboard read feature/chat-suggestions/proof`.
+`npx --yes copilotkit@4.12.0 onboard read feature/chat-suggestions/proof`.

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

@@ -12,23 +12,23 @@ project-owned services running.
 Report each attempt at the proof 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
 ```
 
 Report each repair cycle the same way, counting from 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
 ```
 
 After the final attempt, report the gate exactly once:
 
 ```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>
 ```
 
 Use `passed` only for a proved sent suggestion, `failed` for an attempted proof that failed,
-and `skipped` when the proof could not run. Then run `npx --yes copilotkit@4.11.0 onboard audit`.
+and `skipped` when the proof could not run. Then run `npx --yes copilotkit@4.12.0 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
@@ -43,9 +43,9 @@ Run the audit again after each accepted or authorized change.
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When the audit passes, run
-`npx --yes copilotkit@4.11.0 onboard read feature/complete` with the real browser-proof
+`npx --yes copilotkit@4.12.0 onboard read feature/complete` with the real browser-proof
 outcome.

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

@@ -6,7 +6,7 @@ implementation, and proof to separate subagents and keep all work inside the tar
 Before any subagent or project process runs, capture the developer's existing work:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect
+npx --yes copilotkit@4.12.0 onboard protect
 ```
 
 Keep the exact protected path list it prints and give that list to every subagent. No
@@ -15,7 +15,7 @@ approved authorization before implementation.
 
 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.11.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`,
+`/info`, `npx --yes copilotkit@4.12.0 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.
@@ -23,7 +23,7 @@ onboarding first.
 Wait for the inspection subagent to finish. Then report that the inspection 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
@@ -33,7 +33,7 @@ If the inspection did not prove the baseline this intent extends, stop here with
 changing files:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 Do not run login, provision Intelligence, request a credential, replace the agent, or alter
@@ -48,12 +48,14 @@ context-dependent follow-ups. Show an approved-plan-sized diff, a focused test,
 that a visible suggestion submits the intended message.
 
 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.
+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 --yes copilotkit@4.11.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --yes copilotkit@4.12.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
 ```
 
 If an approved path changed after capture and no implementation step has run, add
@@ -63,7 +65,7 @@ authorize a path the approved plan did not list.
 Then report the plan this run is about to implement:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase plan-written
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase plan-written
 ```
 
-Then run `npx --yes copilotkit@4.11.0 onboard read feature/chat-suggestions/implement`.
+Then run `npx --yes copilotkit@4.12.0 onboard read feature/chat-suggestions/implement`.

package/onboarding/prompts/feature/complete.md

@@ -3,7 +3,7 @@
 Use the outcome the proof step observed. Run:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>
+npx --yes copilotkit@4.12.0 onboard complete --visual-check <performed|skipped-no-browser-tool|failed>
 ```
 
 Use `performed` only when browser control drove the real user-visible surface. Use

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

@@ -5,12 +5,57 @@ valid existing Intelligence selection. If it is absent, use the documented strea
 `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.
 
+## If you stop in this phase
+
+Four rules below end this run without completing it: an entitlement the platform will not
+resolve, a container id that never resolves, an audit that stays blocked, and validation
+that cannot pass. Each one stops onboarding for a developer who has already approved a
+plan. Name the exact command, id, and error code that stopped you: a report that names only
+the step cannot be acted on. Send one short report before you stop. 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.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.
+Pick the category that fits from docs-missing, docs-wrong, docs-sequential, cli-gap,
+sdk-gap, environment, port-collision, credential, validation-loop, and other. Leave
+--cost-seconds off. A run that stopped cannot separate one papercut's cost from the cost of
+the whole run, so the estimate is optional on a stop report and only there. Send no secrets,
+source code, logs, or command output. The command refuses a report that carries any of
+those, prints the reason, and exits zero. A refused report is not a failed step. Send the
+report, then stop.
+
+A refusal by the platform is the one exception. It reaches `feature/blocked-by-plan`, which
+reports the ending by itself and says to file nothing further.
+
 After the project is selected, settle the container from the terminal.
 
+Whichever of the two reads below runs first also answers the entitlement question, because
+a read carries the same availability gate as the create. Read `status` and `error.code`
+from its payload. Route on the code rather than on the exit status.
+`LEARNING_NOT_ENABLED` means the platform refused Learning to this organization. That is a
+settled refusal rather than a missing baseline, so stop here, before any file change, and
+take its own ending:
+
+```text
+npx --yes copilotkit@4.12.0 onboard read feature/blocked-by-plan
+```
+
+`LEARNING_AVAILABILITY_UNAVAILABLE` means the platform did not resolve the answer. It is
+unknown rather than denied. Run the same command once more. If the second call answers the
+same way, report the code and stop onboarding.
+
+`feature/learning/start` asks this question first, and a run that arrives here already
+signed in has its answer. A run that reached this prompt signed out could not be asked
+then, so the read below is where its refusal surfaces.
+
 When the plan or the repository already names an id, ask about that one id and nothing else:
 
 ```text
-npx --yes copilotkit@4.11.0 learning containers get <id> --json
+npx --yes copilotkit@4.12.0 learning containers get <id> --json
 ```
 
 One call answers it, and no list is needed.
@@ -18,7 +63,7 @@ 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.11.0 learning containers list --json
+npx --yes copilotkit@4.12.0 learning containers list --json
 ```
 
 One call returns at most 500 containers. When `nextCursor` in the result is not null, read
@@ -29,7 +74,7 @@ second container for work the first one already covers.
 Report what the read found before asking anyone anything:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase container-surveyed
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase container-surveyed
 ```
 
 Everything after this waits on a person, so a run that stops past this point stopped on a
@@ -47,10 +92,24 @@ person. Route per user only when the developer asks for it, and do it in their s
 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:
+Ask the CLI for the id rather than spelling one yourself:
+
+```text
+npx --yes copilotkit@4.12.0 learning containers default-id --json
+```
+
+It derives the project-scoped id from the selected project's slug, reads the local project
+record only, and needs no credential. `"status": "success"` carries it in `containerId`.
+`"status": "skipped"` means there is no id to derive: `slug-unusable` for a slug that
+leaves nothing the id contract accepts, and `no-project-record` for a directory with no
+selected project. Only then pick a descriptive lowercase hyphenated id of 1-64 characters.
+
+Both this intent and a first onboarding run settle the same project's container, and the
+run that spells the id differently gives one project two containers, each below the line
+above on its own. One command is what keeps the two spellings identical.
 
 ```text
-npx --yes copilotkit@4.11.0 learning containers create --id <id> --name <name> --json
+npx --yes copilotkit@4.12.0 learning containers create --id <id> --name <name> --json
 ```
 
 An id already in use answers `LEARNING_CONTAINER_ALREADY_EXISTS`. That is a container to
@@ -65,7 +124,7 @@ or a guessed id.
 Then report that the container is settled, before any edit:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase container-settled
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase container-settled
 ```
 
 Everything above happens between two prompts, so a run that stopped on a developer who could
@@ -86,16 +145,16 @@ non-zero on an app that is working. Pass what `identifyUser` reads with a repeat
 It is not a defect to repair.
 
 Run focused tests and
-`npx --yes copilotkit@4.11.0 verify --expect-runtime intelligence --round-trip --agent <agent-id> --json`.
+`npx --yes copilotkit@4.12.0 verify --expect-runtime intelligence --round-trip --agent <agent-id> --json`.
 Repair changed-file failures and record secret-safe evidence.
 
 After validation and each repair, run:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard audit
+npx --yes copilotkit@4.12.0 onboard audit
 ```
 
-Continue only when it starts with `Status: passed`. A path under `Authorized to change:` is
+Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
 not a finding. Carry it into the final summary with its reason.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -103,7 +162,7 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect --accept-external --path <path>
+npx --yes copilotkit@4.12.0 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
@@ -112,24 +171,24 @@ or its report does not settle who changed it, ask the developer to allow the unp
 change. Only after they agree, record their answer:
 
 ```text
-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>"
 ```
 
 Run the audit again after each accepted or authorized change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When implementation validation passes, report it:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase build-validated
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase build-validated
 ```
 
 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 --yes copilotkit@4.11.0 onboard read feature/learning/proof`.
+`npx --yes copilotkit@4.12.0 onboard read feature/learning/proof`.

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

@@ -7,7 +7,7 @@ Container. Confirm the thread remains associated with the expected user.
 One command decides it:
 
 ```text
-npx --yes copilotkit@4.11.0 verify --expect-runtime intelligence --round-trip --agent <agent-id> --expect-learning-container <id> --json
+npx --yes copilotkit@4.12.0 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
@@ -25,30 +25,31 @@ 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.
+counts. Existing threads can join this container if they never belonged to another one.
+Their surviving earlier history then becomes eligible for collection and counts toward the
+same threshold. Existing threads do not join automatically just because a container exists.
 
 Report each attempt at the proof 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
 ```
 
 Report each repair cycle the same way, counting from 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
 ```
 
 After the final attempt, report the gate exactly once:
 
 ```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>
 ```
 
 Use `passed` only for a proved Container assignment, `failed` for an attempted proof that
 failed, and `skipped` when the proof could not run. Then run
-`npx --yes copilotkit@4.11.0 onboard audit`. Continue only when it starts with
+`npx --yes copilotkit@4.12.0 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,9 +64,9 @@ Run the audit again after each accepted or authorized change.
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 When the audit passes, run
-`npx --yes copilotkit@4.11.0 onboard read feature/complete` with the actual surface
+`npx --yes copilotkit@4.12.0 onboard read feature/complete` with the actual surface
 outcome.

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

@@ -4,10 +4,62 @@ Treat Learning as a managed Intelligence feature that assigns real threads to a
 Learning Container. Orchestrate with separate read-only, implementation, and proof
 subagents. Work only inside the target project and preserve its existing agent and chat.
 
+## If you stop in this phase
+
+Name the exact command, code, or check that stopped you, then 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.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.
+Pick the category that fits from docs-missing, docs-wrong, docs-sequential, cli-gap,
+sdk-gap, environment, port-collision, credential, validation-loop, and other. Leave
+--cost-seconds off. A run that stopped cannot separate one papercut's cost from the cost of
+the whole run, so the estimate is optional on a stop report and only there. Send no secrets,
+source code, logs, or command output. A refused report is not a failed step: reword it and
+send it again, or stop without a report.
+
+Ask the platform whether this organization may use Learning before doing any work. The
+read carries the same availability gate as the create, so it answers the entitlement
+question in one call and writes nothing:
+
+```text
+copilotkit learning containers list --json
+```
+
+Read `status` and `error.code` from the payload. Route on the code rather than on the exit
+status:
+
+- `"status": "success"` means Learning is available here. Continue with the capture below.
+- `LEARNING_NOT_ENABLED` means the platform refused Learning to this organization. Stop
+  before the capture, the inspection, and any edit:
+
+```text
+npx --yes copilotkit@4.12.0 onboard read feature/blocked-by-plan
+```
+
+- `LEARNING_AVAILABILITY_UNAVAILABLE` means the platform did not resolve the answer. It is
+  unknown rather than denied. Run the same command once more. If the second call answers
+  the same way, report the code and stop onboarding.
+- `AUTH_FAILED` and `PREREQUISITE_MISSING` mean the probe could not ask. This run reaches
+  this prompt before any login or project selection, so the CLI holds no session yet, or
+  this directory has no selected Intelligence project. Neither is a refusal. Do not stop,
+  and do not read `feature/blocked-by-plan`. Continue with the capture below.
+  `feature/learning/implement` signs in, selects the project, and asks the same question
+  there, still before any file changes.
+- Any other code: report it and stop onboarding.
+
+A refusal is not a missing prerequisite. It has its own ending, and `feature/stop` below is
+for a baseline this project does not have. A run that has no session yet is a third thing
+again: it has no answer, so it carries the question forward rather than ending on it.
+
 Before any subagent or project process runs, capture the developer's existing work:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard protect
+npx --yes copilotkit@4.12.0 onboard protect
 ```
 
 Keep the exact protected path list it prints and give that list to every subagent. No
@@ -23,7 +75,7 @@ onboarding.
 Wait for the inspection subagent to finish. Then report that the inspection 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
@@ -33,7 +85,7 @@ If the inspection did not prove the baseline this intent extends, stop here with
 changing files:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard read feature/stop
+npx --yes copilotkit@4.12.0 onboard read feature/stop
 ```
 
 Fetch the current official guides before planning:
@@ -58,12 +110,14 @@ the documented `getLearningContainerId` selector, validation, and a visible assi
 proof. Ask for approval separately.
 
 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.
+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 --yes copilotkit@4.11.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --yes copilotkit@4.12.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
 ```
 
 If an approved path changed after capture and no implementation step has run, add
@@ -73,7 +127,7 @@ authorize a path the approved plan did not list.
 Then report the plan this run is about to implement:
 
 ```text
-npx --yes copilotkit@4.11.0 onboard checkpoint --phase plan-written
+npx --yes copilotkit@4.12.0 onboard checkpoint --phase plan-written
 ```
 
-Then run `npx --yes copilotkit@4.11.0 onboard read feature/learning/implement`.
+Then run `npx --yes copilotkit@4.12.0 onboard read feature/learning/implement`.