@getnoan/wizard 0.1.6 → 0.1.8

package/README.md

@@ -14,8 +14,8 @@ Run it again any time; every write is a merge, and nothing you have is overwritt
 
 ## What it does
 
-1. **Your key.** Create one at app.getnoan.com → Settings → API → New key and paste it in (it is
-   not echoed). The wizard checks it with `GET /me`, writes it to `.env` as `NOAN_API_KEY` and
+1. **Your key.** Create your own at app.getnoan.com → Settings → API → New key and paste it in (it is
+   not echoed). This is *your* key, for you and your coding assistant. The wizard checks it with `GET /me`, writes it to `.env` as `NOAN_API_KEY` and
    `NOAN_PERSONAL_API_KEY`, and makes sure `.env` is gitignored. Already have `NOAN_API_KEY` in
    your environment? It uses that and never asks.
 2. **Your coding assistants.** Whatever is installed gets the MCP address `https://mcp.getnoan.com/mcp`
@@ -31,12 +31,26 @@ Run it again any time; every write is a merge, and nothing you have is overwritt
 4. **Your fact layer.** If the workspace holds fewer than ten facts, the wizard does not guess
    facts for you. It hands the seeding to your assistant, which has the procedure from the skill:
    read your website, repo and docs, propose a structure, and write only after you say yes.
-5. **The agent pack** (optional, `--agents`). Asks what to call your agent — Verity by default, the
-   name she answers to in NOAN — then forks [getnoan/agent-pack](https://github.com/getnoan/agent-pack)
+5. **The agent pack** (optional, `--agents`). The agents should run as **NOAN's agent identity**,
+   not as you: an Owner creates it once under Settings → Team → Agent, and mints its keys under
+   Settings → API → Agent API Keys. The wizard asks for that agent key (or takes `--agent-key` /
+   `NOAN_AGENT_API_KEY`) and checks it is the agent's. The agents then run on it, answer to the
+   agent's id (`AGENT_IDENTITY_IDS`), and take direction from you (`COMMANDERS`). Work they hand
+   back to a person (the weekly fact review, parked tasks, support follow-ups) goes to you: the
+   `PARK_ASSIGNEES_*`, `FACT_ALIGNMENT_REVIEW_ASSIGNEES`, `REPLY_HUMAN_ASSIGNEES` and
+   `HUMAN_IDENTITIES` variables, which a re-run keeps if you have since changed them. Your own key stays
+   for seeding and your assistant. Skip it and the agents run as you; the wizard warns that your own
+   task comments will then read as the agent's, so steer them by email.
+
+   It asks what to call your agent — Verity by default — then forks [getnoan/agent-pack](https://github.com/getnoan/agent-pack)
    to your account, verifies and stores your model and Resend keys (and optionally a Postgres URL
    and a Firecrawl key) as repository secrets, runs the pack's seed scripts so each agent's starting
    instructions are in your workspace, records the name and the block slugs as repository variables,
-   and triggers one dry run. Safe mode stays on: the wizard never sets `DRY_RUN` to 0. That switch is yours.
+   and triggers one dry run. Safe mode stays on: the wizard never sets `DRY_RUN` to 0, and a re-run keeps the fork's `DRY_RUN`, and its `STATE_BACKEND` unless you give a Postgres URL. That switch is yours.
+
+   The newsletter signs unsubscribe links with `NEWSLETTER_UNSUB_SECRET`, and your site has to check
+   them with the same value. The wizard creates it once, stores it as a repository secret and in
+   `noan-agent-pack/.env` so you can copy it to your site, and keeps it on every re-run.
 
    The model does not have to be Anthropic's. Set `ANTHROPIC_BASE_URL` in the environment before
    running — `https://openrouter.ai/api`, say, or your own gateway — and the wizard verifies your key
@@ -54,7 +68,8 @@ Run it again any time; every write is a merge, and nothing you have is overwritt
    `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.
+   internet, so each gets a NOAN key made for it alone, minted under your NOAN agent
+   (Settings → API → Agent API Keys). The report says so.
 7. **The report.** What happened, and the one thing to do next.
 
 ## For a coding assistant
@@ -82,6 +97,7 @@ Exit codes: 0 done, 2 the key did not work, 3 cancelled, 1 anything else.
 | `-y`, `--yes` | non-interactive |
 | `--json` | machine-readable report (implies `--yes`) |
 | `--api-key <key>` | the NOAN key (else `NOAN_API_KEY`, else a prompt) |
+| `--agent-key <key>` | an agent-owned NOAN key the agent pack runs on (else `NOAN_AGENT_API_KEY`, else a prompt) |
 | `--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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnoan/wizard",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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/agents.mjs

@@ -9,7 +9,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
-import { writeEnv } from "./env-file.mjs";
+import { writeEnv, readEnvValue } from "./env-file.mjs";
 
 export const PACK_REPO = "getnoan/agent-pack";
 
@@ -35,7 +35,8 @@ export function parseSeedOutput(text) {
  *  name for the model key and one of the two is required. It is listed so a caller enumerating
  *  the pack's secrets knows the name exists, not so anyone sets both. */
 export const PACK_SECRETS = ["NOAN_PERSONAL_API_KEY", "RESEND_API_KEY", "ANTHROPIC_API_KEY", "LLM_API_KEY", "DATABASE_URL", "FIRECRAWL_API_KEY", "NEWSLETTER_UNSUB_SECRET"];
-export const PACK_VARS = ["MAIL_FROM", "REPLY_TO", "ESCALATE_TO", "STATE_BACKEND", "ANTHROPIC_BASE_URL", "AGENT_NAME", "COMPANY_NAME", "AGENT_IDENTITY_IDS", "COMMANDERS", "REPORT_RECIPIENT_TAG"];
+export const PACK_VARS = ["MAIL_FROM", "REPLY_TO", "ESCALATE_TO", "STATE_BACKEND", "ANTHROPIC_BASE_URL", "AGENT_NAME", "COMPANY_NAME", "AGENT_IDENTITY_IDS", "COMMANDERS", "REPORT_RECIPIENT_TAG",
+                          "FACT_ALIGNMENT_REVIEW_ASSIGNEES", "PARK_ASSIGNEES_CS", "PARK_ASSIGNEES_SALES", "PARK_ASSIGNEES_ENG", "REPLY_HUMAN_ASSIGNEES", "HUMAN_IDENTITIES"];
 
 /** The pack's model endpoint, from the same variable the pack itself reads. Bare base, no
  *  trailing slash; empty string means the default vendor.
@@ -122,6 +123,30 @@ export function setSecret(dest, name, value, dryRun) {
   const r = spawnSync("gh", ["secret", "set", name], { cwd: dest, input: value, encoding: "utf8" });
   return { name, action: r.status === 0 ? "set" : "failed", error: r.status === 0 ? undefined : (r.stderr || "").trim().split("\n")[0] };
 }
+/** The repository variables already set on the fork, by name. A list that cannot be read is
+ *  empty: the defaults are then written, and the gh failure shows on the set that follows. */
+export function existingVariables(dest, dryRun) {
+  if (dryRun) return new Set();
+  const r = spawnSync("gh", ["variable", "list", "--json", "name", "-q", ".[].name"], { cwd: dest, encoding: "utf8" });
+  return new Set(r.status === 0 ? r.stdout.split("\n").map(s => s.trim()).filter(Boolean) : []);
+}
+/** The variables a re-run must not undo. DRY_RUN=1 only on a fork that has none, since it's the
+ *  user's switch for taking agents live. STATE_BACKEND follows a Postgres URL given on this run,
+ *  else keeps the fork's, so leaving the prompt blank doesn't drop the agents' state ledger. */
+export function forkStateVars(have, { db = "" } = {}) {
+  const set = {}, kept = [];
+  if (have.has("DRY_RUN")) kept.push("DRY_RUN"); else set.DRY_RUN = "1";
+  if (db) set.STATE_BACKEND = "postgres";
+  else if (have.has("STATE_BACKEND")) kept.push("STATE_BACKEND");
+  else set.STATE_BACKEND = "local";
+  return { set, kept };
+}
+/** The repository secrets already set on the fork, by name. Same rules as existingVariables. */
+export function existingSecrets(dest, dryRun) {
+  if (dryRun) return new Set();
+  const r = spawnSync("gh", ["secret", "list", "--json", "name", "-q", ".[].name"], { cwd: dest, encoding: "utf8" });
+  return new Set(r.status === 0 ? r.stdout.split("\n").map(s => s.trim()).filter(Boolean) : []);
+}
 export function setVariable(dest, name, value, dryRun) {
   if (dryRun) return { name, action: "would set" };
   const r = spawnSync("gh", ["variable", "set", name, "--body", value], { cwd: dest, encoding: "utf8" });
@@ -188,5 +213,20 @@ export function dispatchDryRun(dest, workflow, dryRun) {
 
 export const randomSecret = () => randomBytes(24).toString("hex");
 
+export const UNSUB_SECRET = "NEWSLETTER_UNSUB_SECRET";
+
+/** The newsletter signs every unsubscribe link with this secret and the user's own site checks it
+ *  with the same value. A GitHub secret can't be read back, so the clone's .env holds the copy the
+ *  user reads. An existing value is kept: a new one breaks every unsubscribe link already sent. */
+export function unsubSecret(dest, forkSecrets, { dryRun = false } = {}) {
+  const onFork = forkSecrets.has(UNSUB_SECRET);
+  const local = readEnvValue(dest, UNSUB_SECRET);
+  if (local) return { value: local, setOnFork: !onFork, action: onFork ? "kept" : "set from .env" };
+  if (onFork) return { value: null, setOnFork: false, action: "kept, not in .env" };
+  const value = randomSecret();
+  writeEnv(dest, { [UNSUB_SECRET]: value }, { dryRun });
+  return { value, setOnFork: true, action: "created" };
+}
+
 /** Write the pack's .env in the clone so the seeds (and a local run) have what they need. */
 export function writePackEnv(dest, pairs, dryRun) { return writeEnv(dest, pairs, { dryRun }); }

package/src/args.mjs

@@ -20,6 +20,7 @@ Options:
   -y, --yes            non-interactive: take every default, never prompt (for an agent mid-session)
   --json               machine-readable report on stdout (implies --yes)
   --api-key <key>      the NOAN key (else NOAN_API_KEY / NOAN_PERSONAL_API_KEY, else a prompt)
+  --agent-key <key>    an agent-owned NOAN key the agent pack runs on (else NOAN_AGENT_API_KEY, else a prompt)
   --global             write user-scope client config (~/.claude.json, ~/.cursor/mcp.json, ...)
                        instead of project scope (.mcp.json, .cursor/mcp.json, .vscode/mcp.json)
   --dir <path>         the project directory (default: the current directory)
@@ -37,7 +38,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, meetings: null, chat: null,
+  const a = { yes: false, json: false, apiKey: null, agentKey: 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 +47,8 @@ export function parseArgs(argv) {
     else if (t === "--json") { a.json = true; a.yes = true; }
     else if (t === "--api-key") a.apiKey = next();
     else if (t.startsWith("--api-key=")) a.apiKey = t.slice(10);
+    else if (t === "--agent-key") a.agentKey = next();
+    else if (t.startsWith("--agent-key=")) a.agentKey = t.slice(12);
     else if (t === "--global") a.global = true;
     else if (t === "--dir") a.dir = next();
     else if (t.startsWith("--dir=")) a.dir = t.slice(6);

package/src/clients.mjs

@@ -29,7 +29,10 @@ export function mergeJsonServer(existing, container, entry) {
 export function mergeToml(text, table, lines) {
   const block = `[${table}]\n${lines.join("\n")}\n`;
   const src = text || "";
-  const rx = new RegExp(`^\\[${table.replace(/\./g, "\\.")}\\]\\n(?:(?!\\[)[^\\n]*\\n?)*`, "m");
+  // Escape every regex metacharacter, not only the dot: the table name is ours today, but a
+  // partial escape is exactly what CodeQL js/incomplete-sanitization flags, and it is one line.
+  const esc = table.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const rx = new RegExp(`^\\[${esc}\\]\\n(?:(?!\\[)[^\\n]*\\n?)*`, "m");
   if (rx.test(src)) {
     const cur = src.match(rx)[0];
     if (cur.trim() === block.trim()) return { text: src, action: "unchanged" };

package/src/env-file.mjs

@@ -16,6 +16,14 @@ export function upsertEnv(text, pairs) {
   return out.join("\n") + "\n";
 }
 
+/** One key's value from dir/.env, "" when the file or the key is missing. */
+export function readEnvValue(dir, key) {
+  const p = path.join(dir, ".env");
+  if (!existsSync(p)) return "";
+  const m = readFileSync(p, "utf8").match(new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*(\\S+)`, "m"));
+  return m ? m[1].replace(/^["']|["']$/g, "") : "";
+}
+
 export function writeEnv(dir, pairs, { dryRun = false } = {}) {
   const p = path.join(dir, ".env");
   const before = existsSync(p) ? readFileSync(p, "utf8") : "";

package/src/noan.mjs

@@ -3,6 +3,8 @@ export const API = "https://api.getnoan.com/v1";
 export const MCP_URL = "https://mcp.getnoan.com/mcp";
 export const APP_URL = "https://app.getnoan.com";
 export const KEY_PAGE_HINT = "app.getnoan.com → Settings → API → New key";
+/** Where an AGENT-owned key is minted: NOAN's agent identity (role bot), created by an Owner. */
+export const AGENT_KEY_PAGE_HINT = "app.getnoan.com → Settings → API → Agent API Keys";
 
 export function looksLikeKey(k) { return typeof k === "string" && /^npak_[A-Za-z0-9_-]{16,}$/.test(k.trim()); }
 
@@ -20,6 +22,72 @@ export async function whoAmI(key) {
   return { ok: true, project: body.project, identity: body.identity };
 }
 
+/** The pack's variables naming who gets work an agent hands back: identity ids, comma-separated.
+ *  HUMAN_IDENTITIES (email=id pairs) is the sixth, set alongside these. */
+export const HAND_BACK_ASSIGNEE_VARS = ["FACT_ALIGNMENT_REVIEW_ASSIGNEES", "PARK_ASSIGNEES_CS", "PARK_ASSIGNEES_SALES", "PARK_ASSIGNEES_ENG", "REPLY_HUMAN_ASSIGNEES"];
+
+/** Is this /me identity NOAN's agent? Its role is "bot" (and the API gives it no email). */
+export function isAgentIdentity(identity) {
+  return identity?.role === "bot";
+}
+
+/**
+ * Who the agents run as, and who steers them, from GET /me on the keys the user gave.
+ *
+ * NOAN has an agent role: one agent identity per workspace (role bot, no login), which an Owner
+ * creates under Settings → Team → Agent; its keys are minted under Settings → API → Agent API Keys. Its id is what the agents answer to
+ * (AGENT_IDENTITY_IDS: tasks assigned to it trigger them, comments by it are the agent's own).
+ * The people who steer and approve (COMMANDERS) are humans, never the agent.
+ *
+ * Deriving both from one key's /me was wrong either way: a person's key made the person "the
+ * agent", so every comment they wrote was classed as the agent's own and ignored; an agent key
+ * made the agent the only commander, and the agent has no email to be one.
+ *
+ *   person  GET /me of the user's own key (step 1), when it is a person
+ *   agent   GET /me of an agent-owned key, when one was given (or step 1's, if that was the agent)
+ *   commanders  extra addresses (COMMANDERS env or a prompt), comma-separated
+ *
+ * Returns the ids/addresses to configure, which key the agents should run on ("agent" or
+ * "person"), who gets the work the agents hand back (handBack), and the warnings to say out loud.
+ *
+ * handBack matters only under the agent role. On a person's key the pack falls back to that
+ * person (fact alignment's review) or to nobody (parks never read GET /me); on the agent's key
+ * every fallback is deliberately refused, because handing work to the key's owner would hand it
+ * to the agent. So with no hand-back settings an agent-key install files its weekly review, its
+ * parked tasks and its support follow-ups with no person on them, and nothing errors. The person
+ * who ran the wizard is the default owner of all of it. On a person's key handBack stays empty:
+ * that person IS the agent there (AGENT_IDENTITY_IDS), so assigning them would hand the work
+ * straight back to the agents.
+ */
+export function agentRoles({ person = null, agent = null, commanders = "" } = {}) {
+  const warnings = [];
+  const agentId = agent && isAgentIdentity(agent) ? agent.id : null;
+  const humans = new Set(String(commanders || "").split(",").map(s => s.trim().toLowerCase()).filter(Boolean));
+  if (person && !isAgentIdentity(person) && person.email) humans.add(String(person.email).toLowerCase());
+  const out = { agentIds: agentId, commanders: [...humans].join(","), runAs: agentId ? "agent" : "person", warnings };
+  if (!agentId) {
+    // No agent identity: keep the old single-account setup, but say what it costs.
+    out.agentIds = person?.id || null;
+    warnings.push(
+      "No agent key, so the agents run as you and answer to your own account. Every comment you write on a task " +
+      "will read as the agent's own, so steer and approve by email, not task comments. To fix it, create the agent " +
+      `(${AGENT_KEY_PAGE_HINT}) and re-run with --agent-key.`);
+  }
+  if (!out.commanders) warnings.push("No commander: nobody can steer or approve the agents until COMMANDERS lists a person's email.");
+  out.handBack = {};
+  if (out.runAs === "agent") {
+    const human = person && !isAgentIdentity(person) && person.id ? person : null;
+    if (human) {
+      for (const n of HAND_BACK_ASSIGNEE_VARS) out.handBack[n] = human.id;
+      if (human.email) out.handBack.HUMAN_IDENTITIES = `${String(human.email).toLowerCase()}=${human.id}`;
+    } else warnings.push(
+      "No person's key, so the work the agents hand back (the weekly fact review, parked tasks, support follow-ups) " +
+      `has nobody to go to. Set ${HAND_BACK_ASSIGNEE_VARS.join(", ")} on the fork to a person's NOAN identity id ` +
+      "(GET /me with their key), or re-run with your own key first and the agent key as --agent-key.");
+  }
+  return out;
+}
+
 /** How many facts the workspace holds — the signal for "empty, hand the seeding over". */
 export async function factCount(key) {
   const { status, body } = await get("/facts?per_page=1", key);

package/src/run.mjs

@@ -2,7 +2,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { makeUI } from "./ui.mjs";
-import { whoAmI, factCount, classifyWorkspace, looksLikeKey, APP_URL, KEY_PAGE_HINT, MCP_URL } from "./noan.mjs";
+import { whoAmI, factCount, classifyWorkspace, looksLikeKey, APP_URL, KEY_PAGE_HINT, MCP_URL, isAgentIdentity, agentRoles, AGENT_KEY_PAGE_HINT } from "./noan.mjs";
 import { writeEnv, ensureGitignored } from "./env-file.mjs";
 import { wireClients, MANUAL_CLIENTS } from "./clients.mjs";
 import { fetchSkillFiles, skillTargets, installSkill, writePointers } from "./skill.mjs";
@@ -38,7 +38,10 @@ export async function run(args) {
   if (!looksLikeKey(key)) ui.warn("that does not look like a NOAN key (they start with npak_) — checking anyway");
   const me = await whoAmI(key);
   if (!me.ok) { ui.warn(me.reason); report.steps.auth = { ok: false, reason: me.reason }; return finish(2, "cancelled"); }
-  ui.ok(`key accepted: ${me.identity?.email || "?"} in workspace "${me.project?.name || "?"}"`);
+  if (isAgentIdentity(me.identity)) {
+    ui.ok(`key accepted: your NOAN agent "${me.identity?.name || "?"}" (role bot) in workspace "${me.project?.name || "?"}"`);
+    ui.warn("this key belongs to the agent, not to you: your coding assistant will write as the agent too. For your own use, a personal key (" + KEY_PAGE_HINT + ") is the better fit.");
+  } else ui.ok(`key accepted: ${me.identity?.email || "?"} in workspace "${me.project?.name || "?"}"`);
   const env = writeEnv(dir, { NOAN_API_KEY: key, NOAN_PERSONAL_API_KEY: key }, { dryRun: args.dryRun });
   const gi = ensureGitignored(dir, { dryRun: args.dryRun });
   ui.ok(`${env.created ? "wrote" : env.changed ? "updated" : "kept"} ${env.path} (NOAN_API_KEY, NOAN_PERSONAL_API_KEY); .gitignore: ${gi.action}`);
@@ -175,15 +178,49 @@ async function setupAgents({ args, ui, dir, key, me, report, shared = {} }) {
         ? await ui.ask(`Pronouns for ${askedName}, in ${askedName}'s own prose (blank for they/them)`)
         : "") });
 
-  const secrets = { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { [mName]: anthropic }), ...(resend && { RESEND_API_KEY: resend }),
-                    ...(db && { DATABASE_URL: db }), ...(firecrawl && { FIRECRAWL_API_KEY: firecrawl }), NEWSLETTER_UNSUB_SECRET: pack.randomSecret() };
+  /* Who the agents run as, and who steers them (NOAN's agent role). The agents should run on an
+   * AGENT-owned key, so what they write is the agent's and its id is what they answer to; the
+   * people who steer them are humans. Step 1's key is normally the user's own, which stays for
+   * seeding and the coding assistant. See agentRoles in noan.mjs. */
+  let agentKey = null, agentMe = null;
+  if (isAgentIdentity(me.identity)) { agentKey = key; agentMe = me.identity; }
+  else {
+    const given = (args.agentKey || process.env.NOAN_AGENT_API_KEY || "").trim()
+      || (ui.interactive ? await ui.ask(`Agent key, so the agents run as your NOAN agent rather than as you (${AGENT_KEY_PAGE_HINT}; blank to skip)`, { secret: true }) : "");
+    if (given) {
+      const am = await whoAmI(given);
+      if (!am.ok) ui.warn(`agent key not accepted (${am.reason}); continuing without one`);
+      else if (am.project?.id && me.project?.id && am.project.id !== me.project.id) ui.warn(`that agent key is for workspace "${am.project?.name}", not "${me.project?.name}"; continuing without one`);
+      else if (!isAgentIdentity(am.identity)) ui.warn(`that key belongs to ${am.identity?.email || "a person"}, not the agent; continuing without one`);
+      else { agentKey = given; agentMe = am.identity; ui.ok(`agent key accepted: "${am.identity?.name || "agent"}" (role bot)`); }
+    }
+  }
+  const commandersIn = (process.env.COMMANDERS || "").trim()
+    || (isAgentIdentity(me.identity) && ui.interactive ? await ui.ask("Email(s) of the people who steer and approve the agents, comma-separated") : "");
+  const roles = agentRoles({ person: isAgentIdentity(me.identity) ? null : me.identity, agent: agentMe, commanders: commandersIn });
+  for (const w of roles.warnings) ui.warn(w);
+  out.identity = { runAs: roles.runAs, agentIds: roles.agentIds, commanders: roles.commanders };
+  // The pack reads its NOAN key from this secret name; under the agent role it holds the agent's key.
+  const runKey = roles.runAs === "agent" ? agentKey : key;
+
+  const secrets = { NOAN_PERSONAL_API_KEY: runKey, ...(anthropic && { [mName]: anthropic }), ...(resend && { RESEND_API_KEY: resend }),
+                    ...(db && { DATABASE_URL: db }), ...(firecrawl && { FIRECRAWL_API_KEY: firecrawl }) };
+  const unsub = pack.unsubSecret(fork.dest, pack.existingSecrets(fork.dest, args.dryRun), { dryRun: args.dryRun });
+  if (unsub.setOnFork) secrets[pack.UNSUB_SECRET] = unsub.value;
   for (const [n, v] of Object.entries(secrets)) { const r = pack.setSecret(fork.dest, n, v, args.dryRun); out.secrets.push(r); ui.ok(`secret ${n}: ${r.action}${r.error ? ` — ${r.error}` : ""}`); }
+  if (!unsub.setOnFork) { out.secrets.push({ name: pack.UNSUB_SECRET, action: unsub.action }); ui.ok(`secret ${pack.UNSUB_SECRET}: ${unsub.action}`); }
+  if (unsub.action === "kept, not in .env") {
+    ui.warn(`${pack.UNSUB_SECRET} is on the fork but not in ${fork.dest}/.env, so your site can't check newsletter unsubscribe links with it`);
+    report.next.push({ id: "unsub-secret", say: `Before sending a newsletter, pick a new ${pack.UNSUB_SECRET} and set it in ${fork.dest}/.env, as the fork's secret, and on your site.`, why: "the site checks unsubscribe links with the same value the agents sign them with" });
+  }
   // The endpoint is a repository VARIABLE, not a secret: without it the fork holds a gateway key
   // and still calls the default vendor, which is the same "documented is not delivered" trap the
   // pack's own workflows had.
-  const vars = { DRY_RUN: "1", STATE_BACKEND: db ? "postgres" : "local", ...(mBase && { ANTHROPIC_BASE_URL: mBase }), ...(mailFrom && { MAIL_FROM: mailFrom }), ...(replyTo && { REPLY_TO: replyTo }), ...(escalateTo && { ESCALATE_TO: escalateTo }),
+  const have = pack.existingVariables(fork.dest, args.dryRun);
+  const forkState = pack.forkStateVars(have, { db });
+  const vars = { ...forkState.set, ...(mBase && { ANTHROPIC_BASE_URL: mBase }), ...(mailFrom && { MAIL_FROM: mailFrom }), ...(replyTo && { REPLY_TO: replyTo }), ...(escalateTo && { ESCALATE_TO: escalateTo }),
                  ...identity,
-                 COMPANY_NAME: me.project?.name || "", ...(me.identity?.id && { AGENT_IDENTITY_IDS: me.identity.id }), ...(me.identity?.email && { COMMANDERS: me.identity.email }) };
+                 COMPANY_NAME: me.project?.name || "", ...(roles.agentIds && { AGENT_IDENTITY_IDS: roles.agentIds }), ...(roles.commanders && { COMMANDERS: roles.commanders }) };
   // The seeds need the key in the clone's .env; the pack's own .env.example documents the rest.
   pack.writePackEnv(fork.dest, { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { [mName]: anthropic }), ...(mBase && { ANTHROPIC_BASE_URL: mBase }), ...(resend && { RESEND_API_KEY: resend }) }, args.dryRun);
   const seeds = pack.runSeeds(fork.dest, { NOAN_PERSONAL_API_KEY: key }, { dryRun: args.dryRun });
@@ -201,8 +238,20 @@ async function setupAgents({ args, ui, dir, key, me, report, shared = {} }) {
       report.next.push({ id: "grounding", say: `Fill the ${grounding.gaps.length} block(s) the agents read (tasks are on your NOAN board): ${grounding.gaps.map(g => g.title).join(", ")}.`, why: "an agent grounded in an empty block fails quietly" });
     } else ui.ok("every block the agents read holds a fact");
   }
+  // Who gets work handed back (agent role only, see agentRoles). An env value wins; one already
+  // set on the fork is kept, since it is a list a person may have extended with teammates.
+  const handBackKept = [], handBackToYou = [];
+  for (const [n, v] of Object.entries(roles.handBack)) {
+    const given = (process.env[n] || "").trim();
+    if (given) vars[n] = given;
+    else if (have.has(n)) handBackKept.push(n);
+    else { vars[n] = v; handBackToYou.push(n); }
+  }
+  out.handBack = { toYou: handBackToYou, kept: handBackKept };
   for (const [n, v] of Object.entries(vars)) { if (!v) continue; const r = pack.setVariable(fork.dest, n, v, args.dryRun); out.variables.push(r); }
-  ui.ok(`${out.variables.length} repository variable(s) ${args.dryRun ? "to set" : "set"} (DRY_RUN=1: every agent stays in safe mode)`);
+  if (handBackToYou.length) ui.ok(`work the agents hand back goes to ${me.identity?.email || "you"} (fact review, parked tasks, support follow-ups)`);
+  if (handBackKept.length) ui.ok(`kept the fork's own ${handBackKept.join(", ")}`);
+  ui.ok(`${out.variables.length} repository variable(s) ${args.dryRun ? "to set" : "set"}${forkState.set.DRY_RUN ? " (DRY_RUN=1: every agent stays in safe mode)" : ""}${forkState.kept.length ? `; kept the fork's own ${forkState.kept.join(", ")}` : ""}`);
   // No point dispatching a run that will only fail for a missing key: say what is missing instead.
   if (!anthropic || !resend) {
     const missing = [!anthropic && mName, !resend && "RESEND_API_KEY"].filter(Boolean);

package/src/web.mjs

@@ -162,7 +162,7 @@ export function webNext(agent, { dest, deployUrl, missingModelKey = null }) {
     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.`
+      + ` Mint a NOAN key for this service alone under your NOAN agent (Settings → API → Agent API Keys) 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",
   };