copilotkit 4.25.1 → 4.27.0

package/onboarding/prompts/setup/questions.md

@@ -1,211 +1,246 @@
 # Ask the setup questions together
 
-The route is chosen. This node asks, in one message, every setup choice that the findings
-and the developer's request do not settle. The developer answers once, and the run then
-goes on without them until the plan is ready for approval. Do not change application code
-in this phase. Do not read, show, store, or request a secret value.
+Do not change application code in this phase. Do not read, show, store, or request a secret value.
 
 ## Settle what the findings already answer
 
 Do not ask the developer for a fact that the repository or their request answers.
 
 - If the project already has an agent in a listed framework, keep that framework and its
-  model setup. Record the vendor that the setup uses, or `other` if you cannot tell, with
-  the choice `existing`.
-- An existing agent that speaks AG-UI, but is none of the frameworks in the table below,
-  takes the Existing AG-UI agent route. For example, an `AbstractAgent` subclass that the
-  project wrote, or a service behind AG-UI middleware. Select it only for an agent that the
-  repository already has, and only when the findings prove that it speaks AG-UI. Do not
-  offer it for a new agent.
+  model setup. Record its vendor, or `other` if you cannot tell, with the choice
+  `existing`.
+- An existing agent in no framework the table below lists takes the Custom agent route,
+  which keeps it and connects it through AG-UI, directly or through an adapter.
 - If the project already has a frontend, keep it.
-- A choice the developer already named in their request or a later reply is settled.
+- A choice the developer already named in their request or a later reply is settled. So
+  is a framework the project's README names, even in an otherwise empty target.
 
 ## Frameworks this machine cannot run yet
 
-The research findings carry the CLI's toolchain reading. Its `unready` list names each
-framework that this machine cannot run until a toolchain is installed, and the toolchain
-it needs. Read that list before you ask the framework question, so the developer learns
-about a missing toolchain before they choose, and not after.
+The research findings' `unready` list names each framework this machine cannot run yet,
+and the toolchain it needs.
 
 - Do not recommend a framework on that list.
-- When you show a framework on that list, show it after the ready ones. In the same line,
-  name the toolchain it needs and its install page.
+- List a framework on that list last, by name only.
 - Do not install a toolchain yourself.
 
 ## The questions
 
-Ask every choice that is still open at this point in one message, one numbered line per
-choice, so that one reply can accept every recommendation. Put the recommendation first,
-give its evidence in one sentence, and keep the alternatives short. Do not ask a yes-or-no
-question first. Leave out a line whose answer is settled. Do not ask about the plan in
-this message: a later step asks for its approval.
-
-**Line 1: what the project is for.**
-
-If neither the developer nor the repository findings prove what the project is for, ask
-this line. It asks what the developer wants to build before the framework is chosen.
-Give two or three short examples.
-
-Do not ask it when the target directory holds no project. The frontend they pick decides
-whether a starter exists. Next.js and Angular have starters for some agent frameworks.
-React SPA, Vue 3 and React Native have no starter, so the project is built from their
-documentation. Slack and Microsoft Teams are choices at that step. A purpose question here
-names a domain before that choice.
-
-**Line 2: the agent framework.**
-
-If the project has no agent, ask this line. Show the options and one
-recommendation based on repository evidence. Match the language the repository already
-uses. When the framework is unknown, give it one line that lists the recommendation and
-valid choices.
-
-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.
-
-These are the agent frameworks, their default vendors, and the vendors that this run can
-set up for a new agent. Each documented vendor has a credential variable and setup steps on
-the framework's CopilotKit pages:
-
-| Framework                          | Default vendor  | Documented vendors        |
-| ---------------------------------- | --------------- | ------------------------- |
-| AG2                                | OpenAI          | OpenAI                    |
-| ADK                                | Google          | Google                    |
-| Agno                               | OpenAI          | OpenAI                    |
-| Built-in CopilotKit agent          | OpenAI          | OpenAI, Anthropic, Google |
-| Claude Agent SDK (Python)          | Anthropic       | Anthropic                 |
-| Claude Agent SDK (TypeScript)      | Anthropic       | Anthropic                 |
-| CrewAI Flows                       | Project-defined |                           |
-| Existing AG-UI agent               | The agent's own |                           |
-| Deep Agents                        | OpenAI          | OpenAI                    |
-| LangGraph FastAPI                  | OpenAI          | OpenAI                    |
-| LangGraph Python                   | OpenAI          | OpenAI                    |
-| LangGraph TypeScript               | OpenAI          | OpenAI                    |
-| LlamaIndex                         | OpenAI          | OpenAI                    |
-| Mastra                             | OpenAI          | OpenAI, Anthropic         |
-| Microsoft Agent Framework (.NET)   | OpenAI          | OpenAI                    |
-| Microsoft Agent Framework (Python) | OpenAI          | OpenAI                    |
-| MS Agent Harness (.NET)            | OpenAI          | OpenAI                    |
-| Pydantic AI                        | OpenAI          | OpenAI                    |
-| Strands Agents (Python)            | OpenAI          | OpenAI, Anthropic         |
-| Strands Agents (TypeScript)        | OpenAI          | OpenAI, Anthropic         |
-
-"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.
-
-"The agent's own" means that the route keeps the vendor the existing agent already uses.
-Ask no vendor question for it.
-
-Do not offer a framework that is not listed above. Do not port an existing agent to another
-framework.
-
-**Line 3: the model provider.**
-
-The run asks for a model key later. A developer with no key from the vendor the run picked
-cannot answer that question, so settle the vendor in this message.
-
-For a new agent, ask this line, even if the framework needed no question. Skip it for an
-existing agent, and when the default vendor is "Project-defined" or "The agent's own":
-those routes settle the vendor themselves. Ask which model provider the developer has an
-API key for. Offer the documented vendors of the recommended framework, then another
-provider, then no preference. Never ask for the key itself.
-
-**Line 4: the frontend.**
-
-If the project has no frontend, ask this line. The valid choices are React SPA,
-Next.js, Angular, Vue 3, React Native, Slack, and Microsoft Teams. They are valid in every
-starting state.
-
-Where there is no existing frontend, include Slack and Microsoft Teams in the frontend
-question. They are chat UIs, not CopilotKit web apps. Then recommend the one the developer
-names, and say what each choice implies for where the CopilotKit runtime lives: Next.js
-hosts it in a route handler, Angular in its SSR server, and Vue 3, React SPA and React
-Native reach a runtime that runs as its own process. Slack and Microsoft Teams use a
-long-running Channel host, not a CopilotKit web app.
-
-**Line 5: the project.** Leave out the project line on the local route: local evaluation
-creates its own project. For an existing app, first
-run `npx --prefer-offline --yes copilotkit@4.25.1 onboard credentials --json` from the target app directory.
-It only reads: it creates no project and writes no file. Read `status`:
-
-- `ready`: the app already has a project. Leave the line out.
-- `needs-developer` with `project-name`: offer `suggestedName`, another name, or a project
-  the developer already has. If there is no `suggestedName`, ask for a name. Do not list
+Ask every open choice in one message, one line each, numbered in order. Leave out a settled line.
+Do not ask about the plan here.
+
+Open the message with "Reply **go** to use all <count>, or tell me what to change."
+`<count>` is the number of lines that **go** answers. Write each line as the topic, a
+colon, and the recommendation in bold. Add a short reason only when it names something in the
+developer's own project, such as "from your README". On the next line, indented, write
+"Other:" and the alternatives, separated by " · ". Write "Other, for example:" when the
+developer can pick an option the line does not list. Say what an option needs only after
+the developer picks it. In an empty target:
+
+```text
+Reply **go** to use all five, or tell me what to change.
+
+1. Framework: **LangGraph TypeScript**
+   Other, for example: LangGraph Python · Mastra · ADK
+2. Model: **OpenAI**
+   Other, for example: Groq · OpenRouter (any OpenAI-compatible provider)
+3. Key: **I ask for the key file after I build the app**
+   Other: name the file now (outside this folder)
+4. Frontend: **Next.js**
+   Other: React SPA · Vue 3 · React Native · Angular · Slack · Microsoft Teams
+5. Project: **new project "copilotkit-assistant"**
+   Other: another name · a project you already have
+```
+
+A line that recommends nothing keeps its own wording and has no "Other:" line: the
+`env-file-exposed` line with `question.untrack` and no `question.alternative`, the
+uncommitted-changes line, or a held-back vendor, with the note "Read the reply" gives.
+**go** does not answer it. Open with "Reply **go** to use the other <count>, and answer
+line <number>." For several, "Reply **go** to use the others, and answer lines <a> and
+<b>." With one line: "Reply **go** to use it, or tell me what to change." When every line
+needs its own answer, write no **go** sentence: open with "Answer each line."
+
+**The purpose line.**
+
+Ask this line only when neither the request nor the repository shows what the project is
+for. Recommend "a general assistant", and give two short examples. In an empty target, do
+not ask it: record the purpose the request names, or "a general assistant".
+
+**The framework line.**
+
+If the project has no agent, ask this line. Recommend a framework in the repository's
+language. In an empty target, use the example's line.
+
+The vendors each framework takes in this release, default first:
+
+| Framework                          | Vendors                                      |
+| ---------------------------------- | -------------------------------------------- |
+| AG2                                | OpenAI, OpenAI-compatible                    |
+| ADK                                | Google, OpenAI, OpenAI-compatible            |
+| Agno                               | OpenAI, OpenAI-compatible                    |
+| Built-in CopilotKit agent          | OpenAI, Anthropic, Google, OpenAI-compatible |
+| Claude Agent SDK (Python)          | Anthropic only                               |
+| Claude Agent SDK (TypeScript)      | Anthropic only                               |
+| CrewAI Flows                       | Project-defined                              |
+| Custom agent                       | The agent's own                              |
+| Deep Agents                        | OpenAI, OpenAI-compatible                    |
+| LangGraph FastAPI                  | OpenAI, OpenAI-compatible                    |
+| LangGraph Python                   | OpenAI, OpenAI-compatible                    |
+| LangGraph TypeScript               | OpenAI, OpenAI-compatible                    |
+| LlamaIndex                         | OpenAI, OpenAI-compatible                    |
+| Mastra                             | OpenAI, OpenAI-compatible                    |
+| Microsoft Agent Framework (.NET)   | OpenAI, OpenAI-compatible                    |
+| Microsoft Agent Framework (Python) | OpenAI, OpenAI-compatible                    |
+| MS Agent Harness (.NET)            | OpenAI, OpenAI-compatible                    |
+| Pydantic AI                        | OpenAI, OpenAI-compatible                    |
+| Strands Agents (Python)            | OpenAI, OpenAI-compatible                    |
+| Strands Agents (TypeScript)        | OpenAI, OpenAI-compatible                    |
+
+"Project-defined" keeps the repository's vendor, or asks once when it shows none.
+
+"The agent's own" keeps the existing agent's vendor, with no vendor question. A new agent
+on the Custom agent route asks the model and key lines like any new agent, with OpenAI as
+its default vendor.
+
+For a new agent in a framework the table does not list, record its name and take the Custom
+agent route.
+
+**The model and key lines.**
+
+For a new agent, ask the model line, even if the framework needed no question. Skip it for
+"Project-defined" or "The agent's own". The model line names providers only: the row's
+default vendor, then its other vendors on "Other, for example:", except on an "only" row,
+where the model line has no "Other:" line.
+
+Ask the key line for a new agent only. Never ask for the key itself. Recommend the key file
+the developer named, or the project's env file under the rule below, or else "I ask for the
+key file after I build the app", which **go** takes. Its "Other:" is the example's, or
+"later" after a file.
+
+An OpenAI-compatible provider uses `OPENAI_API_KEY`. When the developer names one, ask in
+the same line for its model id, and its base URL unless the key file sets
+`OPENAI_BASE_URL`. Neither is a secret.
+
+When the developer has no key yet, name the ways forward on the key line: credit on the
+vendor's account, and, when the chosen framework can use Google, a free key from Google AI
+Studio at https://aistudio.google.com/apikey. The free tier limits requests per minute, so
+tell them that a slow first reply is that limit and not a fault.
+
+A path the developer names is theirs to give, even outside the project. Recommend the
+project's env file only when it exists, holds the key, and git ignores and does not track
+it, and no `env-file-exposed` line is open. In an empty target, a new key file goes outside
+the target directory, because `init` refuses a target with a `.env` file. Tell the
+developer only where it goes.
+
+**The frontend line.**
+
+If the project has no frontend, ask this line. Recommend the one the developer names, or
+Next.js. "Other:" is the example's list.
+
+**The project line.** On the local route, ask the local lines below instead. For an
+existing app, first run `npx --prefer-offline --yes copilotkit@4.27.0 onboard credentials --json` from the target app
+directory. It only reads: it creates no project and writes no file. Read `status`:
+
+- `ready`: the app has a project. Leave the line out.
+- `needs-developer` with `project-name`: recommend `suggestedName`, with the
+  example's "Other:" line. If there is no `suggestedName`, ask for a name. Do not list
   the organization's projects.
 - `needs-developer` with `env-file-exposed`: git tracks the env file the key goes into, or
-  does not ignore it. Add `question.ask` as its own line, in those words. When
-  `question.untrack` is absent, recommend approving it: without it, the run writes no key. A
-  reply that accepts every recommendation approves it. When `question.untrack` is present,
-  git tracks the file. If `question.alternative` is present, recommend it: the key goes into
-  `question.alternative.file`, which affects no teammate, and a reply that accepts every
-  recommendation takes it. Without `question.alternative`, recommend nothing for this line.
-  Untracking removes the file for everyone who pulls the next commit, so only an answer to
-  this line approves it. A reply that accepts every recommendation never approves the
-  untrack. Then offer a new project for this app, or a project the developer already has.
+  does not ignore it. Add `question.ask` as its own line, word for word: never shorten it or
+  drop what it says about teammates. Without `question.untrack`, recommend approving it:
+  without it, the run writes no key, and **go** approves it. With `question.untrack`, git
+  tracks the file: recommend `question.alternative` if present, since the key then goes into
+  `question.alternative.file`, which affects no teammate, and **go** takes it. Otherwise
+  recommend nothing. Untracking removes the file for everyone who pulls the next commit. A
+  reply that accepts every recommendation never approves the untrack. Never suggest a
+  reply that approves it. Then offer a new project for this app, or a project the developer
+  already has.
 - `stopped`: the command already filed the stop report. Tell the developer
   `stopReason.detail` in one sentence, then stop onboarding.
 
-For an empty target, offer a new project named after the target directory, or a project the
-developer already has.
-
-**Line 6: where the model key lives.** For a new agent, ask this line beside the provider
-line. Ask where the developer keeps the key for that provider: the file that holds it, or
-that they will add it later. With no file named, record that they will add it later. Never
-ask for the key itself. A path the developer names is
-theirs to give, including one outside the project. For an empty target, a new key file
-goes outside the target directory: `init` refuses a target that holds a `.env` file.
+For an empty target, recommend a new project named after the target directory, with the
+same "Other:" line. When that name is generic, such as `project`, `app`,
+`web`, `frontend`, or `src`, name it after the README title or the `package.json` `name`
+instead.
+
+**Local lines.** On the local route only:
+
+- Run `npx --prefer-offline --yes copilotkit@4.27.0 onboard local-terms --json` and follow `next`.
+- "Learning model: **configure later**", then "Other:
+  guided setup in your own terminal · a private model file you have".
+- "Local connection: **install the local stack, then write `<app directory>/<env file>`
+  and `<app directory>/.copilotkit/project.json`**", then "Other: not now". A reply that
+  accepts every recommendation approves the connection.
+- When the env file or `.copilotkit/project.json` has uncommitted changes, add one line that
+  names every one of them: "Uncommitted changes: `<files>` have edits that are not
+  committed, and the connection changes their settings. Allow it, or commit first?" One
+  answer covers every file on that line. A reply that accepts every
+  recommendation never approves those writes.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.25.1 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
 ```
 
-If no line is open, ask nothing and continue.
+With no line open, ask nothing and continue.
 
 ## Read the reply
 
-A reply that accepts, such as "yes" or "go ahead", accepts every recommendation. A line the
-reply changes takes the new answer. A line the reply does not mention keeps its
-recommendation.
+A reply such as "go", "yes" or "go ahead" accepts every recommendation. A line the reply
+changes takes the new answer. A line it does not mention keeps its recommendation.
 
 If a changed line makes another answer invalid, ask again, in one message:
 
-- A vendor that the chosen framework's row does not name: tell the developer that this run
-  cannot set up that vendor for a new agent with this framework. Offer two choices. They
-  can keep the framework with its default vendor, or choose a framework whose row names
-  their vendor.
+- A vendor that the chosen framework's own model layer cannot use, such as OpenAI for the
+  Claude Agent SDK: say so, and offer the framework with its default vendor, or another
+  framework for their vendor.
+- Anthropic or Google for a new agent on a row without it: say that this release supports
+  the row's vendors there, that Anthropic and Google come in a later release, and offer the Built-in
+  CopilotKit agent if they need them now.
 - Slack or Microsoft Teams as the frontend of an empty project: the Channel starter brings
-  its own agent, so the framework and provider lines decide nothing. Drop them.
+  its own agent, so the framework, model, and key lines decide nothing. Drop all three:
+  `<count>` counts only the lines shown.
 
 If the developer chooses a framework on the `unready` list, or the repository already has
 an agent in one, keep that framework. Before the run changes the project, tell the
-developer three things in one message:
+developer in one message:
 
 1. Which toolchain to install, and its install page.
-2. That the coding agent's shell reads PATH when it starts, so it cannot see the new
-   toolchain until the developer restarts the coding agent.
+2. That the coding agent sees the toolchain only after a restart, since its shell
+   reads PATH at start.
 3. That the run resumes after the restart with
-   `npx --prefer-offline --yes copilotkit@4.25.1 onboard start --run <onboarding_run_id>`.
+   `npx --prefer-offline --yes copilotkit@4.27.0 onboard start --run <onboarding_run_id>`.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.25.1 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
 ```
 
 Then end your turn and wait for the developer. That restart is a step here, not an error.
 
 ## Record the answers
 
-Record the purpose, the framework, the frontend, the project answer, the key file answer,
-and the model vendor with how it was chosen. The developer named it: `developer`. The developer had no preference: `default`,
-which is the row's default vendor. An existing agent's vendor: `existing`. Give these to
-every later node and subagent. They answer the framework, provider, and frontend questions
-for the rest of the run. The project and key answers answer those questions too.
+Record every answer in the CLI. They answer
+the framework, provider, and frontend questions for the rest of the run. Give them to each
+subagent too. Pass the flags that apply:
+
+- `--purpose <text>`, `--framework <name>` (a name from the table, or another
+  framework's name), and `--frontend <name>`.
+- `--vendor <vendor>`: `openai`, `anthropic`, `google`, `openai-compatible`, or `other`,
+  with `--vendor-choice <choice>`: `developer`, `default` (the row's default), or `existing`
+  (an existing agent's). For
+  `openai-compatible`, add `--model-id <id>`, and `--base-url <url>` unless the CLI
+  printed `keyFileBaseUrl`: show that one.
+- `--create <name>` for a new project or `--project <slug>` for theirs, and
+  `--key-file <path>` or `--key-later`.
+- On the local route: `--learning later`, `--learning guided`, or `--learning-file <path>`.
+  Then `--connection approved` or `declined`. For an uncommitted-changes line the reply
+  answered, add `--uncommitted-writes approved` or `declined`.
+
+```text
+npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers --framework <name> --vendor <vendor> --create <name> --key-file <path>
+```
 
-Then run `npx --prefer-offline --yes copilotkit@4.25.1 onboard read credentials/plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/plan`.