@getnoan/wizard 0.1.5 → 0.1.6

package/README.md

@@ -8,7 +8,8 @@ npx -y @getnoan/wizard@latest
 
 It takes your NOAN API key, points your coding assistants at the NOAN MCP server, installs the
 NOAN skill, checks whether your fact layer has anything in it, and, if you want, sets up the six
-open-source agents on your own GitHub account. Then it tells you what it did and what to do next.
+open-source agents on your own GitHub account and gets the two web agents — booking pages and a
+site chat — ready to deploy. Then it tells you what it did and what to do next.
 Run it again any time; every write is a merge, and nothing you have is overwritten.
 
 ## What it does
@@ -41,7 +42,20 @@ Run it again any time; every write is a merge, and nothing you have is overwritt
    running — `https://openrouter.ai/api`, say, or your own gateway — and the wizard verifies your key
    against *that* endpoint, stores it as `LLM_API_KEY`, and records the endpoint as a repository
    variable so the fork actually uses it. Unset, nothing changes: it asks for an Anthropic key.
-6. **The report.** What happened, and the one thing to do next.
+6. **The web agents** (optional, `--meetings`, `--chat`). Two agents run as always-on services on
+   your own domain rather than as scheduled jobs, so they live in their own repos:
+   [Verity Meetings](https://github.com/getnoan/verity-meetings) (booking pages) and
+   [Verity Chat](https://github.com/getnoan/verity-chat) (a chat widget for your website). For each
+   one you pick, the wizard forks the repo to your account, runs its seed scripts so its starting
+   instructions are in your workspace (in a stack of their own, apart from any other agent's), boots
+   it locally with no keys to prove it works, and writes a gitignored `.env` in the clone with the
+   block slugs. Deploying needs accounts only you can create — a host, a Supabase project, and for
+   Meetings, Google Calendar credentials — so the report hands your assistant the rest of the repo's
+   `INSTALL.md` and a one-click Render deploy link.
+
+   Your personal NOAN key is **not** written into either service's `.env`: these answer the open
+   internet, so each gets a NOAN key made for it alone. The report says so.
+7. **The report.** What happened, and the one thing to do next.
 
 ## For a coding assistant
 
@@ -55,7 +69,9 @@ NOAN_API_KEY=npak_… npx -y @getnoan/wizard@latest --yes --json
 (progress goes to stderr) with a `next` list an agent can act on, including the first-connect
 hand-off when the workspace is empty. `--agents` adds the pack step; it reads `ANTHROPIC_API_KEY`,
 `RESEND_API_KEY`, `DATABASE_URL`, `FIRECRAWL_API_KEY`, `MAIL_FROM`, `REPLY_TO` and `ESCALATE_TO`
-from the environment and skips what is missing, saying so.
+from the environment and skips what is missing, saying so. `--meetings` and `--chat` add the web
+agents; the chat reads its model key from the same variables as the pack (or reuses the pack
+step's in the same run), and a `next` item per service carries the deploy hand-off.
 
 Exit codes: 0 done, 2 the key did not work, 3 cancelled, 1 anything else.
 
@@ -69,6 +85,8 @@ Exit codes: 0 done, 2 the key did not work, 3 cancelled, 1 anything else.
 | `--global` | user-scope client config instead of project scope |
 | `--dir <path>` | the project directory (default: current) |
 | `--agents` / `--no-agents` | include or skip the agent pack step |
+| `--meetings` / `--no-meetings` | include or skip Verity Meetings (booking pages) |
+| `--chat` / `--no-chat` | include or skip Verity Chat (a chat widget for your site) |
 | `--no-mcp`, `--no-skill` | skip a step |
 | `--dry-run` | show every write without making it |
 | `--no-telemetry` | send nothing about this run (also `NOAN_WIZARD_NO_TELEMETRY`, `DO_NOT_TRACK`, or any `CI`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnoan/wizard",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "One command from nothing to a grounded agent: sign in to NOAN, wire your coding assistant, install the skill, and set up the agent pack.",
   "license": "MIT",
   "type": "module",

package/src/args.mjs

@@ -11,7 +11,10 @@ What it does, in order:
   4. Workspace checks whether your fact layer has anything in it; if not, hands the
                seeding to your assistant (it has the procedure) rather than guessing
   5. Agents    optionally sets up the open-source agent pack on your GitHub account
-  6. Report    says what it did, and what to do next
+  6. Web       optionally forks Verity Meetings (booking pages) and Verity Chat (a chat
+               widget for your site), seeds their facts, proves each boots locally, and
+               hands the deploy to your assistant
+  7. Report    says what it did, and what to do next
 
 Options:
   -y, --yes            non-interactive: take every default, never prompt (for an agent mid-session)
@@ -21,6 +24,8 @@ Options:
                        instead of project scope (.mcp.json, .cursor/mcp.json, .vscode/mcp.json)
   --dir <path>         the project directory (default: the current directory)
   --agents             also set up the agent pack (default: ask; with --yes: skip unless given)
+  --meetings           also set up Verity Meetings, booking pages on your own domain (same default)
+  --chat               also set up Verity Chat, a chat widget for your website (same default)
   --no-mcp             skip the client wiring
   --no-skill           skip the skill install
   --dry-run            show every write without making it
@@ -32,7 +37,7 @@ Exit codes: 0 done · 2 the key did not work · 3 cancelled · 1 anything else
 `;
 
 export function parseArgs(argv) {
-  const a = { yes: false, json: false, apiKey: null, global: false, dir: process.cwd(), agents: null,
+  const a = { yes: false, json: false, apiKey: null, global: false, dir: process.cwd(), agents: null, meetings: null, chat: null,
               mcp: true, skill: true, dryRun: false, telemetry: true, help: false, version: false, unknown: [] };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -46,6 +51,10 @@ export function parseArgs(argv) {
     else if (t.startsWith("--dir=")) a.dir = t.slice(6);
     else if (t === "--agents") a.agents = true;
     else if (t === "--no-agents") a.agents = false;
+    else if (t === "--meetings") a.meetings = true;
+    else if (t === "--no-meetings") a.meetings = false;
+    else if (t === "--chat") a.chat = true;
+    else if (t === "--no-chat") a.chat = false;
     else if (t === "--no-mcp") a.mcp = false;
     else if (t === "--no-skill") a.skill = false;
     else if (t === "--dry-run") a.dryRun = true;

package/src/report.mjs

@@ -15,6 +15,13 @@ export function renderReport(report, { json = false } = {}) {
   if (s.skill?.rows) L.push(`skill: ${s.skill.rows.map(r => `${r.id} (${r.written} written)`).join(" · ")}; pointers: ${s.skill.pointers.map(p => p.action).join(", ")}`);
   if (s.workspace) L.push(`facts: ${s.workspace.count ?? "?"} (${s.workspace.state})`);
   if (s.agents && !s.agents.skipped) L.push(s.agents.ok ? `agents: ${s.agents.repo || s.agents.dest} — ${s.agents.agentName || "your agent"}, ${s.agents.secrets.length} secrets, ${s.agents.variables.length} variables, safe mode on` : `agents: not set up (${s.agents.reason})`);
+  if (s.web && !s.web.skipped) for (const [id, w] of Object.entries(s.web)) {
+    if (!w.ok) { L.push(`${id}: not set up (${w.reason})`); continue; }
+    if (report.dryRun) { L.push(`${id}: would fork to ${w.dest}, run ${w.seeds.length} seed(s), boot it locally and write its .env${w.missing?.length ? ` (still needs ${w.missing.join(", ")})` : ""}`); continue; }
+    const seeded = w.seeds.filter(r => r.action === "ran").length;
+    const local = w.local?.ok ? "boots locally" : w.local?.ok === false ? `local boot failed (${w.local.reason})` : "local boot not tried";
+    L.push(`${id}: ${w.repo || w.dest} — ${seeded}/${w.seeds.length} seeds ran, ${local}, .env written${w.missing?.length ? ` (still needs ${w.missing.join(", ")})` : ""}${w.deployUrl ? `, deploy: ${w.deployUrl}` : ""}`);
+  }
   if (report.next?.length) { L.push("", "──────── next ────────"); for (const n of report.next) L.push(`• ${n.say}${n.why ? `  (${n.why})` : ""}`); }
   L.push("");
   return L.join("\n");

package/src/run.mjs

@@ -7,6 +7,7 @@ import { writeEnv, ensureGitignored } from "./env-file.mjs";
 import { wireClients, MANUAL_CLIENTS } from "./clients.mjs";
 import { fetchSkillFiles, skillTargets, installSkill, writePointers } from "./skill.mjs";
 import * as pack from "./agents.mjs";
+import * as web from "./web.mjs";
 import { capture } from "./telemetry.mjs";
 import { renderReport } from "./report.mjs";
 
@@ -86,17 +87,36 @@ export async function run(args) {
   ui.step(5, "The agent pack");
   let wantAgents = args.agents;
   if (wantAgents == null) wantAgents = ui.interactive ? await ui.confirm("Set up the six open-source agents on your GitHub account too?", false) : false;
-  if (wantAgents) report.steps.agents = await setupAgents({ args, ui, dir, key, me, report });
+  // Carries the model key and the agent's name from the pack step to the web step, so a run that
+  // does both asks once. Never put in the report: the report is printed, and --json is parsed.
+  const shared = {};
+  if (wantAgents) report.steps.agents = await setupAgents({ args, ui, dir, key, me, report, shared });
   else { ui.info("skipped" + (args.yes && args.agents == null ? " (pass --agents to include it)" : "")); report.steps.agents = { skipped: true }; }
 
-  /* 6. report */
+  /* 6. web agents */
+  ui.step(6, "The web agents");
+  const wantWeb = [];
+  for (const [id, agent] of Object.entries(web.WEB_AGENTS)) {
+    let want = args[id];
+    if (want == null) want = ui.interactive ? await ui.confirm(`Set up ${agent.label} — ${agent.what}?`, false) : false;
+    if (want) wantWeb.push(id);
+  }
+  if (!wantWeb.length) {
+    ui.info("skipped" + (args.yes && args.meetings == null && args.chat == null ? " (pass --meetings and/or --chat to include them)" : ""));
+    report.steps.web = { skipped: true };
+  } else {
+    report.steps.web = {};
+    for (const id of wantWeb) report.steps.web[id] = await setupWeb({ id, args, ui, dir, key, me, report, shared });
+  }
+
+  /* 7. report */
   report.next.push({ id: "open", say: `Open ${APP_URL} to see the workspace your assistant is grounded in.` });
   return finish(0);
 }
 
 async function ask(ui, q, o) { return ui.ask(q, o); }
 
-async function setupAgents({ args, ui, dir, key, me, report }) {
+async function setupAgents({ args, ui, dir, key, me, report, shared = {} }) {
   const ready = pack.ghReady();
   if (!ready.ok) { ui.warn(ready.reason); return { ok: false, reason: ready.reason }; }
   const fork = pack.forkAndClone(dir, { dryRun: args.dryRun });
@@ -196,5 +216,63 @@ async function setupAgents({ args, ui, dir, key, me, report }) {
   }
   out.repo = pack.repoSlug(fork.dest);
   out.agentName = identity.AGENT_NAME;
+  Object.assign(shared, { modelKey: anthropic, modelKeyName: mName, modelBase: mBase, agentName: identity.AGENT_NAME });
+  return out;
+}
+
+/** One web agent: fork, seed, prove it boots, write its .env, hand the deploy to the assistant.
+ *  What it returns goes in the report, so it carries names and outcomes — never a key. */
+async function setupWeb({ id, args, ui, dir, key, me, report, shared }) {
+  const agent = web.WEB_AGENTS[id];
+  ui.info(`${agent.label}:`);
+  const ready = pack.ghReady();
+  if (!ready.ok) { ui.warn(ready.reason); return { ok: false, reason: ready.reason }; }
+  const fork = web.forkAndCloneWeb(dir, agent, { dryRun: args.dryRun });
+  ui.ok(`${fork.action}: ${fork.dest}${fork.error ? ` — ${fork.error}` : ""}`);
+  if (fork.error) return { ok: false, reason: fork.error };
+  const out = { ok: true, dest: fork.dest, seeds: [], skipped: [] };
+
+  // Seeds run under the person's own key: setting up their workspace is theirs to do.
+  const seeds = web.runWebSeeds(fork.dest, agent, { NOAN_PERSONAL_API_KEY: key }, { dryRun: args.dryRun });
+  out.seeds = seeds.rows;
+  for (const r of seeds.rows) (r.action === "failed" || r.action === "missing" ? ui.warn : ui.ok)(`${r.seed}: ${r.action}${r.slugs != null ? ` (${r.slugs} slug(s))` : ""}${r.error ? ` — ${r.error}` : ""}`);
+
+  // INSTALL.md step 0, for them: the service boots with no keys at all.
+  if (args.dryRun) out.local = { ok: null, reason: "dry run" };
+  else if (existsSync(fork.dest)) {
+    out.local = await web.proveLocally(fork.dest, agent);
+    if (out.local.ok) ui.ok(`boots locally with no keys (${out.local.probes.join(", ")} answered)`);
+    else ui.warn(`did not boot locally: ${out.local.reason} — INSTALL.md step 0 runs the same thing by hand`);
+  }
+
+  // The chat needs a model key; reuse the pack step's if this run had one, else env, else ask.
+  let modelKey = null, modelKeyName = "ANTHROPIC_API_KEY", modelBase = "";
+  if (agent.needsModelKey) {
+    if (shared.modelKey) ({ modelKey, modelKeyName, modelBase } = shared);
+    else {
+      try { modelBase = pack.modelBase(); } catch (e) { ui.warn(e.message); out.skipped.push({ name: "model key", why: e.message }); modelBase = null; }
+      if (modelBase !== null) {
+        modelKeyName = pack.modelKeyName();
+        modelKey = (process.env[modelKeyName] || process.env[modelKeyName === "LLM_API_KEY" ? "ANTHROPIC_API_KEY" : "LLM_API_KEY"] || "").trim()
+          || (ui.interactive ? await ui.ask(`API key for ${modelBase ? new URL(modelBase).host : "Anthropic"} (the chat's model; blank to add it later)`, { secret: true }) : "");
+        if (modelKey) {
+          const verdict = await pack.verifyModelKey(modelKey, modelBase);
+          if (verdict === false) { ui.warn(`${modelKeyName} was not accepted by its service; not written`); out.skipped.push({ name: modelKeyName, why: "rejected" }); modelKey = null; }
+        } else out.skipped.push({ name: modelKeyName, why: "not provided" });
+      }
+    }
+  }
+
+  const agentName = shared.agentName || pack.agentIdentity({ name: process.env.AGENT_NAME }).AGENT_NAME;
+  const pairs = web.webEnv(agent, { slugs: seeds.slugs, company: me.project?.name || "", agentName, modelKey, modelKeyName, modelBase: modelBase || "" });
+  const env = web.writeWebEnv(fork.dest, pairs, { dryRun: args.dryRun });
+  ui.ok(`${args.dryRun ? "would write" : env.created ? "wrote" : env.changed ? "updated" : "kept"} ${env.path} (${env.keys.join(", ") || "nothing new"}); .gitignore: ${env.gitignore}`);
+  out.env = { path: env.path, keys: env.keys, gitignore: env.gitignore };
+  const missingModelKey = agent.needsModelKey && !modelKey ? modelKeyName : null;
+  if (missingModelKey) { ui.warn(`no ${missingModelKey} written: the chat cannot answer until it has one`); out.missing = [missingModelKey]; }
+
+  out.repo = args.dryRun ? null : pack.repoSlug(fork.dest);
+  out.deployUrl = web.renderDeployUrl(out.repo);
+  report.next.push(web.webNext(agent, { dest: fork.dest, deployUrl: out.deployUrl, missingModelKey }));
   return out;
 }

package/src/web.mjs

@@ -0,0 +1,169 @@
+/**
+ * The web-facing agents: getnoan/verity-meetings (booking pages) and getnoan/verity-chat (a chat
+ * widget for your site). They are always-on services on the user's own domain, not scheduled
+ * jobs, so they live in their own repos and deploy to a host (Render by default), not to Actions.
+ *
+ * The wizard does the part that needs no account the user has not already given it:
+ *   fork and clone → seed the service's facts (under the user's own key, a human action) →
+ *   prove the service boots locally with NO keys → write a gitignored .env in the clone with what
+ *   is known → hand the rest to the coding assistant, INSTALL.md's remaining steps plus a Render
+ *   deploy link.
+ * The rest — a host account, a Supabase project, Google calendar credentials, DNS, the embed tag on
+ * their site — needs the person, and INSTALL.md marks each of those HUMAN.
+ *
+ * The personal NOAN key is NOT written into the service's .env. That key reaches the whole
+ * workspace, and these services answer the open internet; each gets a key made for it, and the
+ * hand-off says so. The seeds are different: seeding is a person setting up their own workspace.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import path from "node:path";
+import { gh, parseSeedOutput, randomSecret } from "./agents.mjs";
+import { writeEnv, ensureGitignored } from "./env-file.mjs";
+
+/** One entry per web agent. `boot` is INSTALL.md step 0 — the no-keys local run — and `probe` is
+ *  what proves it came up; both are the repos' own CI checks, so a green CI there means this works. */
+export const WEB_AGENTS = {
+  meetings: {
+    label: "Verity Meetings",
+    repo: "getnoan/verity-meetings",
+    dirName: "verity-meetings",
+    what: "booking pages on your own domain",
+    seeds: ["agents/seed-scheduling.mjs", "agents/seed-booking.mjs"],
+    boot: (port) => ({
+      args: ["booking/server.mjs"],
+      env: { BOOKING_ENABLED: "1", BOOKING_STORE: "memory", BOOKING_DRY_RUN: "1",
+             BOOKING_HOSTS: "founder@example.com,teammate@example.com",
+             BOOKING_PUBLIC_URL: `http://127.0.0.1:${port}`, PORT: String(port) },
+    }),
+    probe: ["/healthz", "/alex"],
+    needsModelKey: false,
+    // INSTALL.md steps left after the wizard: it has seeded (step 1's second half).
+    remaining: "step 2 (Google calendar credentials), step 3 (Supabase + schema.sql), step 4 (deploy), step 5 (DNS)",
+    after: "Then edit the Booking Types fact in NOAN: the starters use placeholder hosts, and a type whose host is not in BOOKING_HOSTS is not served.",
+  },
+  chat: {
+    label: "Verity Chat",
+    repo: "getnoan/verity-chat",
+    dirName: "verity-chat",
+    what: "a grounded chat widget for your website",
+    seeds: ["agents/seed-site-chat.mjs"],
+    boot: (port) => ({
+      args: ["--input-type=module", "-e", `const { server } = await import("./site-web/server.mjs"); server.listen(${port}, "127.0.0.1");`],
+      env: { NODE_ENV: "test" },
+    }),
+    probe: ["/healthz", "/widget.js"],
+    needsModelKey: true,
+    remaining: "step 3 (Supabase + schema.sql — the daily budget refuses every chat until it can meter), step 4 (deploy), step 5 (the embed tag on your site)",
+    after: "Set SITE_ALLOWED_ORIGINS to your site's origins and SITE_CHAT_GROUNDING_SLUGS to the blocks it may answer from.",
+  },
+};
+
+/** Fork (or reuse) and clone a web agent's repo into dir/<dirName>. */
+export function forkAndCloneWeb(dir, agent, { dryRun = false } = {}) {
+  const dest = path.join(dir, agent.dirName);
+  if (existsSync(path.join(dest, ".git"))) return { dest, action: "reused existing clone" };
+  if (dryRun) return { dest, action: "would fork and clone" };
+  const r = gh(["repo", "fork", agent.repo, "--clone", "--remote=false", dest]);
+  if (!r.ok) return { dest, action: "fork failed", error: r.err.split("\n")[0] };
+  return { dest, action: "forked and cloned" };
+}
+
+/** Run a web agent's seed scripts from the repo root; collect the block slugs they print. */
+export function runWebSeeds(dest, agent, env, { dryRun = false } = {}) {
+  const slugs = {}; const rows = [];
+  for (const s of agent.seeds) {
+    const p = path.join(dest, s);
+    // A dry run has no clone yet, so "missing" there would be a false alarm.
+    if (dryRun && !existsSync(dest)) { rows.push({ seed: s, action: "would run" }); continue; }
+    if (!existsSync(p)) { rows.push({ seed: s, action: "missing" }); continue; }
+    if (dryRun) { rows.push({ seed: s, action: "would run" }); continue; }
+    const r = spawnSync(process.execPath, [p], { cwd: dest, encoding: "utf8", env: { ...process.env, ...env } });
+    const found = parseSeedOutput((r.stdout || "") + "\n" + (r.stderr || ""));
+    Object.assign(slugs, found);
+    rows.push({ seed: s, action: r.status === 0 ? "ran" : "failed", slugs: Object.keys(found).length,
+      error: r.status === 0 ? undefined : (r.stderr || r.stdout || "").trim().split("\n").slice(-1)[0] });
+  }
+  return { slugs, rows };
+}
+
+export function freePort() {
+  return new Promise((res, rej) => {
+    const s = createServer(); s.unref(); s.on("error", rej);
+    s.listen(0, "127.0.0.1", () => { const { port } = s.address(); s.close(() => res(port)); });
+  });
+}
+
+/** INSTALL.md step 0, run for the user: boot the service with no keys, hit its probes, stop it.
+ *  The child gets PATH and HOME only — never the wizard's environment — so no key it holds can
+ *  reach the service, and a block slug in the shell cannot switch booking out of its local mode. */
+export async function proveLocally(dest, agent, { timeoutMs = 15000, fetchImpl = fetch } = {}) {
+  const port = await freePort();
+  const { args, env } = agent.boot(port);
+  const child = spawn(process.execPath, args, { cwd: dest, stdio: ["ignore", "ignore", "pipe"],
+    env: { PATH: process.env.PATH || "", HOME: process.env.HOME || "", ...env } });
+  let stderr = ""; child.stderr.on("data", d => { stderr = (stderr + d).slice(-2000); });
+  const exited = new Promise(r => child.on("exit", code => r(code)));
+  const base = `http://127.0.0.1:${port}`;
+  try {
+    const deadline = Date.now() + timeoutMs;
+    let up = false;
+    while (Date.now() < deadline && !up) {
+      if (child.exitCode !== null) break;
+      try { up = (await fetchImpl(`${base}${agent.probe[0]}`, { signal: AbortSignal.timeout(1000) })).ok; } catch {}
+      if (!up) await new Promise(r => setTimeout(r, 300));
+    }
+    if (!up) return { ok: false, reason: child.exitCode !== null ? `exited (${child.exitCode}): ${stderr.trim().split("\n").slice(-1)[0] || "no output"}` : "did not answer in time" };
+    for (const p of agent.probe.slice(1)) {
+      const r = await fetchImpl(`${base}${p}`, { signal: AbortSignal.timeout(3000) }).catch(() => null);
+      if (!r?.ok) return { ok: false, reason: `${p} answered ${r ? r.status : "nothing"}` };
+    }
+    return { ok: true, probes: agent.probe };
+  } finally {
+    if (child.exitCode === null) { child.kill(); await Promise.race([exited, new Promise(r => setTimeout(r, 2000))]); }
+  }
+}
+
+/** Render's one-click deploy for a repo that carries a render.yaml. */
+export const renderDeployUrl = (slug) => (slug ? `https://render.com/deploy?repo=https://github.com/${slug}` : null);
+
+/** What goes in the clone's .env. Never the personal NOAN key (see the header). The model key goes
+ *  under the name the service reads for the chosen endpoint (the pack's rule: ANTHROPIC_API_KEY for
+ *  the default vendor, LLM_API_KEY plus ANTHROPIC_BASE_URL for anything else). */
+export function webEnv(agent, { slugs = {}, company = "", agentName = "", modelKey = null, modelKeyName = "ANTHROPIC_API_KEY", modelBase = "" } = {}) {
+  return {
+    ...slugs,
+    ...(company && { COMPANY_NAME: company }),
+    ...(agentName && { AGENT_NAME: agentName }),
+    ...(agent === WEB_AGENTS.chat && { SESSION_SECRET: randomSecret() }),
+    ...(agent.needsModelKey && modelKey && { [modelKeyName]: modelKey }),
+    ...(agent.needsModelKey && modelKey && modelBase && { ANTHROPIC_BASE_URL: modelBase }),
+  };
+}
+
+/** Write the clone's .env: gitignored FIRST (the exported repos ship no .gitignore, and this file
+ *  can hold a model key), and a SESSION_SECRET that is already there is kept — rotating it would
+ *  sign out every visitor of a chat already deployed from it. */
+export function writeWebEnv(dest, pairs, { dryRun = false } = {}) {
+  const gitignore = ensureGitignored(dest, { dryRun });
+  const envPath = path.join(dest, ".env");
+  const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  const keep = { ...pairs };
+  if (/^\s*(?:export\s+)?SESSION_SECRET\s*=\s*\S/m.test(existing)) delete keep.SESSION_SECRET;
+  const env = writeEnv(dest, keep, { dryRun });
+  return { ...env, gitignore: gitignore.action, keys: Object.keys(keep) };
+}
+
+/** The hand-off line for the report's `next` list: what is left, and where to read how. */
+export function webNext(agent, { dest, deployUrl, missingModelKey = null }) {
+  return {
+    id: `web-${agent.dirName}`,
+    say: `Finish ${agent.label} (${agent.what}): in ${dest}, follow INSTALL.md ${agent.remaining}.`
+      + (missingModelKey ? ` It needs ${missingModelKey} too — the wizard had none to write.` : "")
+      + (deployUrl ? ` One-click deploy: ${deployUrl}.` : "")
+      + ` Create a NOAN API key for this service alone and set it as NOAN_AGENT_API_KEY in the deploy env — not your personal key.`
+      + ` ${agent.after}`,
+    why: "the rest needs accounts only you can create; INSTALL.md marks those steps HUMAN",
+  };
+}