setup-agent 0.0.3 → 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentbaseAI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,18 +21,24 @@ npx setup-agent <url> done --summary "installed the thread and a chat route" --p
 
 ## 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`. 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. When a product needs another one the project lacks, the agent proposes it with `ask "<why>" --product <slug>`; the browser, which owns the catalog, accepts with `checkout/add-product` (the product and its guide join `products`, the input answers `added`) or dismisses the input. 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 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.
 
 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.
 
 ## Inputs
 
-Every input is `text`, `choice` or `model`. A choice carries `options` (`id`, `label`, `description`, `icon`, `variants`), an optional `default` and a `help` note the browser renders as a "help me choose" disclosure. The answer is the option id, `<option>:<variant>` when the option has variants (`langgraph:python`), or the user's own text when none of the options fit; the stream marks that answer `custom`. An agent's own choice is multi-select unless asked with `--single`: the user checks any number of options (none may have variants), and the answer is a JSON array of those entries, which `wait` and the stream print as an array and `status` holds as text. `--single` is for options that exclude each other (one framework, one model, yes or no) and answers one id. Every one of the agent's own options must carry an `icon` from the pack `OPTION_ICONS` exports (`--icons "slack=message,email=mail"`); the CLI refuses the question otherwise. A preset option carries a brand mark instead. Every answer may carry a `note` from the user. A model input lists providers as its options; the browser collects the provider, its API key, the model and an optional reasoning effort, and the answer is that object as JSON (`{"provider","model","reasoningEffort"?}`); the API key is deposited separately and only ever reaches the env file the agent names through `env`.
+Inputs include `text`, `choice`, `model` and `entry-point`, plus the legacy `product` kind. A choice carries `options` (`id`, `label`, `description`, `icon`, `variants`), an optional `default` and a `help` note the browser renders as a "help me choose" disclosure. Option ids are unique, and neither option nor variant ids may contain `:`. The answer is the option id, `<option>:<variant>` when the option has variants (`langgraph:python`), or the user's own text when none of the options fit (including any text with more than one `:`); the stream marks that answer `custom`. An agent's own choice is multi-select unless asked with `--single`: the user checks any number of options (none may have variants), and the answer is a JSON array of those entries, which `wait` and the stream print as an array and `status` holds as text. `--single` is for options that exclude each other (one framework, one model, yes or no) and answers one id. Every one of the agent's own options must carry an `icon` from the pack `OPTION_ICONS` exports (`--icons "slack=message,email=mail"`); the CLI refuses the question otherwise. A preset option carries a brand mark instead. Every answer may carry a `note` from the user. A model input lists providers as its options; the browser collects the provider, its API key, the model and an optional reasoning effort, and the answer is that object as JSON (`{"provider","model","reasoningEffort"?}`); the API key is deposited separately and only ever reaches the env file the agent names through `env`.
 
-Three standard choices ship as presets (`setup-agent` exports `INPUT_PRESETS` and `presetInput`), so the browser and the CLI agree on their options and brand marks:
+When the setup puts an assistant in the app, the agent asks for its entry point after discovering the app, with `ask "<prompt>" --entry-points '<JSON array>' [--default <id>]`. Each of 1–3 options includes a stable `id`, `label`, contextual `description`, and `entryPoint: { formFactor: "modal" | "sidebar" | "full-page", placement, trigger, recommended? }`. At most one option is recommended, and the agent marks it with `recommended` rather than `--default`, which would preselect it. Two alternatives can share a form factor when their placements differ. Entry-point questions accept exactly one option id, with an optional user note; variants, custom ids, a help note and multi-selection are refused. The agent describes the actual app's workflow, placement and opening action, then incorporates the user's selection into the approved plan.
+
+Two standard choices and a legacy project choice ship as presets (`setup-agent` exports `INPUT_PRESETS` and `presetInput`), so the browser and the CLI agree on their options and brand marks:
 
 - `framework`: Vercel AI SDK, Mastra, LangGraph, each with its language.
 - `llm-provider`: OpenAI, Anthropic, Google Gemini, OpenRouter, xAI, Mistral, DeepSeek, Groq, Fireworks AI; defaults to OpenAI. Rendered as the model picker (provider, key, model, reasoning effort).
-- `project`: the React projects the agent found, passed as `--choices "apps/web=Next.js,apps/admin"`, ahead of a fixed "New project" option whose second pick is the meta framework. Answers a path, or `new:<next|vite|react-router|tanstack-start|expo>`.
+- `project` (legacy decoder compatibility): the React projects the agent found, passed as `--choices "apps/web=Next.js,apps/admin"`, ahead of a fixed "New project" option whose second pick is the meta framework. Answers a path, or `new:<next|vite|react-router|tanstack-start|expo>`.
+
+`--only` restricts a preset to some of its options and leaves out `--choices` (a single id locks the choice in) and `--default` preselects one.
+
+## Workspace
 
-`--only` restricts a preset to some of its options (a single id locks the choice in) and `--default` preselects one.
+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

@@ -1,66 +1,71 @@
-/// <reference types="node" />
-import { Checkout } from "./protocol.js";
-import { CheckoutClient } from "./client.js";
-//#region src/cli.d.ts
-declare const HELP: string;
-declare const INSTRUCTIONS: (url: string) => string;
+import type { CheckoutClient } from "./client.js";
+import type { Checkout } from "./protocol.js";
+export declare const HELP: string;
+export declare const agentInstructions: (url: string) => string;
+export declare const INSTRUCTIONS: (url: string) => string;
 type Parsed = {
-  positional: string[];
-  flags: Map<string, string | true>;
+    positional: string[];
+    flags: Map<string, string | true>;
 };
 /** The coding agent this process runs under, from the variables each one exports to its shell. */
-declare const detectAgentKind: (env?: NodeJS.ProcessEnv) => string | undefined;
+export declare const detectAgentKind: (env?: NodeJS.ProcessEnv) => string | undefined;
 /** True when a person typed the command into a terminal rather than an agent running it from its shell. */
-declare const isDirectInvocation: (env?: NodeJS.ProcessEnv, stdin?: {
-  isTTY?: boolean | undefined;
+export declare const isDirectInvocation: (env?: NodeJS.ProcessEnv, stdin?: {
+    isTTY?: boolean | undefined;
 }, stdout?: {
-  isTTY?: boolean | undefined;
+    isTTY?: boolean | undefined;
 }) => boolean;
 type StreamEvent = {
-  event: "planning.started";
+    event: "planning.started";
 } | {
-  event: "message.created";
-  messageId: string;
-  text: string;
+    event: "message.created";
+    messageId: string;
+    text: string;
 } | {
-  event: "input.answered";
-  inputId: string;
-  prompt: string;
-  /** The entries of a multiple choice answer, else the answer text. */
-  answer: string | string[];
-  note?: string;
-  /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */
-  custom?: true;
+    event: "input.answered";
+    inputId: string;
+    prompt: string;
+    /** The entries of a multiple choice answer, else the answer text. */
+    answer: string | string[];
+    note?: string;
+    /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */
+    custom?: true;
 } | {
-  event: "input.dismissed";
-  inputId: string;
-  prompt: string;
+    event: "input.dismissed";
+    inputId: string;
+    prompt: string;
 } | {
-  event: "plan.approved";
-  revision: number;
+    event: "plan.approved";
+    revision: number;
 } | {
-  event: "plan.changes-requested";
-  revision: number;
-  feedback: string;
+    event: "plan.changes-requested";
+    revision: number;
+    feedback: string;
 } | {
-  event: "finished";
-  next: string;
+    event: "finished";
+    next: string;
 } | {
-  event: "cancelled";
-  next: string;
+    event: "cancelled";
+    next: string;
 } | {
-  event: "setup.created";
-  products: string[];
+    event: "setup.created";
+    products: string[];
 };
-declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
+export declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
 /** Resolves once a setup is planning or installing, or once the one being waited on is cancelled; a setup already closed when the wait begins is over, so the wait is for the next one. */
-declare const waitForStart: (client: Pick<CheckoutClient, "state" | "subscribe">) => Promise<Checkout.Status>;
-declare const askSeed: (rest: readonly string[], flags: Parsed["flags"]) => Checkout.InputSeed & {
-  stepId?: string;
+export declare const waitForStart: (client: Pick<CheckoutClient, "state" | "subscribe">) => Promise<Checkout.Status>;
+export declare const askSeed: (rest: readonly string[], flags: Parsed["flags"]) => Checkout.InputSeed & {
+    stepId?: string;
 };
 /** Sets `key=value` in dotenv text, replacing an existing line for the key. */
-declare const upsertEnvLine: (content: string, key: string, value: string) => string;
-declare const main: (argv: readonly string[]) => Promise<undefined>;
-//#endregion
-export { HELP, INSTRUCTIONS, askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, upsertEnvLine, waitForStart };
+export declare const upsertEnvLine: (content: string, key: string, value: string) => string;
+/**
+ * Write the secret `take` returns to `file` under `key`, leaving the file
+ * owner-only. The file is opened before `take` runs, because taking the
+ * secret consumes it and an unwritable destination must fail while it is
+ * still deposited; it is read after, so lines written meanwhile survive.
+ */
+export declare const writeEnvSecret: (file: string, key: string, take: () => Promise<string>) => Promise<void>;
+export declare const main: (argv: readonly string[]) => Promise<undefined>;
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAsBa;cAmCA,eACX;KA4CG;EAAW;EAAsB,OAAO;;;cA8ChC,kBAAmB,MAAK,OAAO;;cA2C/B,qBACX,MAAK,OAAO,YACZ;EAAS;GACT;EAAU;;KA8FP;EACC;;EACA;EAA0B;EAAmB;;EAE7C;EACA;EACA;;EAEA;EACA;;EAEA;;EAEA;EAA0B;EAAiB;;EAC3C;EAAwB;;EACxB;EAAiC;EAAkB;;EACnD;EAAmB;;EACnB;EAAoB;;EACpB;EAAwB;;cAKjB,aACX,QAAQ,SAAS,OACjB,OAAO,SAAS,UACf;;cAkHU,eACX,QAAQ,KAAK,2CAAsC,QAAA,SAAA;cAyExC,UACX,yBACA,OAAO,oBACN,SAAS;EAAc;;;cAoFb,gBAAiB,iBAAiB,aAAa;cA2B/C,OAAc,4BAAuB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAiB;AAmB/C,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAmB;AAE3C,eAAO,MAAM,IAAI,QAgChB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,KAAK,MAAM,WA2CZ,CAAC;AAEF,eAAO,MAAM,YAAY,QA7ClB,MAAM,WA6CgC,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;AA6C1E,kGAAkG;AAClG,eAAO,MAAM,eAAe,GAAI,MAAK,MAAM,CAAC,UAAwB,uBACd,CAAC;AAyCvD,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,GAC7B,MAAK,MAAM,CAAC,UAAwB,EACpC,QAAO;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAkB,EACtD,SAAQ;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAmB,YAInC,CAAC;AA0FxB,KAAK,WAAW,GACZ;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,GAC7B;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IACE,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2GAA2G;IAC3G,MAAM,CAAC,EAAE,IAAI,CAAC;CACf,GACD;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAKnD,eAAO,MAAM,UAAU,GACrB,QAAQ,QAAQ,CAAC,KAAK,EACtB,OAAO,QAAQ,CAAC,KAAK,KACpB,WAAW,EAqEb,CAAC;AA4CF,2LAA2L;AAC3L,eAAO,MAAM,YAAY,GACvB,QAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,6BAiBjD,CAAC;AAwDL,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,MAAM,EAAE,EACvB,OAAO,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,GAAI,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,WAWxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,MAAM,MAAM,OAAO,CAAC,MAAM,CAAC,kBAa5B,CAAC;AAkBF,eAAO,MAAM,IAAI,GAAU,MAAM,SAAS,MAAM,EAAE,uBA+LjD,CAAC"}

package/dist/cli.js

@@ -1,8 +1,8 @@
 import { connectCheckout } from "./client.js";
 import { INPUT_PRESETS, isPresetId, presetInput } from "./presets.js";
-import { AGENT_HEARTBEAT_MS, OPTION_ICONS, classifyChoiceAnswer, currentPlan, isAgentPresent, isClosed, isOptionIcon, parseModelAnswer, parseMultipleAnswer, stepProgress } from "./protocol.js";
+import { AGENT_HEARTBEAT_MS, OPTION_ICONS, classifyChoiceAnswer, currentPlan, isAgentPresent, isClosed, isOptionIcon, isValidModelAnswer, parseEntryPointOptions, parseMultipleAnswer, stepProgress } from "./protocol.js";
 import { spawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
 //#region src/cli.ts
@@ -15,17 +15,16 @@ Commands (the url always comes first):
   ack <message-id>                  Acknowledge a user message.
   ask <prompt> [--placeholder <text>] [--optional] [--step <step-id>] [--wait]
                                     Ask the user for a line of text.
-  ask [prompt] --preset <framework|llm-provider|project> [--only <id,id>] [--choices <id=description,...>] [--default <id>] [--optional] [--step <step-id>] [--wait]
-                                    Ask a standard question. --only restricts the options (one id locks it in); --default preselects one.
+  ask [prompt] --preset <framework|llm-provider> [--only <id,id>] [--choices <id=description,...>] [--default <id>] [--optional] [--step <step-id>] [--wait]
+                                    Ask a standard question. --only restricts the options and leaves out --choices (one id locks it in); --default preselects one.
                                     "framework" answers "<framework>:<language>"; "llm-provider" answers JSON with provider, model and reasoningEffort; the key itself arrives through "env".
-                                    "project" lists the React projects you found as --choices "<path>=<what it is>,..." ahead of "New project"; it answers a path, or "new:<next|vite|react-router|tanstack-start|expo>".
   ask <prompt> --choices <id,id,...> --icons <id=icon,...> [--single] [--default <id>] [--optional] [--step <step-id>] [--wait]
                                     Ask the user to pick from your own options; they may also type their own answer.
                                     The user checks any number of options and the answer is a JSON array of option ids (their own text is one entry).
                                     --single is for options that exclude each other (one framework, one model, yes or no); the answer is then one id.
                                     --icons is required and names an icon for every option, from: ${OPTION_ICONS.join(", ")}.
-  ask <prompt> --product <slug> [--wait]
-                                    Propose adding a product to this setup, such as one another product needs first. Answers "added"; the product and its guide then appear in "status".
+  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 <input-id>                   Block until the user answers or dismisses an input. A multi-select answer prints as an array.
   plan (<markdown> | --file <path>) [--wait]
@@ -40,7 +39,7 @@ Commands (the url always comes first):
   done [--summary <text>] [--preview <url>]
                                     Mark every remaining step done and propose closing; the user closes it.
 `;
-const INSTRUCTIONS = (url) => `You are the coding agent for a setup 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.
+const agentInstructions = (url) => `You are the coding agent for a setup 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.
 
 First, start a persistent Monitor on
   npx setup-agent ${url} stream
@@ -57,13 +56,14 @@ Keep the stream running while you wait. Do not inspect the project, fetch guides
 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:
-  npx setup-agent ${url} ask "Which project should I install into?" --placeholder "An absolute path, or a path for a new Next.js app" --wait
+  npx setup-agent ${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:
   npx setup-agent ${url} ask --preset framework
   npx setup-agent ${url} ask --preset llm-provider
-If a product's guide needs another product the project does not have yet (most need assistant-ui installed and rendering a thread), do not stop and do not install it on the side. Propose adding it to this setup:
-  npx setup-agent ${url} ask "assistant-ui is not installed in this project yet. Add it to this setup?" --product assistant-ui --wait
-On "added", run "status", fetch the new product's guide, and install it first in your plan. If the user dismisses it, follow what the guide says about the missing product.
+The setup's products are starting names and guide references. 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:
+  npx setup-agent ${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 block with "wait <input-id>" only when nothing else can proceed. 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:
   npx setup-agent ${url} plan --file <path> --wait
@@ -82,6 +82,7 @@ Before that, start the project's dev server in the background when the project h
   npx setup-agent ${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;
 const parseArgs = (argv) => {
 	const positional = [];
 	const flags = /* @__PURE__ */ new Map();
@@ -376,6 +377,38 @@ const askSeed = (rest, flags) => {
 	const stepId = flagText(flags, "step");
 	const optional = flags.has("optional");
 	const fallback = flagText(flags, "default");
+	if (flags.has("entry-points")) {
+		if ([
+			"preset",
+			"product",
+			"choices",
+			"icons",
+			"multiple",
+			"single",
+			"only",
+			"placeholder"
+		].some((flag) => flags.has(flag))) return fail("--entry-points cannot be combined with other input kinds, --multiple, --single or --only");
+		const json = flagText(flags, "entry-points");
+		let value;
+		try {
+			value = JSON.parse(json ?? "");
+		} catch {
+			return fail("--entry-points needs a JSON array of options");
+		}
+		const options = parseEntryPointOptions(value);
+		if (!options) return fail("--entry-points needs 1–3 unique options with id, label, description and entryPoint {formFactor, placement, trigger, recommended?}; at most one is recommended");
+		if (fallback !== void 0 && !options.some((option) => option.id === fallback)) return fail(`no option "${fallback}" to default to`);
+		const prompt = rest[0] ?? fail("usage: ask <prompt> --entry-points '<JSON array>'");
+		if (prompt.trim() === "") return fail("an entry-point prompt cannot be empty");
+		return {
+			kind: "entry-point",
+			prompt,
+			options,
+			...fallback !== void 0 && { default: fallback },
+			optional,
+			...stepId !== void 0 && { stepId }
+		};
+	}
 	const preset = flagText(flags, "preset");
 	if (preset !== void 0) {
 		if (!isPresetId(preset)) return fail(`unknown preset "${preset}"; use ${Object.keys(INPUT_PRESETS).join(" or ")}`);
@@ -446,15 +479,38 @@ const askSeed = (rest, flags) => {
 		...stepId !== void 0 && { stepId }
 	};
 };
+const assertEnvKey = (key) => {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`"${key}" is not an environment variable name`);
+};
 /** Sets `key=value` in dotenv text, replacing an existing line for the key. */
 const upsertEnvLine = (content, key, value) => {
+	assertEnvKey(key);
 	const line = `${key}=${value}`;
 	const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
-	const index = lines.findIndex((entry) => new RegExp(`^(export\\s+)?${key}\\s*=`).test(entry));
+	const index = lines.findIndex((entry) => /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(entry)?.[1] === key);
 	if (index === -1) lines.push(line);
 	else lines[index] = line;
 	return `${lines.join("\n")}\n`;
 };
+/**
+* Write the secret `take` returns to `file` under `key`, leaving the file
+* owner-only. The file is opened before `take` runs, because taking the
+* secret consumes it and an unwritable destination must fail while it is
+* still deposited; it is read after, so lines written meanwhile survive.
+*/
+const writeEnvSecret = async (file, key, take) => {
+	assertEnvKey(key);
+	const handle = await open(file, "a+", 384);
+	try {
+		await handle.chmod(384);
+		const value = await take();
+		const current = await handle.readFile("utf8");
+		await handle.truncate(0);
+		await handle.writeFile(upsertEnvLine(current, key, value));
+	} finally {
+		await handle.close();
+	}
+};
 const answerFields = (input, answer) => ({
 	answer: input.multiple && parseMultipleAnswer(answer) || answer,
 	...input.note !== void 0 && { note: input.note },
@@ -579,16 +635,19 @@ const main = async (argv) => {
 				const inputId = rest[0] ?? fail(usage);
 				const envKey = rest[1] ?? fail(usage);
 				if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(envKey)) fail(`"${envKey}" is not an environment variable name`);
-				const input = requireState(client).inputs.find((candidate) => candidate.id === inputId) ?? fail(`no input "${inputId}"`);
+				const state = requireState(client);
+				const input = state.inputs.find((candidate) => candidate.id === inputId) ?? fail(`no input "${inputId}"`);
+				const setupId = state.id ?? fail("the setup has not been created yet");
+				if (isClosed(state)) fail("the setup is not open");
 				if (input.status !== "answered") fail(`input "${inputId}" is ${input.status}`);
-				if (parseModelAnswer(input.answer ?? "") === void 0) fail(`input "${inputId}" is not an llm-provider answer`);
+				if (input.kind !== "model" || !isValidModelAnswer(input, input.answer ?? "")) fail(`input "${inputId}" is not an llm-provider answer`);
 				const file = resolve(flagText(flags, "file") ?? ".env.local");
-				const response = await fetch(`${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}`);
-				if (response.status === 404) fail(`the key for "${inputId}" was already taken or never deposited`);
-				if (!response.ok) fail(`could not fetch the key: ${response.status}`);
-				const value = await response.text();
-				const current = await readFile(file, "utf8").catch(() => "");
-				await writeFile(file, upsertEnvLine(current, envKey, value));
+				await writeEnvSecret(file, envKey, async () => {
+					const response = await fetch(`${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}?setup=${encodeURIComponent(setupId)}`);
+					if (response.status === 404) fail(`the key for "${inputId}" was already taken or never deposited`);
+					if (!response.ok) fail(`could not fetch the key: ${response.status}`);
+					return response.text();
+				});
 				print({
 					ok: true,
 					envKey,
@@ -631,6 +690,6 @@ const main = async (argv) => {
 	}
 };
 //#endregion
-export { HELP, INSTRUCTIONS, askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, upsertEnvLine, waitForStart };
+export { HELP, INSTRUCTIONS, agentInstructions, askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, upsertEnvLine, waitForStart, writeEnvSecret };
 
 //# sourceMappingURL=cli.js.map