setup-agent 0.1.2 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@ One setup, shared live between the browser that opened it and the coding agent i
 ```sh
 npx setup-agent <url>              # instructions plus the current setup
 npx setup-agent <url> stream       # one JSON array of events per line; run it under a Monitor
-npx setup-agent <url> wait start   # wait for the user to click Begin plan in their browser
+npx setup-agent <url> wait start   # wait for the setup page to start the plan
 npx setup-agent <url> log "Sure, I will keep the existing chat route"   # a reply, or something no question or step conveys
 npx setup-agent <url> ask --preset llm-provider --only openai,anthropic --default openai
 npx setup-agent <url> ask "Where should assistant-ui live?" --optional   # keep working; the answer arrives on the stream
@@ -23,9 +23,9 @@ npx setup-agent <url> stream --setup-app-url https://setup.assistant-ui.com   #
 
 ## Phases
 
-A setup opens `waiting` with its products and nothing else: no steps, no questions. After connecting, the agent tells the user to return to their browser and click **Begin plan**. It keeps the stream running and blocks on `wait start`, which prints `{"ok":true,"status":"planning"}` once planning begins, or `{"ok":false,"status":"cancelled"}` when the user ends the setup first. The browser sends `checkout/begin-plan`, moving the setup to `planning` and emitting `planning.started` on the stream. Questions and plan submissions are refused while waiting. Products are the starting list of names and setup guide references. The agent explores every starting guide and may discover other relevant products or dependencies without adding them to the cart. It includes those additions in the plan for approval. The legacy `ask --product` and `checkout/add-product` protocol remains supported for older agents. In `planning`, the agent investigates the project, asks what the code does not decide, and proposes a markdown plan with `plan` carrying its findings. `log` is for replying to the user and for what no question or step conveys. The user approves the plan or asks for changes with feedback; every revision is kept. Approval moves the setup to `installing`, where the agent declares its own steps with `add-step` and works through them with `step`. `add-step` and `step` are refused before approval. `done` marks the remaining steps done and proposes closing, with an optional `--summary` and an optional `--preview <url>` naming a dev server the agent left running; a preview must be an http(s) URL on localhost, and the browser offers to open it. `done` does not close. The browser shows the proposal with a close action that sends `checkout/finish`, and the stream prints `finished`. Until then the agent stays idle on the stream, because the user may send a follow-up message; after handling one it runs `done` again to renew the proposal.
+A setup opens `waiting` with its products and nothing else: no steps, no questions. After connecting, the agent keeps the stream running and blocks on `wait start`, which prints `{"ok":true,"status":"planning"}` once planning begins, or `{"ok":false,"status":"cancelled"}` when the user ends the setup first. The setup page has no Begin plan button: it sends `checkout/begin-plan` by itself once it joins a waiting setup, moving the setup to `planning` and emitting `planning.started` on the stream. Questions and plan submissions are refused while waiting. Products are the starting list of names and setup guide references. The agent explores every starting guide and may discover other relevant products or dependencies without adding them to the cart. It includes those additions in the plan for approval. The legacy `ask --product` and `checkout/add-product` protocol remains supported for older agents. In `planning`, the agent investigates the project, asks what the code does not decide, and proposes a markdown plan with `plan` carrying its findings. `log` is for replying to the user and for what no question or step conveys. The user approves the plan or asks for changes with feedback; every revision is kept. Approval moves the setup to `installing`, where the agent declares its own steps with `add-step` and works through them with `step`. `add-step` and `step` are refused before approval. `done` marks the remaining steps done and proposes closing, with an optional `--summary` and an optional `--preview <url>` naming a dev server the agent left running; a preview must be an http(s) URL on localhost, and the browser offers to open it. `done` does not close. The browser shows the proposal with a close action that sends `checkout/finish`, and the stream prints `finished`. Until then the agent stays idle on the stream, because the user may send a follow-up message; after handling one it runs `done` again to renew the proposal.
 
-The URL is the browser's link to its agent, not one setup. A finished or cancelled setup stays on the link, and the browser's next setup replaces it with a new `checkout/create` carrying a new `id`: the plans, steps, inputs and log start over, the agent's presence carries across when it is still connected, and the stream prints `setup.created` with the new products. The agent keeps the stream running after `finished` or `cancelled` and blocks on `wait start`, which returns once the next setup begins planning; a setup already closed when the wait begins is skipped rather than reported.
+The URL is the browser's link to its agent, not one setup. A finished or cancelled setup stays on the link until the agent replaces it with a new `checkout/create` carrying a new `id` (only the agent creates setups; the browser never sends it): the plans, steps, inputs and log start over, the agent's presence carries across when it is still connected, and the stream prints `setup.created` with the new products. The agent keeps the stream running after `finished` or `cancelled` and blocks on `wait start`, which returns once the next setup begins planning; a setup already closed when the wait begins is skipped rather than reported.
 
 The browser sends the setup `id` and the displayed plan `revision` with each `checkout/plan` decision. The host rejects a mismatched setup or revision with `stale-plan`, so a queued decision cannot approve or revise a newer plan. Older clients may omit these fields and retain their existing behavior. The guard requires a host running this version of `setup-agent`.
 
@@ -76,6 +76,14 @@ The browser opens only when the setup waits on the user (an open input, a propos
 
 Each `input.needed` carries the question, its options and the `answer` command. On a worker without browser presence, setup opens once and then leaves the rest to the agent.
 
+## Guide
+
+Setup is online-only. Every text the CLI shows the agent lives on the setup server (`apps/checkout-worker/src/guide.ts`), so a wording or flow fix ships with a worker deploy and reaches every CLI from this version on. That covers the briefing, the stream's messages, the `waiting` and `done` hints, and the questions `input.needed` relays. Commands that print guidance (`<url>` itself, `stream`, `ask`, `plan`, `wait`, `done`, and `runAgentSetup`) fetch `GET <setup-url>/guide?protocol=1&started=<user|agent|agent-stream>&opened=<0|1>`. Without it they fail with `Setup needs internet access to <url>`.
+
+The guide is data. The CLI strips control characters and bidirectional overrides from every text, and fills `{{cmd}}`, `{{url}}` and the other placeholders with values it computes itself. It runs the intro only from three local actions: `print` (a text by key), `print-status` and `announce-agent`. It refuses any other step, a guide over 256 KB, and redirects. Commands for the CLI to run, files it writes and URLs it opens never come from the guide. The server's text can still steer the agent, as its questions and user messages already can, so the guide is as trusted as the setup server.
+
+`GUIDE_PROTOCOL` is the format version. The server answers another version with 426, and the CLI tells the user to update. Bump it only for a change an older CLI cannot read. A new command, flag or local action needs an npm release.
+
 ## Workspace
 
 The package lives in `packages/setup-agent`; its Cloudflare worker lives in `apps/checkout-worker`. Build the worker dependencies with `pnpm turbo build --filter="checkout-worker^..."`, then run `pnpm --filter checkout-worker dev`. The worker consumes the published `@statewire/cloudflare` adapter.

package/dist/cli.d.ts

@@ -9,26 +9,6 @@ export declare const HELP: string;
  * no credentials, query or fragment, and hold only address characters.
  */
 export declare const parseSetupUrl: (value: string) => string;
-export type AgentInstructionsOptions = {
-    /** How the agent invokes the setup commands, before the URL; `npx setup-agent` by default. */
-    command?: string;
-    /**
-     * The agent started this setup with `assistant-ui setup`, which already
-     * began planning; there is no Begin plan click to wait for.
-     */
-    startedByAgent?: {
-        browserUrl: string;
-        /** False when the browser was not opened for the user; the agent then hands them the link. */
-        opened?: boolean;
-        /**
-         * The command that printed this briefing is the stream: it keeps running
-         * and opens the browser only when the setup waits on the user.
-         */
-        streaming?: boolean;
-    };
-};
-export declare const agentInstructions: (setupUrl: string, options?: AgentInstructionsOptions) => string;
-export declare const INSTRUCTIONS: typeof agentInstructions;
 type Parsed = {
     positional: string[];
     flags: Map<string, string | true>;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAU,CAAC;AA2B/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAY,CAAC;AAI3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAU,CAAC;AAatC,eAAO,MAAM,IAAI,QAuChB,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,KAAG,MA6B7C,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,8FAA8F;QAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AA6CF,eAAO,MAAM,iBAAiB,aAClB,MAAM,YACP,wBAAwB,WA+ClC,CAAC;AAEF,eAAO,MAAM,YAAY,0BAAoB,CAAC;AAE9C,KAAK,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,CAAC;AAuB1E,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAU,CAAC;AAuG5C,2LAA2L;AAC3L,eAAO,MAAM,YAAY,WACf,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,6BAiBjD,CAAC;AAiGL,eAAO,MAAM,OAAO,SACZ,SAAS,MAAM,EAAE,SAChB,MAAM,CAAC,OAAO,CAAC,KACrB,QAAQ,CAAC,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CA+HxC,CAAC;AAQF,+EAA+E;AAC/E,eAAO,MAAM,aAAa,YAAa,MAAM,OAAO,MAAM,SAAS,MAAM,WAqBxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,OACP,MAAM,QACL,MAAM,OAAO,CAAC,MAAM,CAAC,wCAuD5B,CAAC;AAgHF,MAAM,MAAM,sBAAsB,GAAG;IACnC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,OAAO,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAkCF,eAAO,MAAM,IAAI,SAAU,SAAS,MAAM,EAAE,kBAA0B,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,eAAe,SACpB,SAAS,MAAM,EAAE,YACd,sBAAsB,kBA4ThC,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAU,CAAC;AA2B/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAY,CAAC;AAM3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAU,CAAC;AAatC,eAAO,MAAM,IAAI,QAuChB,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,KAAG,MA6B7C,CAAC;AASF,KAAK,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,CAAC;AAuB1E,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAU,CAAC;AAuG5C,2LAA2L;AAC3L,eAAO,MAAM,YAAY,WACf,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,6BAiBjD,CAAC;AAiGL,eAAO,MAAM,OAAO,SACZ,SAAS,MAAM,EAAE,SAChB,MAAM,CAAC,OAAO,CAAC,KACrB,QAAQ,CAAC,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CA+HxC,CAAC;AAQF,+EAA+E;AAC/E,eAAO,MAAM,aAAa,YAAa,MAAM,OAAO,MAAM,SAAS,MAAM,WAqBxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,OACP,MAAM,QACL,MAAM,OAAO,CAAC,MAAM,CAAC,wCAuD5B,CAAC;AAgHF,MAAM,MAAM,sBAAsB,GAAG;IACnC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,OAAO,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAoCF,eAAO,MAAM,IAAI,SAAU,SAAS,MAAM,EAAE,kBAA0B,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,eAAe,SACpB,SAAS,MAAM,EAAE,YACd,sBAAsB,kBAgVhC,CAAC"}

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { CODING_AGENTS, detectAgentKind, findCommand, isDirectInvocation, runCodingAgent } from "./agents.js";
 import { OPTION_ICONS, currentPlan, isAgentPresent, isClosed, isLoopbackHostname, isOptionIcon, isValidModelAnswer, parseEntryPointOptions, stepProgress } from "./protocol.js";
+import { loadGuide, renderText } from "./guide.js";
 import { answerNeed } from "./needs.js";
 import { connectCheckout } from "./client.js";
 import { INPUT_PRESETS, isPresetId, presetInput } from "./presets.js";
@@ -43,7 +44,7 @@ Commands (the url always comes first):
                                     --icons is required and names an icon for every option, from: ${OPTION_ICONS.join(", ")}.
   ask <prompt> --entry-points '<JSON array>' [--default <id>] [--optional] [--step <step-id>] [--wait]
                                     Ask where users should access the assistant. Each of 1–3 options has id, label, description and entryPoint {formFactor: modal|sidebar|full-page, placement, trigger, recommended?}. Answers one option id.
-  wait start                        Block until the user clicks Begin plan in their browser; after a finished or cancelled setup, until the next one begins.
+  wait start                        Block until the setup page starts the plan; prints {"ok":false,"status":"cancelled"} if the user cancels first. After a finished or cancelled setup, waits for the next one to begin.
   wait <input-id> [--timeout <seconds>]
                                     Block until the user answers or dismisses an input. A multi-select answer prints as an array.
   plan (<markdown> | --file <path>) [--wait] [--timeout <seconds>]
@@ -82,71 +83,12 @@ const parseSetupUrl = (value) => {
 	if (!SETUP_URL_PATTERN.test(href)) throw new Error("the setup URL has characters a setup URL does not use");
 	return href;
 };
-const EVENT_LIST = `"planning.started", "input.answered" ({inputId, answer, note?}; answer is an array for a choice question not asked with --single), "input.dismissed", "plan.approved", "plan.changes-requested" ({feedback}), "message.created" ({messageId, text}), "finished", "cancelled", "setup.created" ({products})`;
-const beginPlanHandoff = (cmd, url) => `Before planning, check the current setup status. If it is "waiting", tell the user in your own conversation: "I'm connected. Go back to your browser and click Begin plan. You can watch my progress, answer questions, and steer me there." Then run:
-  ${cmd} ${url} wait start
-Keep the stream running while you wait. Do not inspect the project, fetch guides, ask setup questions, or propose a plan until this command returns {"ok":true}. If it returns {"ok":false,"status":"cancelled"}, the user ended this setup before planning: do not plan, tell the user you are connected and waiting for their next setup, and run "wait start" again. Only the user in the browser should start planning; never invoke the browser's start command yourself. "planning.started" also arrives on the stream. If the status is already "planning" or "installing", resume that phase without asking the user to begin again. If it is "done" or "cancelled", that setup is over: tell the user you are connected and waiting for their next setup, and run "wait start", which returns once the next one begins.`;
-const agentStartedHandoff = ({ browserUrl, opened = true, streaming = false }) => streaming ? `You started this setup, and it is already planning: there is no Begin plan click to wait for. Check "status" before planning: if it is "planning" or "installing", go on with that phase. If the status is "done" or "cancelled", that setup is over: tell the user you are connected and waiting for their next setup, and run "wait start", which returns once the next one begins.` : `You started this setup, and it is already planning: there is no Begin plan click to wait for. The browser asks the user to connect to you first; it shows your working directory once your stream is running. Check "status" before planning: if it is "planning" or "installing", go on with that phase. Tell the user in your own conversation, once: ${opened ? `"I opened the assistant-ui setup in your browser. I'll ask my questions there, and you can watch my progress and steer me from that page. If it didn't open, go to ${browserUrl} ."` : `"Open ${browserUrl} to follow the assistant-ui setup. I'll ask my questions there, and you can watch my progress and steer me from that page."`} If the status is "done" or "cancelled", that setup is over: tell the user you are connected and waiting for their next setup, and run "wait start", which returns once the next one begins.`;
-const streamSection = (cmd, url, streaming, noOpen) => streaming ? `The command that printed this is the stream. Keep it running in the background until the setup ends: the browser shows you as connected only while it runs. New output does not wake you: read its new lines between your other commands. Each new line is a JSON array of events: ${EVENT_LIST}, plus:
-- "browser.opened" ({id, message}): setup opened the setup page in the user's browser for a question. Tell the user once, in your own conversation, that it waits there, and keep working in the same turn.
-- "input.needed" ({id, message, question, options?, answer}): the user may not see the browser right now. Do what its message says: run "wait <id>" for their answer in the browser, or ask the user in your own conversation with that question and options, then run its "answer" command with their reply. Answered either way, the setup goes on.
-If this command stops, start it again in the background with
-  ${cmd} ${url} stream${noOpen ? " --no-open" : ""}
-The URL is the user's link to you from their browser, not one setup: it outlives this one, and their next setup arrives on the same stream.` : `First, start a persistent Monitor on
-  ${cmd} ${url} stream
-and keep it running: the browser shows you as connected only while it runs, and it is how answers reach you. The URL is the user's link to you from their browser, not one setup: it outlives this one, and their next setup arrives on the same stream. Each line is a JSON array of events: ${EVENT_LIST}.`;
-/** Why the agent must not end its turn mid-setup, and how it waits instead. */
-const keepGoing = (cmd, url) => `Run the setup to the end in one go. Do not count on the stream or the browser to wake you: if you end your turn before the install is done, the setup can stay paused until the user types to you, even after they answer in the browser. So never end your turn to wait for an answer, and do not stop after telling the user something. To get an answer, block on it:
-  ${cmd} ${url} wait <input-id>
-("plan --wait" and "ask --wait" block the same way). A wait that prints {"ok":false,"status":"waiting"} has not failed and the setup is not stuck: run its "next" command, right away. "next" only waits; never repeat an "ask" or "plan" to keep waiting, since that asks or submits again. End your turn only to ask the user in your own conversation (an "input.needed" you relay, or a value only they can give), and go on as soon as they reply; or once the install is done and proposed with "done".`;
-const agentInstructions = (setupUrl, options = {}) => {
-	const url = shellWord(setupUrl);
-	const cmd = options.command ?? DEFAULT_COMMAND;
-	const started = options.startedByAgent;
-	const streaming = started?.streaming === true;
-	return `You are the coding agent for a setup ${started ? streaming ? started.opened === false ? "you started; setup opens no browser (--no-open), so the user follows it on the setup page if they open it, or answers you in your own conversation" : "you started; the user follows it in their browser, which setup opens when you ask the user something" : "you opened in the user's browser" : "the user opened in their browser"}. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
-
-${streamSection(cmd, url, streaming, started?.opened === false)}
-
-${keepGoing(cmd, url)}
-
-The user can message you at any time, including while a question is waiting. Read "message.created" events, acknowledge each with "${cmd} ${url} ack <message-id>", and reply using "log" with what you will do. Pending messages are replayed when the stream starts and listed in "status". A message is not an answer or plan approval; keep those decisions explicit.
-
-"log" is a message to the user, and the user reads every one: send it only to reply to their message, to tell them something no question or step conveys (a blocker, a deviation from the plan, a decision you made for them), or once as a wrap-up when the install is finished. Findings go in the plan, progress in step notes, questions in "ask"; do not narrate.
-
-${started ? agentStartedHandoff(started) : beginPlanHandoff(cmd, url)}
-
-The remaining phases are plan, then install.
-
-1. Plan. Investigate only; change nothing yet. If the current directory is not an app to install into (a monorepo root, an empty folder, a library), ask where to install first:
-  ${cmd} ${url} ask "Which project should I install into?" --placeholder "An absolute path to the app" --wait
-Read the project: its app framework and package manager, the agent framework and model provider it already uses, where components live, any existing chat route. Fetch each product's "guide" URL from the setup below; it is the install reference. Ask for what the project does not decide, using the standard questions so the browser can render them well:
-  ${cmd} ${url} ask --preset framework
-  ${cmd} ${url} ask --preset llm-provider
-The setup's products are starting names and guide references. If the setup lists no products, first ask the user what to set up with a choice question whose options are slugs from https://www.assistant-ui.com/catalog.md, then fetch https://www.assistant-ui.com/install.md?items=<slugs> as the guide. Explore each product's setup instructions, then discover and plan any other relevant products or dependencies the app needs. Read /catalog.md on the guide URL’s origin to find related products and fetch their setup guides. The starting list does not restrict the implementation or require adding another product to the list. Include relevant additions in the plan for approval.
-When the setup puts an assistant in the app, ask how users should access it after discovering the actual app and before proposing the plan. Skip this question when no product's guide installs an assistant (a standalone library or service setup, for example). Use an entry-point question with only 1–3 sensible alternatives. Describe the actual app's pages, workflow and component placement, not generic placeholder copy. Recommend one clear fit when there is one; two options may use the same form factor in different places. Each option needs a stable id, label, contextual description and entryPoint {"formFactor":"modal"|"sidebar"|"full-page","placement":"where it appears","trigger":"how users open it or navigate to it","recommended":true?}. Write the JSON array for this app and send it with:
-  ${cmd} ${url} ask "Where should users access the assistant?" --entry-points '<JSON array>' --wait
-Mark a clear fit with "recommended":true rather than --default, so the user makes the pick. When you ask it, do not submit the plan before the user picks an entry point. Respect the selected placement and trigger in the plan and implementation. Do not ask for a new-versus-existing app setting; discover the app from its files and ask only for an install path when needed.
-Skip a preset the code already answers (a chat route on the AI SDK, a provider key in .env.local) and log why. Ask everything at once, keep investigating, and then run "wait <input-id>" for each open question before you write the plan; do not end your turn while they are open. A framework answer is "<framework>:<language>", for example "ai-sdk:typescript". A model answer is JSON {"provider","model","reasoningEffort"?}. An answer may carry a "note" from the user; follow it. A choice answer that matches none of the options is the user's own text.
-Then write the plan as markdown and submit it:
-  ${cmd} ${url} plan --file <path> --wait
-Use these headings, each with bullets: "## What I found" (facts as \`- **Label:** value\`: app framework, package manager, agent framework, model provider and model, where components live), "## What I will install" (packages and files, one per bullet), "## Steps" (a numbered list, one line each), and "## Open questions" only if any remain. Keep it under 30 lines; no preamble. "plan --wait" prints {"decision":"approve"} or {"decision":"revise","feedback":"..."}; when it prints {"ok":false,"status":"waiting"}, the plan is submitted and still with the user, so keep waiting with "wait plan" and do not submit it again. On revise, address the feedback (ask again if you need to) and submit a new plan; repeat until approved. Do not change the project before approval: the setup refuses steps until then.
-
-2. Install. Declare the steps from your plan up front, in order:
-  ${cmd} ${url} add-step "<title>" --detail "<one line>"
-which prints the step id. Then work through them: "step <id> active" before, "step <id> done --note '<one line on what you did>'" after; "skipped" when the step is already satisfied, "blocked" when you cannot continue, saying why in --note. Add steps as the work reveals them. Ask when you need another decision or value (--choices for a pick, plain for text; --optional when you can proceed without an answer; --wait only when the answer is the very next thing you need). A choice question is multi-select: the user checks any number of your options, and the answer is an array of the ids they checked, plus their own text as an entry when they typed one. Pass --single only when the options exclude each other (one framework, one model, yes or no); the answer is then one id. Every option must carry an icon, given as --icons "<id>=<icon>,..." with the closest name from this pack: ${OPTION_ICONS.join(", ")}. A question without an icon for each option is refused. Open inputs the user has not answered are listed under "inputs" in "status"; check them before asking again.
-The API key behind a model answer is not in the answer and you never see it: pick the variable name the provider's SDK reads (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) and run
-  ${cmd} ${url} env <input-id> <ENV_VAR> --file .env.local
-which writes ENV_VAR=<key> into that file. Use the answer's model in the chat route and map reasoningEffort onto the provider's setting when it is set. If "env" says the key was never deposited (the model question was answered from your conversation), ask the user to add the key to that file themselves. Never invent a key or a model name.
-
-When every product is installed and verified, run
-  ${cmd} ${url} done --summary "<one or two lines on what you installed and how to try it>" --preview http://localhost:<port>
-Before that, start the project's dev server in the background when the project has one, check that the page you changed loads, and pass the address as --preview (the page itself when it is not the root); leave the server running so the user can try the result. Omit --preview when there is nothing to open. This proposes closing the setup; only the user closes it. Do not stop the stream or exit: stay idle on it, because the user may follow up with a "message.created" event. Handle it, then run "done" again. The stream prints "finished" once the user closes the setup, and "cancelled" if they end it early. Keep the stream running after either: the user's next setup starts on this same URL and arrives as "setup.created" with its products. Run
-  ${cmd} ${url} wait start
-which returns once that setup begins, then run "status" for its products, guides and instructions and go through plan and install again. A "setup.created" event while you are still working means the user replaced this setup: drop what you were doing and start over the same way.
-`;
-};
-const INSTRUCTIONS = agentInstructions;
+/** The values the CLI fills into guide texts itself; never the server's to choose. */
+const localValues = (setupUrl, command = DEFAULT_COMMAND) => ({
+	cmd: command,
+	url: shellWord(setupUrl),
+	icons: OPTION_ICONS.join(", ")
+});
 const parseArgs = (argv) => {
 	const positional = [];
 	const flags = /* @__PURE__ */ new Map();
@@ -302,12 +244,12 @@ const within = async (promise, seconds) => {
 	}
 };
 /** What a wait prints when the user has not decided yet: the command to run again, now. */
-const stillWaiting = (target, next) => ({
+const stillWaiting = (target, next, guide) => ({
 	ok: false,
 	status: "waiting",
 	waitingFor: target,
 	next,
-	message: `The user has not answered yet. Run "next" now to keep waiting (it only waits; do not repeat the command you ran, which would ask or submit again), or go on with other work and run it when you need the answer. Do not end your turn: nothing resumes you until you run it.`
+	message: renderText(guide, "wait.waiting")
 });
 const decided = (plan, state) => {
 	if (state.status === "cancelled") return {
@@ -552,15 +494,18 @@ const answered = (input) => ({
 	status: input.status,
 	...input.answer !== void 0 && answerFields(input, input.answer)
 });
-const runStream = async (client, url, flags, options) => {
+const runStream = async (client, url, flags, options, guide) => {
 	const setupAppUrl = options.browser?.setupAppUrl ?? flagText(flags, "setup-app-url");
 	const linkId = new URL(url).pathname.split("/").filter(Boolean).at(-1);
-	const stream = await followSetup(client, { ...setupAppUrl !== void 0 && linkId !== void 0 && { browser: {
-		setupAppUrl: parseSetupUrl(setupAppUrl),
-		linkId,
-		answerCommand: `${options.command ?? DEFAULT_COMMAND} ${shellWord(url)} answer`,
-		canOpen: (options.browser?.canOpen ?? true) && !flags.has("no-open")
-	} } });
+	const stream = await followSetup(client, {
+		guide,
+		...setupAppUrl !== void 0 && linkId !== void 0 && { browser: {
+			setupAppUrl: parseSetupUrl(setupAppUrl),
+			linkId,
+			answerCommand: `${options.command ?? DEFAULT_COMMAND} ${shellWord(url)} answer`,
+			canOpen: (options.browser?.canOpen ?? true) && !flags.has("no-open")
+		} }
+	});
 	const stop = () => {
 		stream.stop().finally(() => {
 			client.dispose();
@@ -593,22 +538,28 @@ const runSetupCommand = async (argv, options = {}) => {
 	if (command === "intro" && isDirectInvocation()) return launchAgent(url);
 	const client = await connectCheckout(url).catch((error) => fail(error instanceof Error ? error.message : String(error)));
 	const commands = client.commands;
+	let guideLoad;
+	const guide = () => guideLoad ??= loadGuide(url, {
+		started: "user",
+		opened: command !== "stream" || (options.browser?.setupAppUrl ?? flagText(flags, "setup-app-url")) !== void 0 && (options.browser?.canOpen ?? true) && !flags.has("no-open")
+	});
 	const waitCommand = (target) => `${options.command ?? DEFAULT_COMMAND} ${shellWord(url)} wait ${target}`;
 	try {
 		switch (command) {
 			case "intro": {
-				const kind = detectAgentKind();
-				await commands["agent/intro"]({ ...kind !== void 0 && { kind } }).catch(() => {});
-				process.stdout.write(agentInstructions(url, { ...options.command !== void 0 && { command: options.command } }));
-				process.stdout.write("\nCurrent setup:\n");
-				print(summary(requireState(client)));
+				const intro = await guide();
+				for (const step of intro.intro) if (step.action === "announce-agent") {
+					const kind = detectAgentKind();
+					await commands["agent/intro"]({ ...kind !== void 0 && { kind } }).catch(() => {});
+				} else if (step.action === "print") process.stdout.write(renderText(intro, step.text, localValues(url, options.command)));
+				else print(summary(requireState(client)));
 				break;
 			}
 			case "status":
 				print(summary(requireState(client)));
 				break;
 			case "stream":
-				await runStream(client, url, flags, options);
+				await runStream(client, url, flags, options, await guide());
 				break;
 			case "answer": {
 				const id = rest[0] ?? fail("usage: answer <input-id|plan|finish> <answer> [--note <text>]");
@@ -667,7 +618,7 @@ const runSetupCommand = async (argv, options = {}) => {
 					break;
 				}
 				const plan = await within(waitForPlan(client, revision), waitSeconds(flags, DEFAULT_WAIT_SECONDS));
-				print(plan === TIMED_OUT ? stillWaiting("plan", waitCommand("plan")) : decided(plan, requireState(client)));
+				print(plan === TIMED_OUT ? stillWaiting("plan", waitCommand("plan"), await guide()) : decided(plan, requireState(client)));
 				break;
 			}
 			case "ask": {
@@ -693,7 +644,7 @@ const runSetupCommand = async (argv, options = {}) => {
 					break;
 				}
 				const input = await within(waitForInput(client, inputId), waitSeconds(flags, DEFAULT_WAIT_SECONDS));
-				print(input === TIMED_OUT ? stillWaiting(inputId, waitCommand(inputId)) : answered(input));
+				print(input === TIMED_OUT ? stillWaiting(inputId, waitCommand(inputId), await guide()) : answered(input));
 				break;
 			}
 			case "wait": {
@@ -702,7 +653,7 @@ const runSetupCommand = async (argv, options = {}) => {
 				if (target === "start") {
 					const status = await within(waitForStart(client), waitSeconds(flags, 0));
 					if (status === TIMED_OUT) {
-						print(stillWaiting("start", waitCommand("start")));
+						print(stillWaiting("start", waitCommand("start"), await guide()));
 						break;
 					}
 					print({
@@ -714,12 +665,12 @@ const runSetupCommand = async (argv, options = {}) => {
 				if (target === "plan") {
 					const plan = currentPlan(state) ?? fail("no plan has been proposed");
 					const decision = await within(waitForPlan(client, plan.revision), waitSeconds(flags, DEFAULT_WAIT_SECONDS));
-					print(decision === TIMED_OUT ? stillWaiting("plan", waitCommand("plan")) : decided(decision, requireState(client)));
+					print(decision === TIMED_OUT ? stillWaiting("plan", waitCommand("plan"), await guide()) : decided(decision, requireState(client)));
 					break;
 				}
 				if (!state.inputs.some((input) => input.id === target)) fail(`no input "${target}"`);
 				const input = await within(waitForInput(client, target), waitSeconds(flags, DEFAULT_WAIT_SECONDS));
-				print(input === TIMED_OUT ? stillWaiting(target, waitCommand(target)) : answered(input));
+				print(input === TIMED_OUT ? stillWaiting(target, waitCommand(target), await guide()) : answered(input));
 				break;
 			}
 			case "env": {
@@ -770,6 +721,7 @@ const runSetupCommand = async (argv, options = {}) => {
 				break;
 			}
 			case "done": {
+				const hint = renderText(await guide(), "done.next");
 				const summary = flagText(flags, "summary");
 				const preview = flagText(flags, "preview");
 				await commands["agent/done"]({
@@ -779,7 +731,7 @@ const runSetupCommand = async (argv, options = {}) => {
 				print({
 					ok: true,
 					status: "proposed",
-					next: "Keep the stream running and stay idle. The user closes the setup or sends a follow-up message."
+					next: hint
 				});
 				break;
 			}
@@ -791,6 +743,6 @@ const runSetupCommand = async (argv, options = {}) => {
 		client.dispose();
 	}
 };
-export { CODING_AGENTS, HELP, INSTRUCTIONS, agentInstructions, askSeed, detectAgentKind, diffEvents, findCommand, isDirectInvocation, main, parseSetupUrl, runCodingAgent, runSetupCommand, upsertEnvLine, waitForStart, writeEnvSecret };
+export { CODING_AGENTS, HELP, askSeed, detectAgentKind, diffEvents, findCommand, isDirectInvocation, main, parseSetupUrl, runCodingAgent, runSetupCommand, upsertEnvLine, waitForStart, writeEnvSecret };
 
 //# sourceMappingURL=cli.js.map