copilotkit 4.8.3 → 4.9.0

package/onboarding/index.json

@@ -3,7 +3,7 @@
   "prompts": [
     {
       "edges": [
-        "subagent/inspect-repository",
+        "proof/oss-baseline",
         "credentials/plan",
         "unsupported/no-validated-path"
       ],
@@ -12,7 +12,6 @@
     },
     {
       "edges": [
-        "subagent/create-plan",
         "implementation/build-and-validate",
         "unsupported/no-validated-path"
       ],
@@ -21,30 +20,35 @@
     },
     {
       "edges": [
+        "framework/ag2",
+        "framework/agno",
         "framework/built-in",
+        "framework/claude-sdk-python",
+        "framework/claude-sdk-typescript",
+        "framework/crewai-flows",
         "framework/deep-agents",
         "framework/langgraph-python",
         "framework/langgraph-fastapi",
         "framework/langgraph-typescript",
+        "framework/llamaindex",
         "framework/google-adk",
-        "framework/strands-python",
-        "framework/strands-typescript",
-        "framework/mastra",
-        "framework/claude-sdk-python",
-        "framework/claude-sdk-typescript",
-        "framework/pydantic-ai",
         "framework/ms-agent-python",
         "framework/ms-agent-dotnet",
+        "framework/mastra",
         "framework/ms-agent-harness-dotnet",
-        "framework/ag2",
-        "framework/agno",
-        "framework/llamaindex",
-        "framework/crewai-flows",
+        "framework/pydantic-ai",
+        "framework/strands-python",
+        "framework/strands-typescript",
         "unsupported/no-validated-path"
       ],
       "milestone": "credentials",
       "name": "credentials/plan"
     },
+    {
+      "edges": [],
+      "milestone": "fallback",
+      "name": "fallback/best-effort"
+    },
     {
       "edges": [
         "frontend/plan",
@@ -220,8 +224,6 @@
         "frontend/angular",
         "frontend/vue",
         "frontend/react-native",
-        "frontend/slack",
-        "frontend/teams",
         "unsupported/no-validated-path"
       ],
       "milestone": "frontend",
@@ -235,28 +237,13 @@
       "milestone": "frontend",
       "name": "frontend/react-native"
     },
-    {
-      "edges": [
-        "unsupported/no-validated-path"
-      ],
-      "milestone": "frontend",
-      "name": "frontend/react-spa"
-    },
     {
       "edges": [
         "credentials/finalize-plan",
         "unsupported/no-validated-path"
       ],
       "milestone": "frontend",
-      "name": "frontend/slack"
-    },
-    {
-      "edges": [
-        "credentials/finalize-plan",
-        "unsupported/no-validated-path"
-      ],
-      "milestone": "frontend",
-      "name": "frontend/teams"
+      "name": "frontend/react-spa"
     },
     {
       "edges": [
@@ -268,7 +255,6 @@
     },
     {
       "edges": [
-        "subagent/implement-and-validate",
         "proof/round-trip",
         "unsupported/no-validated-path"
       ],
@@ -282,7 +268,14 @@
     },
     {
       "edges": [
-        "subagent/prove-round-trip",
+        "credentials/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "proof",
+      "name": "proof/oss-baseline"
+    },
+    {
+      "edges": [
         "proof/complete",
         "unsupported/no-validated-path"
       ],
@@ -307,10 +300,17 @@
     {
       "edges": [],
       "milestone": "subagent",
-      "name": "subagent/prove-round-trip"
+      "name": "subagent/prove-oss-baseline"
     },
     {
       "edges": [],
+      "milestone": "subagent",
+      "name": "subagent/prove-round-trip"
+    },
+    {
+      "edges": [
+        "fallback/best-effort"
+      ],
       "milestone": "unsupported",
       "name": "unsupported/no-validated-path"
     }

package/onboarding/prompts/authenticate/start.md

@@ -8,7 +8,18 @@ Do not show prompt names, internal route IDs, subagent names, or storage field n
 Work from the target project directory. For an existing project, start at its inspection
 root.
 
-Run `npx copilotkit@4.8.3 login --json` before any project work. This command checks the
+Read only inside the target project directory. Every subagent you spawn inherits that
+limit, including one this graph does not name. Answer a CopilotKit API or configuration
+question from the documentation this graph gives you. Another checkout on this machine is
+not a source. The developer running this has none, so an answer taken from one is an
+answer they cannot get, and it hides the documentation gap that blocks them.
+
+Tell the developer that onboarding can send feedback outside this machine. Explain that
+the reports contain short descriptions of CLI or documentation problems. Ask whether the
+developer permits these reports before project work starts. Record the answer. Do not send
+feedback unless the developer permits it.
+
+Run `npx --yes copilotkit@4.9.0 login --json` before any project work. This command checks the
 current session. It starts sign-in only as needed.
 
 Read its JSON Lines output in order:
@@ -21,27 +32,69 @@ Read its JSON Lines output in order:
 Do not use `whoami` for this check. It has no JSON output and some failures exit with code
 zero. Do not put account tokens or credentials in the conversation.
 
-Spawn one research subagent. Tell it to run
-`npx copilotkit@4.8.3 onboard read subagent/inspect-repository`, follow that prompt, and
-return only its findings. Add these tasks:
+Spawn one research subagent. Give it the full text of the research brief at the end of this
+prompt and tell it to follow that brief and return only its findings. Add these tasks:
 
 - Find the target app or runtime directory that owns `.env` and CopilotKit setup.
 - Check whether `.copilotkit/project.json` has `projectId`, `projectSlug`, and `clerkOrgId`.
 - Check whether `.env` has a non-empty `INTELLIGENCE_API_KEY` entry.
 - Record the `.env` file modification time without returning it.
+- Report whether an agent, frontend, and CopilotKit integration are present.
+- Report whether the runtime constructor uses a `runner` option, an `intelligence`
+  option, or neither can be proved from project files.
 
 Do not print either file or any secret value. Return only paths, presence checks, and missing
 field names. Wait for the subagent to finish.
 
+If the findings show an empty project and do not prove its purpose, ask what the developer
+wants to build before you select a framework. Ask this question immediately. Record the
+answer and give it to each later subagent.
+
 If a repository file exists, each finding must cite it. For an empty project, the subagent
 must cite its directory check and report absent parts.
 
-The findings must cover the agent, frontend, CopilotKit setup, authentication,
-credential names, and validation path. Do not ask the developer for facts that the
-repository answers.
+The findings must cover what the project is for, the agent, frontend, CopilotKit setup,
+authentication, credential names, and validation path. Do not ask the developer for facts
+that the repository answers.
+
+Do not infer a working OSS path from packages, imports, project files, or keys. If an
+agent, frontend, and CopilotKit integration are present, prove the live starting state
+before any project file changes. Run
+`npx --yes copilotkit@4.9.0 onboard read proof/oss-baseline`.
 
-When the evidence is complete, run
-`npx copilotkit@4.8.3 onboard read credentials/plan`.
+For every other inspected state, run
+`npx --yes copilotkit@4.9.0 onboard read credentials/plan`.
 
 If authentication or inspection stops onboarding, run
-`npx copilotkit@4.8.3 onboard read unsupported/no-validated-path`.
+`npx --yes copilotkit@4.9.0 onboard read unsupported/no-validated-path`.
+
+## Research subagent brief
+
+Everything below the rule is the subagent's prompt. Give it verbatim.
+
+---
+
+# Inspect the repository
+
+Inspect the repository without changing it. Find evidence for:
+
+- what the project is for, in the project's own words
+- any existing agent framework
+- any existing frontend
+- current CopilotKit packages and configuration
+- authentication boundaries
+- names of required credential variables, without reading their values
+
+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
+empty project carries it in the README alone, and that makes the README the whole of the
+evidence. State the purpose as unproved when the project never says.
+
+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 file paths and a short finding for each item. State each absent or unproved item.
+Do not read, print, or return secret values. 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.

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

@@ -17,15 +17,49 @@ 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 the developer needs a project or another project, use the target directory. Tell them
-to run `npx copilotkit@4.8.3 project select` from an interactive terminal in that
-directory. This command lets the developer select or create an Intelligence project.
+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.
 
-End the turn and ask the developer to return the command's final status lines. Tell them to
-remove any secret before replying. Resume only after they reply.
+Read the choices first:
 
-If the output includes `Could not provision a project-scoped API key` or another error,
-stop onboarding.
+```text
+npx --yes copilotkit@4.9.0 project list --json
+```
+
+With `--json` the payload is the only thing on standard output, so it is safe to parse.
+Show the current selection and the five most recent projects. Sort recency by `createdAt`.
+Offer search, create-new, and list-all options. Do not show every project unless the
+developer asks.
+
+If the developer searches, run:
+
+```text
+npx --yes copilotkit@4.9.0 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. Ask this with the frontend and model
+choices when those choices remain unknown.
+
+Then record their answer, from the target directory:
+
+```text
+npx --yes copilotkit@4.9.0 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.
+
+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:
@@ -39,19 +73,138 @@ 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.
 
-Spawn one planning subagent. Tell it to run
-`npx copilotkit@4.8.3 onboard read subagent/create-plan`. Give it the repository findings,
-selected framework, frontend, model, credential variable names, and selected documentation
-URLs. Wait for the subagent to finish.
+## Where a model credential comes from
+
+The plan names the model credential variables. Finding their values is not its job.
+
+If the project has no value for one, ask the developer where it lives. Never read a file
+outside the project directory to find one. A key found that way belongs to another
+project: it bills that project for these model calls, points attribution at a project
+nobody chose, and leaves no trace, because the scaffold works.
+
+Asking where a credential lives is not requesting a secret value. Ask for a path, or ask
+the developer to write the value into the project's env file themselves. A path the
+developer names is theirs to give, including one outside the project. A path this run
+finds is not.
+
+If no answer comes, stop. Do not write a placeholder or an empty value. A scaffold
+carrying a dummy key looks finished and fails at the first model call, which is worse
+than stopping here.
+
+## Wire the runtime to Intelligence
+
+The key in `.env` does nothing on its own. The runtime reads no environment variable for
+it. The credential reaches the platform only when the runtime is constructed with an
+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:
+
+- https://docs.copilotkit.ai/premium/connect-your-runtime.md
+
+Fetch it together with the pages already selected rather than on its own.
+
+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.
 
 Make sure that the plan preserves each part that already exists. The plan must name the
-credential variables, implementation steps, validation steps, and proof steps. It must not
-contain secret values.
+credential variables, the Intelligence runtime wiring, the application the project asks
+for, implementation steps, validation steps, and proof steps. It must not contain secret
+values.
 
 Show only the selected framework, frontend, model, planned file changes, validation commands, and proof steps.
 
 If the developer approves the plan, run
-`npx copilotkit@4.8.3 onboard read implementation/build-and-validate`.
+`npx --yes copilotkit@4.9.0 onboard read implementation/build-and-validate`.
 
 If no exact supported path or documentation URL exists, run
-`npx copilotkit@4.8.3 onboard read unsupported/no-validated-path`.
+`npx --yes copilotkit@4.9.0 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 only the
+project selection, Intelligence runtime configuration, and authenticated proof needed for
+the conversion. Preserve the existing persistence and user-visible request. Do not
+rebuild a path that already works.
+
+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.

package/onboarding/prompts/credentials/plan.md

@@ -4,61 +4,67 @@ 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.
 
-If the project has an agent, preserve its framework and model setup. Use the matching route
-below. Ask only about choices that remain unknown.
+These are the agent frameworks and their default vendors:
 
-If the project needs an agent, run
-`npx copilotkit@4.8.3 framework list --json`. The command returns every CLI framework ID.
-It has no ownership or stability field.
+| Framework                          | Default vendor  |
+| ---------------------------------- | --------------- |
+| AG2                                | OpenAI          |
+| ADK                                | Google          |
+| Agno                               | OpenAI          |
+| Built-in CopilotKit agent          | OpenAI          |
+| Claude Agent SDK (Python)          | Anthropic       |
+| Claude Agent SDK (TypeScript)      | Anthropic       |
+| CrewAI Flows                       | Project-defined |
+| Deep Agents                        | OpenAI          |
+| LangGraph FastAPI                  | OpenAI          |
+| LangGraph Python                   | OpenAI          |
+| LangGraph TypeScript               | OpenAI          |
+| LlamaIndex                         | OpenAI          |
+| Mastra                             | OpenAI          |
+| Microsoft Agent Framework (.NET)   | GitHub Models   |
+| Microsoft Agent Framework (Python) | OpenAI          |
+| MS Agent Harness (.NET)            | GitHub Models   |
+| Pydantic AI                        | OpenAI          |
+| Strands Agents (Python)            | OpenAI          |
+| Strands Agents (TypeScript)        | OpenAI          |
 
-Offer these first-party CLI-backed options:
+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.
 
-| Framework                        | Default vendor |
-| -------------------------------- | -------------- |
-| LangGraph Python                 | OpenAI         |
-| LangGraph TypeScript             | OpenAI         |
-| Google ADK                       | Google         |
-| AWS Strands Python               | OpenAI         |
-| Mastra                           | OpenAI         |
-| Claude Agent SDK Python          | Anthropic      |
-| Claude Agent SDK TypeScript      | Anthropic      |
-| PydanticAI                       | OpenAI         |
-| Microsoft Agent Framework Python | OpenAI         |
-| Microsoft Agent Framework .NET   | GitHub Models  |
-| Agno                             | OpenAI         |
-| LlamaIndex                       | OpenAI         |
+If the project needs an agent, show the options and one recommendation based on repository
+evidence. Match the language the repository already uses. Ask the developer to choose.
 
-Do not offer AG2 as a first-party choice. Its starter tracks third-party code from a moving
-branch. CrewAI Flows needs an existing CrewAI Enterprise agent. If the repository uses
-either framework, preserve it.
+If the project is empty, state that no repository-based recommendation exists. Give these
+documented defaults: LangGraph TypeScript, LangGraph Python, ADK, Microsoft Agent Framework
+Python, Microsoft Agent Framework .NET, and Mastra. Explain which default matches the
+developer's stated purpose. Show the other listed frameworks as options. Do not describe a
+documented default as a repository-based recommendation.
 
-Do not offer A2A, A2UI, MCP Apps, Open Generative UI, AgentCore, or `adk-angular` as agent
-frameworks. They are protocols, deployment targets, tools, or combined starters.
-
-Show the public options and one recommendation based on repository evidence. If the
-repository has no agent, ask the developer to choose. Do not show the internal route.
+Do not offer a framework that is not listed above. Do not port an existing agent to
+another framework. Do not show the internal route.
 
 Use exactly one matching internal route:
 
-1. Built-in: `npx copilotkit@4.8.3 onboard read framework/built-in`
-2. Deep Agents: `npx copilotkit@4.8.3 onboard read framework/deep-agents`
-3. LangGraph Python: `npx copilotkit@4.8.3 onboard read framework/langgraph-python`
-4. LangGraph FastAPI: `npx copilotkit@4.8.3 onboard read framework/langgraph-fastapi`
-5. LangGraph TypeScript: `npx copilotkit@4.8.3 onboard read framework/langgraph-typescript`
-6. Google ADK: `npx copilotkit@4.8.3 onboard read framework/google-adk`
-7. AWS Strands Python: `npx copilotkit@4.8.3 onboard read framework/strands-python`
-8. AWS Strands TypeScript: `npx copilotkit@4.8.3 onboard read framework/strands-typescript`
-9. Mastra: `npx copilotkit@4.8.3 onboard read framework/mastra`
-10. Claude Agent SDK Python: `npx copilotkit@4.8.3 onboard read framework/claude-sdk-python`
-11. Claude Agent SDK TypeScript: `npx copilotkit@4.8.3 onboard read framework/claude-sdk-typescript`
-12. PydanticAI: `npx copilotkit@4.8.3 onboard read framework/pydantic-ai`
-13. Microsoft Agent Framework Python: `npx copilotkit@4.8.3 onboard read framework/ms-agent-python`
-14. Microsoft Agent Framework .NET: `npx copilotkit@4.8.3 onboard read framework/ms-agent-dotnet`
-15. Microsoft Agent Framework Harness .NET: `npx copilotkit@4.8.3 onboard read framework/ms-agent-harness-dotnet`
-16. AG2: `npx copilotkit@4.8.3 onboard read framework/ag2`
-17. Agno: `npx copilotkit@4.8.3 onboard read framework/agno`
-18. LlamaIndex: `npx copilotkit@4.8.3 onboard read framework/llamaindex`
-19. CrewAI Flows: `npx copilotkit@4.8.3 onboard read framework/crewai-flows`
+1. AG2: `npx --yes copilotkit@4.9.0 onboard read framework/ag2`
+2. Agno: `npx --yes copilotkit@4.9.0 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --yes copilotkit@4.9.0 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --yes copilotkit@4.9.0 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --yes copilotkit@4.9.0 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --yes copilotkit@4.9.0 onboard read framework/crewai-flows`
+7. Deep Agents: `npx --yes copilotkit@4.9.0 onboard read framework/deep-agents`
+8. LangGraph Python: `npx --yes copilotkit@4.9.0 onboard read framework/langgraph-python`
+9. LangGraph FastAPI: `npx --yes copilotkit@4.9.0 onboard read framework/langgraph-fastapi`
+10. LangGraph TypeScript: `npx --yes copilotkit@4.9.0 onboard read framework/langgraph-typescript`
+11. LlamaIndex: `npx --yes copilotkit@4.9.0 onboard read framework/llamaindex`
+12. ADK: `npx --yes copilotkit@4.9.0 onboard read framework/google-adk`
+13. Microsoft Agent Framework Python: `npx --yes copilotkit@4.9.0 onboard read framework/ms-agent-python`
+14. Microsoft Agent Framework .NET: `npx --yes copilotkit@4.9.0 onboard read framework/ms-agent-dotnet`
+15. Mastra: `npx --yes copilotkit@4.9.0 onboard read framework/mastra`
+16. MS Agent Harness .NET: `npx --yes copilotkit@4.9.0 onboard read framework/ms-agent-harness-dotnet`
+17. Pydantic AI: `npx --yes copilotkit@4.9.0 onboard read framework/pydantic-ai`
+18. Strands Agents Python: `npx --yes copilotkit@4.9.0 onboard read framework/strands-python`
+19. Strands Agents TypeScript: `npx --yes copilotkit@4.9.0 onboard read framework/strands-typescript`
 
-If no listed framework fits, run
-`npx copilotkit@4.8.3 onboard read unsupported/no-validated-path`.
+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.0 onboard read unsupported/no-validated-path`.

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

@@ -0,0 +1,29 @@
+# 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.
+
+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.
+
+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.
+
+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.
+
+Do not block core proof on CopilotKit Skills or MCP configuration. Try these tools after
+the application passes proof. Report each tool result separately.
+
+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.0 onboard complete`, carrying the
+visual-check result:
+
+```text
+npx --yes copilotkit@4.9.0 onboard complete --visual-check <outcome>
+```

package/onboarding/prompts/framework/ag2.md

@@ -1,7 +1,10 @@
 # Configure AG2
 
-If the repository uses AG2, preserve it. Do not recommend it for a new agent. Its starter
-tracks third-party code from a moving branch. Preserve its model vendor and model setup.
+Preserve an existing AG2 model setup. Start with OpenAI for a new agent. Offer another
+vendor only after an exact CopilotKit Markdown page names it. The page must name its
+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.
@@ -11,12 +14,35 @@ store, or request a secret value.
 - 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/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.
+
+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.
 
-Fetch all three pages. Record the selected framework, vendor, model, required credential
-variable names, and these URLs. 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.
 
 If the pages support the selection, run
-`npx copilotkit@4.8.3 onboard read frontend/plan`.
+`npx --yes copilotkit@4.9.0 onboard read frontend/plan`.
 
-If a page does not load or support the selection, run
-`npx copilotkit@4.8.3 onboard read unsupported/no-validated-path`.
+If a second method also fails, or a page that loads does not support the selection, run
+`npx --yes copilotkit@4.9.0 onboard read unsupported/no-validated-path`.