copilotkit 4.9.2 → 4.9.17

package/onboarding/prompts/credentials/finalize-plan.md

@@ -1,7 +1,9 @@
 # Select the Intelligence project and create the plan
 
 Use the selected framework, frontend, model vendor, model, documentation URLs, and
-repository findings. Ask the developer only for choices that the repository does not
+repository findings. On a conversion these were read from the baseline rather than
+selected, and the conversion prompt recorded them: use those values and ask no framework
+or frontend question here. Ask the developer only for choices that the repository does not
 show. Do not change application code in this phase. Do not read, show, store, or request
 a secret value.
 
@@ -10,6 +12,25 @@ one question. Put the recommendation first, give its evidence in one sentence, a
 the alternatives short. When project selection is unknown, ask only which Intelligence
 project to use. Keep final plan approval as its own later question.
 
+## If you stop in this phase
+
+Several rules below stop onboarding: a refused classification value, an output path that
+overlaps a protected path, a project selection that reports a false field, a failed
+credential check, a model credential nobody can place. Each one ends a run that reached
+project selection and never got a plan, and more runs stop here than anywhere else. Send
+one short report before you stop. Run the feedback command without another developer
+question. The CLI telemetry gate decides whether the report is sent.
+
+```text
+npx --yes copilotkit@4.9.17 onboard feedback
+```
+
+Write at most four lines to standard input: the step you stopped at and what stopped it.
+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 the way the rule that stopped you says to. Reporting is
+not a route change and does not resume the run.
+
 ## Record the audit cell
 
 Use the repository findings and selected choices to record the path before project work
@@ -24,7 +45,7 @@ starts. Choose one starting state: empty, agent-only, frontend-only, both, both-
 Run this command with the exact selected slugs:
 
 ```text
-npx --yes copilotkit@4.9.2 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
+npx --yes copilotkit@4.9.17 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
 ```
 
 Do not continue if a value is refused. Fix the value from the choices that the earlier
@@ -34,13 +55,14 @@ prompts gave, then run the command again.
 
 Use the target app or runtime directory from the repository findings. If a nested app owns
 the runtime `.env` file, do not default to the repository root.
+Set the environment path to `<target>/.env`.
 
-If valid project fields and a non-empty `INTELLIGENCE_API_KEY` already exist, ask whether to
-keep that selection. Recommend keeping it to avoid minting another key. Ask the developer to
-confirm that the prior project selection had no key-provision warning.
-
-Reused project credentials remain unverified until an authenticated Intelligence call
-succeeds. Record that state in the plan.
+If valid project fields and a non-empty `CPK_INTELLIGENCE_API_KEY` already exist, use this
+rule: Reuse that project without another question. Do not mint another key. The round-trip
+proof later runs the authenticated Intelligence checks. Record the reused project
+credentials as unverified in the plan until those checks pass.
+If you reuse a project, set the project-record path to the exact evidence path from the
+project research subagent.
 
 If the developer needs a project or another project, do the selection yourself from the
 target directory. Do not send the developer to another terminal.
@@ -48,7 +70,7 @@ target directory. Do not send the developer to another terminal.
 Read the choices first:
 
 ```text
-npx --yes copilotkit@4.9.2 project list --json
+npx --yes copilotkit@4.9.17 project list --json
 ```
 
 With `--json` the payload is the only thing on standard output, so it is safe to parse.
@@ -59,38 +81,53 @@ developer asks.
 If the developer searches, run:
 
 ```text
-npx --yes copilotkit@4.9.2 project list --search <query> --json
+npx --yes copilotkit@4.9.17 project list --search <query> --json
 ```
 
 If the developer asks for all projects, show the result of the first list command. Ask
 which project to use, or ask for a new project name. Do not combine this question with a
 frontend, framework, model, credential, or plan-approval question.
 
+Project selection writes the environment path. It updates the nearest project record from
+the target through the repository root. If no project record exists there, it writes one at
+the repository root. If no repository exists, use the target. If the repository root is the
+home directory, use the target.
+
+Before project selection, derive the expected project-record path from the repository
+findings. Compare that path and the environment path with the initial protected paths. Use
+the path-segment overlap rule. If either output path overlaps an initial protected path, do
+not run project selection. Report the conflicting path and stop onboarding.
+
 Then record their answer, from the target directory:
 
 ```text
-npx --yes copilotkit@4.9.2 project select --project <slug-or-id> --json
+npx --yes copilotkit@4.9.17 project select --project <slug-or-id> --json
 ```
 
 Use `--create <name> --json` instead when they want a new project. The two flags cannot be
 combined. A slug that does not exist fails and lists the real ones, so a typo cannot record
 a selection that points at nothing.
 
-Read the JSON result. It reports `selected_project_slug`, `api_key_provisioned`,
-`project_file_written`, and `environment_file_written` at the top level. The result does
-not contain a secret. Report `selected_project_slug` as the project slug that the server
-selected or created. Require `api_key_provisioned`, `project_file_written`, and
-`environment_file_written` to be true. If one is false, report the error and stop
-onboarding. Key provisioning is non-fatal, so the command can persist a selection and
-still exit zero with no key. A scaffold with no key looks finished and is not.
+Read the JSON result. It reports `selected_project_slug`, `config_path`,
+`api_key_provisioned`, `project_file_written`, and `environment_file_written` at the top
+level. The result does not contain a secret. Report `selected_project_slug` as the project
+slug that the server selected or created. Require `api_key_provisioned`,
+`project_file_written`, and `environment_file_written` to be true. If one is false, report
+the error and stop onboarding. Key provisioning is non-fatal, so the command can persist a
+selection and still exit zero with no key. A scaffold with no key looks finished and is not.
+
+After project selection, set the project-record path to the absolute `config_path` from the
+JSON result. If it differs from the expected project-record path, report both paths and stop
+onboarding.
 
 Never print the payload or any secret value.
 
-After a warning-free result, send the research subagent a follow-up check. Require it to
-confirm these facts without showing values:
+After project reuse or a warning-free selection result, send the environment
+research subagent a focused follow-up check. Give it the exact target app directory and both
+credential paths. Require it to report these facts without values:
 
-- `.copilotkit/project.json` has non-empty `projectId`, `projectSlug`, and `clerkOrgId` fields.
-- `.env` has a non-empty `INTELLIGENCE_API_KEY` entry.
+- The project-record path has non-empty `projectId`, `projectSlug`, and `clerkOrgId` fields.
+- The environment path has a non-empty `CPK_INTELLIGENCE_API_KEY` entry.
 - If project selection ran, its selected slug matches `projectSlug`.
 - If project selection ran, the `.env` file was created or its modification time advanced.
 
@@ -98,6 +135,10 @@ Do not print either file or any secret value. If a check fails, stop onboarding.
 selection success message alone does not prove key readiness. The CLI cannot prove key scope
 before an authenticated Intelligence call succeeds.
 
+Continue only if the environment follow-up result starts with `Status: passed`. Retain the
+project-record path and environment path as the credential setup path list. Do not add them
+to the baseline yet.
+
 ## Where a model credential comes from
 
 The plan names the model credential variables. Finding their values is not its job.
@@ -116,6 +157,28 @@ If no answer comes, stop. Do not write a placeholder or an empty value. A scaffo
 carrying a dummy key looks finished and fails at the first model call, which is worse
 than stopping here.
 
+After model credential placement is complete, add each credential setup path to the
+protected path list. Also add each project file that the developer changed for model
+credentials. Record them in the baseline from the target app directory:
+
+```text
+npx --yes copilotkit@4.9.17 onboard protect --path <path>
+```
+
+Pass one `--path` for each. The command captures a digest for each path and never re-reads
+a path the baseline already holds.
+
+Then re-capture the files this graph wrote itself. For each path the first capture printed
+as `deferred` that this run has now written, run:
+
+```text
+npx --yes copilotkit@4.9.17 onboard protect --rebaseline --path <path>
+```
+
+From that point they are protected like any other path, so a later step that rewrites
+`.env` and drops its key fails the audit rather than passing it. Continue only if every
+result starts with `Status: passed`.
+
 ## Wire the runtime to Intelligence
 
 The key in `.env` does nothing on its own. The runtime reads no environment variable for
@@ -123,15 +186,28 @@ it. The credential reaches the platform only when the runtime is constructed wit
 Intelligence client, and a runtime built without one compiles, serves, answers in a
 browser, and never touches the platform.
 
-Add this page to the selected documentation URLs for both subagents:
+Add these pages to the selected documentation URLs for the planning, implementation, and
+proof subagents:
 
 - https://docs.copilotkit.ai/premium/connect-your-runtime.md
+- https://docs.copilotkit.ai/backend/runtime-endpoints.md
+- https://docs.copilotkit.ai/premium/managed-intelligence-platform.md
+
+Fetch them together with the pages already selected rather than on their own.
 
-Fetch it together with the pages already selected rather than on its own.
+Spawn one planning subagent. Tell it to run
+`npx --yes copilotkit@4.9.17 onboard read subagent/create-plan` 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 repository findings, selected framework, frontend, model, credential
+variable names, selected documentation URLs, and documentation policy. On a conversion, also
+give it the frozen criterion. Give the planning subagent the updated protected path list.
+Wait for the subagent to finish.
 
-Spawn one planning subagent. Give it the full text of the planning brief at the end of this
-prompt, the repository findings, selected framework, frontend, model, credential variable
-names, and selected documentation URLs. Wait for the subagent to finish.
+Continue only if the planning result starts with `Status: passed`. For `Status: failed`,
+send the result back to the planning subagent for repair, up to three attempts. For
+`Status: blocked`, or a third failed result, use the unsupported route below. Do not show or
+ask for approval of a non-pass plan.
 
 Make sure that the plan preserves each part that already exists. The plan must name the
 credential variables, the Intelligence runtime wiring, the application the project asks
@@ -146,113 +222,7 @@ approve rather than in the implementation that follows. Do not upgrade a depende
 developer did not approve.
 
 If the developer approves the plan, run
-`npx --yes copilotkit@4.9.2 onboard read implementation/build-and-validate`.
+`npx --yes copilotkit@4.9.17 onboard read implementation/build-and-validate`.
 
 If no exact supported path or documentation URL exists, run
-`npx --yes copilotkit@4.9.2 onboard read unsupported/no-validated-path`.
-
-## Planning subagent brief
-
-Everything below the rule is the subagent's prompt. Give it verbatim.
-
----
-
-# Create the onboarding plan
-
-Use the selected framework, frontend, model, repository findings, and documentation URLs
-from the main coding agent. Fetch every selected URL in one step rather than one after
-another. Do not use remembered CopilotKit instructions.
-
-A fetch tool that refuses a URL, or fails to reach it, reports a limit of the tool and
-not a fact about the page. Retrieve the same URL a second way before you judge it. Run
-`curl -fsSL <url>`, or read the same page without the `.md` suffix. Report a
-documentation gap only after a second method also fails.
-
-Name the application the project asks for, and plan that application. Each documentation
-page teaches through one worked example, and that example carries a domain of its own.
-The domain belongs to the page. The project's purpose from the repository findings
-decides what gets built. Where the two differ, the project wins. Where the repository
-never states a purpose, say so in the plan and ask the developer before you adopt the
-domain of an example.
-
-Read only inside the project directory. Answer an API question from the documentation
-URLs you were given, not from another checkout on this machine.
-
-List the required credential variable names. Do not read or return credential values.
-Preserve each agent or frontend that already exists.
-
-Plan the runtime to consume the Intelligence credential. The runtime takes an
-`intelligence` option holding a client built from the project key. A runtime given a
-`runner` option instead is the OSS runtime. It never reads the Intelligence key, and the
-Inspector reads the project as locked. The default in-memory OSS runner is ephemeral.
-SQLite, custom, or framework persistence can be durable. The two options cannot be
-combined. Take the constructor from the connect-your-runtime page. Where a framework
-quickstart shows a `runner` option instead, the connect-your-runtime page wins.
-
-When the starting state is `both-oss`, use its recorded live baseline evidence. Preserve
-the working agent, frontend, CopilotKit integration, and OSS behavior. Plan the project
-selection, the CopilotKit dependency upgrade below, the Intelligence runtime
-configuration, and the authenticated proof needed for the conversion. Preserve the
-existing persistence and user-visible request. Do not rebuild a path that already works.
-
-Preserving the OSS baseline preserves the application, not its CopilotKit dependency
-versions. An install that predates the managed platform defaults carries a bundled
-reference naming hosts that route nothing, and it requires the platform URLs the same
-documentation calls optional. A run that reads that reference configures the runtime
-against a dead host, and the failure arrives as an empty-body 404 with no cause named.
-
-If any `@copilotkit/*` dependency is below 1.64.0, plan to upgrade every `@copilotkit/*`
-dependency to its latest published version. Packages that share a version line must end
-on the same version. Never force a package onto a version line it does not publish on.
-Resolve each latest version at run time rather than from a remembered version number.
-Where every `@copilotkit/*` dependency already meets that floor, plan no dependency
-change.
-
-Plan the upgrade as its own step before the Intelligence runtime wiring, and plan to
-re-run the recorded baseline checks immediately after it. Name the revert: restore the
-manifest and lockfile to their recorded state and stop, rather than wiring Intelligence
-onto a baseline the upgrade broke.
-
-Where the SDK requires an application-level value that the repository cannot supply, such
-as an end-user identity for threads, use one clearly marked local placeholder and name what
-production requires instead. Do not stop onboarding to ask the developer for it.
-
-Check whether the existing agent performs unattended side effects, such as paging, sending
-notifications, writing to an external system, or creating tickets. If it does, the new
-conversational surface must not trigger them. Wrap only the reasoning steps, or require an
-explicit developer confirmation before the side effect can run. Name each side effect you
-found and state how the plan avoids it.
-
-If the value of the journey depends on data the project already holds, name that data,
-name where it lives, and name how it reaches the agent. Rendering a list in the DOM does
-not give the agent access to it. An agent wired without the page's data answers from
-entities it invents, and the answer looks correct. Take the frontend-context step from
-the selected documentation. Where no selected page documents it for this framework or
-frontend, record that as a documentation gap rather than guessing the API.
-
-Where that data exists, name the entities the proof compares against: the ids, names, or
-records the project holds and the answer has to reference. Where the outcome references
-no project data, say so in the plan, so that the proof asks for evidence this journey can
-produce.
-
-Create one plan for implementation, validation, and proof. Name each file or area that can
-change. Name the commands that can validate the result.
-Name the commands or user path that prove a real generative-UI round trip.
-
-Keep a production build out of the validation commands. A type check plus the real round
-trip is the proof, and the round trip runs in development mode. Name the production build
-as a follow-up for the developer instead. Never raise a bundle budget or relax a lint rule
-to make a build pass during onboarding.
-
-The type check runs against the project's own configuration. If the project has no
-type-check command, add one that uses the configuration the project already has.
-Do not add compiler strictness the project did not have. Nothing later in the run is
-allowed to weaken type safety, so a stricter gate named here is one the run cannot get
-back out of.
-
-Gather what you need in as few commands as possible. Combine independent reads into one
-command rather than running them one at a time. Split a command only when its result decides
-what you run next.
-
-Return the plan, the URLs that you read, and each documentation gap. Stop after you return
-the findings to the main coding agent.
+`npx --yes copilotkit@4.9.17 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/credentials/plan.md

@@ -4,11 +4,23 @@ Use the repository findings to select the agent framework. Ask the developer onl
 choices that the repository does not show. Do not change application code in this phase.
 Do not read, show, store, or request a secret value.
 
+Keep `CPK_INTELLIGENCE_API_KEY` separate from every model-vendor credential. Do not read,
+show, store, or copy either credential.
+
+This documentation policy applies to every framework and frontend route below. Deduplicate
+the selected URL list and fetch each URL once. Fetch all selected URLs in one step. Do not
+use remembered CopilotKit instructions. A fetch tool that refuses a URL, or fails to reach
+it, reports a limit of the tool and not a fact about the page. Retrieve the same URL a
+second way before you judge it. Run `curl -fsSL <url>`, or read the same page without the
+`.md` suffix. Treat a page as unavailable only after a second method also fails. Give this
+policy to every documentation subagent. A page that is still unavailable after the second
+method does not support the selection.
+
 Use a gentle wizard. Ask one short question at a time. Do not combine separate choices in
 one question. Put the recommendation first, give its evidence in one sentence, and keep
-the alternatives short. When the framework is unknown, ask only whether to use the
-recommended framework. If the developer declines it, ask one follow-up question that lists
-the valid framework choices. Do not ask about the frontend, model, or project in this step.
+the alternatives short. When the framework is unknown, use this rule: Ask one framework
+question that lists the recommendation and valid choices. Do not ask a yes-or-no question
+first. Do not ask about the frontend, model, or project in this step.
 
 These are the agent frameworks and their default vendors:
 
@@ -27,13 +39,18 @@ These are the agent frameworks and their default vendors:
 | LangGraph TypeScript               | OpenAI          |
 | LlamaIndex                         | OpenAI          |
 | Mastra                             | OpenAI          |
-| Microsoft Agent Framework (.NET)   | GitHub Models   |
+| Microsoft Agent Framework (.NET)   | OpenAI          |
 | Microsoft Agent Framework (Python) | OpenAI          |
-| MS Agent Harness (.NET)            | GitHub Models   |
+| MS Agent Harness (.NET)            | OpenAI          |
 | Pydantic AI                        | OpenAI          |
 | Strands Agents (Python)            | OpenAI          |
 | Strands Agents (TypeScript)        | OpenAI          |
 
+"Project-defined" is not a missing default. It means that framework's own route settles
+the vendor with the developer: it keeps the one the repository already uses, and asks a
+single question when the repository shows none. Do not read it as a framework this release
+cannot onboard.
+
 If the project already has an agent in a listed framework, preserve that framework and
 its model setup. Ask only about choices that remain unknown.
 
@@ -51,26 +68,26 @@ another framework. Do not show the internal route.
 
 Use exactly one matching internal route:
 
-1. AG2: `npx --yes copilotkit@4.9.2 onboard read framework/ag2`
-2. Agno: `npx --yes copilotkit@4.9.2 onboard read framework/agno`
-3. Built-in CopilotKit agent: `npx --yes copilotkit@4.9.2 onboard read framework/built-in`
-4. Claude Agent SDK Python: `npx --yes copilotkit@4.9.2 onboard read framework/claude-sdk-python`
-5. Claude Agent SDK TypeScript: `npx --yes copilotkit@4.9.2 onboard read framework/claude-sdk-typescript`
-6. CrewAI Flows: `npx --yes copilotkit@4.9.2 onboard read framework/crewai-flows`
-7. Deep Agents: `npx --yes copilotkit@4.9.2 onboard read framework/deep-agents`
-8. LangGraph Python: `npx --yes copilotkit@4.9.2 onboard read framework/langgraph-python`
-9. LangGraph FastAPI: `npx --yes copilotkit@4.9.2 onboard read framework/langgraph-fastapi`
-10. LangGraph TypeScript: `npx --yes copilotkit@4.9.2 onboard read framework/langgraph-typescript`
-11. LlamaIndex: `npx --yes copilotkit@4.9.2 onboard read framework/llamaindex`
-12. ADK: `npx --yes copilotkit@4.9.2 onboard read framework/google-adk`
-13. Microsoft Agent Framework Python: `npx --yes copilotkit@4.9.2 onboard read framework/ms-agent-python`
-14. Microsoft Agent Framework .NET: `npx --yes copilotkit@4.9.2 onboard read framework/ms-agent-dotnet`
-15. Mastra: `npx --yes copilotkit@4.9.2 onboard read framework/mastra`
-16. MS Agent Harness .NET: `npx --yes copilotkit@4.9.2 onboard read framework/ms-agent-harness-dotnet`
-17. Pydantic AI: `npx --yes copilotkit@4.9.2 onboard read framework/pydantic-ai`
-18. Strands Agents Python: `npx --yes copilotkit@4.9.2 onboard read framework/strands-python`
-19. Strands Agents TypeScript: `npx --yes copilotkit@4.9.2 onboard read framework/strands-typescript`
+1. AG2: `npx --yes copilotkit@4.9.17 onboard read framework/ag2`
+2. Agno: `npx --yes copilotkit@4.9.17 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --yes copilotkit@4.9.17 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --yes copilotkit@4.9.17 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --yes copilotkit@4.9.17 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --yes copilotkit@4.9.17 onboard read framework/crewai-flows`
+7. Deep Agents: `npx --yes copilotkit@4.9.17 onboard read framework/deep-agents`
+8. LangGraph Python: `npx --yes copilotkit@4.9.17 onboard read framework/langgraph-python`
+9. LangGraph FastAPI: `npx --yes copilotkit@4.9.17 onboard read framework/langgraph-fastapi`
+10. LangGraph TypeScript: `npx --yes copilotkit@4.9.17 onboard read framework/langgraph-typescript`
+11. LlamaIndex: `npx --yes copilotkit@4.9.17 onboard read framework/llamaindex`
+12. ADK: `npx --yes copilotkit@4.9.17 onboard read framework/google-adk`
+13. Microsoft Agent Framework Python: `npx --yes copilotkit@4.9.17 onboard read framework/ms-agent-python`
+14. Microsoft Agent Framework .NET: `npx --yes copilotkit@4.9.17 onboard read framework/ms-agent-dotnet`
+15. Mastra: `npx --yes copilotkit@4.9.17 onboard read framework/mastra`
+16. MS Agent Harness .NET: `npx --yes copilotkit@4.9.17 onboard read framework/ms-agent-harness-dotnet`
+17. Pydantic AI: `npx --yes copilotkit@4.9.17 onboard read framework/pydantic-ai`
+18. Strands Agents Python: `npx --yes copilotkit@4.9.17 onboard read framework/strands-python`
+19. Strands Agents TypeScript: `npx --yes copilotkit@4.9.17 onboard read framework/strands-typescript`
 
 If the project has an agent in another framework, or no listed framework fits, keep the
 developer's current agent and run
-`npx --yes copilotkit@4.9.2 onboard read unsupported/no-validated-path`.
+`npx --yes copilotkit@4.9.17 onboard read unsupported/no-validated-path`.

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

@@ -1,36 +1,127 @@
 # Build from the best available official documentation
 
-Tell the implementation subagent which plan steps lack direct documentation. Give it the
-approved plan, repository findings, and all official documentation that you found.
+Work only in the target project directory. Do not read, show, store, or request a secret
+value.
 
-Tell the subagent to preserve the existing project. It must not invent a CopilotKit API.
-It can combine compatible APIs from different official pages when one page omits the
-selected framework and frontend combination.
+This fallback contains unproved steps. Use the approved plan in step order.
 
-Run the approved implementation and validation steps. Repair a failure in new work at most
-three times. Stop if the fix requires changes to the developer's existing agent or
-frontend.
+## If you stop in this fallback
 
-After validation passes, prove the runtime, agent round trip, and real frontend path. Use
-the same proof rules from the approved plan. Keep the development servers running after
-proof.
+Several rules below stop onboarding: a blocked or third failed implementation result, a
+changed protected path, a blocked or third failed proof, a fix that needs changes to the
+existing agent or frontend. Send one short report before you stop. Run the feedback
+command without another developer question. The CLI telemetry gate decides whether the
+report is sent.
 
-Do not block core proof on CopilotKit Skills or MCP configuration. Try these tools after
-the application passes proof. Report each tool result separately.
+```text
+npx --yes copilotkit@4.9.17 onboard feedback
+```
+
+Write at most four lines to standard input: the step you stopped at and what stopped it.
+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 the way the rule that stopped you says to. This fallback
+runs because the documentation already fell short once, so a stop inside it is the second
+gap in the same run and neither is recorded anywhere else.
+
+Spawn one implementation subagent. Give it the approved plan, repository findings, and
+target project directory. Tell it which steps lack direct documentation. Give it all
+official documentation that you fetched for the plan. Give it the protected path list.
+Give it these rules:
+
+- Preserve the existing project.
+- Change only the paths the approved plan names.
+- Do not change a protected path or an overlapping path.
+- Do not invent a CopilotKit API.
+- Do not read, show, store, or return secret values.
+
+When one page omits the selected framework and frontend combination, combine compatible APIs
+from different official pages. Tell it to run every implementation and validation step in
+plan order, and to run the full validation list.
+
+Give it this result format: Start with `Status: passed`, `Status: failed`, or
+`Status: blocked`.
+
+Wait for the implementation subagent to finish.
+
+Use these rules for the implementation result:
+
+1. For `Status: passed`, keep the result.
+2. For `Status: failed`, retry the same subagent with its evidence. Make at most three attempts.
+3. For `Status: blocked`, stop onboarding. Report the blocker.
+
+After a third failed result, stop. When a fix needs changes to the existing agent or frontend,
+stop.
+
+Use these rules for every protected-path check in this fallback:
+
+- Run `npx --yes copilotkit@4.9.17 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, stop onboarding.
+- Never repair, reset, or revert a protected path.
+
+Run the protected-path check now. Apply the protected-path rules. Continue only when the
+audit starts with `Status: passed`.
+
+After validation passes, use this rule: Spawn one proof subagent. Give it the complete ordered
+proof rules from the approved plan, validation evidence, project directory, all official
+documentation that you fetched for the plan, and recorded browser or device control. Require
+the runtime, agent round trip, and real frontend proof. Keep the development servers running.
+Give the proof subagent the protected path list.
+Tell the proof subagent not to write a path that overlaps a protected path.
+Tell it not to read, show, store, or return secret values. During proof, do not edit source
+files, configuration files, dependencies, or tracked files. Allow only operational repairs
+to project-owned processes, ports, and request options.
+Require this result format: Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
+Tell it to use `Status: passed` only when the proof attempt completed with `performed`,
+`skipped-no-browser-tool`, or `skipped-no-device`. Use `Status: failed` for any failed proof
+step. Use `Status: blocked` when a safety or access limit stops the attempt before a surface
+outcome.
+Wait for the proof subagent to finish. For `Status: blocked`, stop onboarding and report the
+blocker. For `Status: failed`, classify the cause before retrying.
+
+Retry the proof worker only for a project-owned process, port, or request-option failure.
+Give it the failure evidence and wait after each attempt. Stop after three failed attempts.
+
+For a source, configuration, dependency, or tracked-file defect, send the evidence to the
+implementation subagent. Require the repair and full validation. Wait for the repair to
+finish. Continue only if its result starts with `Status: passed`. For a failed repair,
+retry that worker with its evidence, up to three attempts. For a blocked or third failed
+repair, stop onboarding and report the blocker. Run the protected-path check after the repair
+passes. Apply the protected-path rules before you continue. After repair, full validation,
+and the protected-path check pass, spawn a fresh proof subagent. Give it the full original
+proof handoff, failed proof evidence, and new validation evidence. The handoff includes the
+protected path list. Wait for the fresh proof subagent and apply the same proof-result rules.
+Continue only if the proof result starts with `Status: passed`.
+
+Run the protected-path check again after the final proof result passes. Apply the
+protected-path rules. Continue only if the audit starts with `Status: passed`.
+
+Do not block core proof on CopilotKit Skills or MCP configuration. Tell the developer that
+the skills install writes a `.agents/skills` directory and `.claude/skills` links into the
+working tree before you run it, because both show up in `git status` and this run cannot
+know whether the project keeps them in version control. Try these tools after the
+application passes proof. Report each tool result separately from the proof result.
 
 Report the documentation gap and each assumption with the proof evidence. Do not claim
 that the selected documentation proved an inferred step.
 
-When the proof is complete, run `npx --yes copilotkit@4.9.2 onboard complete`, carrying the
+When the proof is complete, run `npx --yes copilotkit@4.9.17 onboard complete`, carrying the
 surface-check result the proof subagent returned. Pass exactly one flag, matching this
 journey's surface:
 
 ```text
-npx --yes copilotkit@4.9.2 onboard complete --visual-check <outcome>
-npx --yes copilotkit@4.9.2 onboard complete --device-check <outcome>
+npx --yes copilotkit@4.9.17 onboard complete --visual-check <outcome>
+npx --yes copilotkit@4.9.17 onboard complete --device-check <outcome>
 ```
 
 `--visual-check` is for a web frontend and takes `performed`, `skipped-no-browser-tool`, or
 `failed`. `--device-check` is for React Native and takes `performed`, `skipped-no-device`,
 or `failed`. Anything but `performed` ends this run as blocked, and the command's output
 names the evidence that is missing. Report it that way.
+
+If the proof passed and something after it still blocked this run, add
+`--blocked-by <cause>` to the same command, with one of `hosted-dashboard`, `inspector`,
+`plan-excluded-capability`, or `other`. It ends the run as blocked and names what the
+blocker leaves unverified.

package/onboarding/prompts/framework/ag2.md

@@ -6,43 +6,32 @@ credential variables and setup steps.
 
 Name the default model credential `OPENAI_API_KEY`.
 
-Keep `INTELLIGENCE_API_KEY` separate from model-vendor credentials. Do not read, show,
-store, or request a secret value.
-
 ## Documentation
 
 - https://docs.copilotkit.ai/ag2/quickstart.md
 - https://docs.copilotkit.ai/ag2/inspector.md
-- https://docs.copilotkit.ai/ag2/generative-ui/a2ui/fixed-schema.md
+- https://docs.copilotkit.ai/ag2/generative-ui/tool-based.md
 - https://docs.copilotkit.ai/ag2/readables.md
 
-Fetch all four pages in one step rather than one after another.
-
 The documentation scope is `ag2`. Use only the Python examples from these pages.
 Preserve the existing `AGUIStream` endpoint and its route. The quickstart uses a sample
 repository with `uv sync`. It does not name a dependency list for an existing project.
 Do not replace the project's dependency manifest with a guessed list, and do not change
 an existing endpoint to the quickstart's `/weather` sample route.
 
-The fixed-schema page has no AG2 backend schema-loading, render-operations, or runtime
-setup snippet. Do not invent a fixed-schema A2UI backend setup. If the requested work
-needs that missing setup, run the unsupported route below.
+A2UI is not on this path. If the developer asks for it, say first that its page has no AG2
+backend schema-loading, render-operations, or runtime setup snippet, so there is nothing to
+follow for the backend half.
 
 The Readables page includes the AG2 backend context path. Use its `ContextVariables` and
 `AGUIStream` examples when the project needs frontend context. Do not substitute another
 framework's context setup.
 
 Record the selected framework, vendor, model, required credential variable names, these
-URLs, and the fixed-schema documentation gap. Do not use remembered CopilotKit
-instructions.
-
-A fetch tool that refuses a URL, or fails to reach it, reports a limit of the tool and
-not a fact about the page. Retrieve the same URL a second way before you judge it. Run
-`curl -fsSL <url>`, or read the same page without the `.md` suffix. Treat a page as
-unavailable only after a second method also fails.
+URLs, and the A2UI documentation gap.
 
 If the pages support the selection, run
-`npx --yes copilotkit@4.9.2 onboard read frontend/plan`.
+`npx --yes copilotkit@4.9.17 onboard read frontend/plan`.
 
-If a second method also fails, or a page that loads does not support the selection, run
-`npx --yes copilotkit@4.9.2 onboard read unsupported/no-validated-path`.
+If the documentation does not support the selection, run
+`npx --yes copilotkit@4.9.17 onboard read unsupported/no-validated-path`.