@getnoan/wizard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NOAN
+
+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

@@ -0,0 +1,85 @@
+# NOAN wizard
+
+One command from nothing to a grounded agent.
+
+```bash
+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.
+Run it again any time; every write is a merge, and nothing you have is overwritten.
+
+## 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
+   `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`
+   merged into its config: Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), VS Code
+   (`.vscode/mcp.json`), Gemini CLI, Windsurf, and Codex (`~/.codex/config.toml`, which reads the
+   key from your environment by name; no secret is written into any config file). Clients that
+   sign you in themselves get the address only. Claude and ChatGPT have no file to write; the
+   report tells you what to click.
+3. **The skill.** The `noan-fact-layer` and `noan-fact-candidate-capture` skills from
+   [getnoan/skills](https://github.com/getnoan/skills) are copied into `.claude/skills/` (and
+   `~/.codex/skills/` if Codex is installed), and a short pointer is appended to `CLAUDE.md` and
+   `AGENTS.md` so an assistant knows where the key and the skill are.
+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`). Forks [getnoan/agent-pack](https://github.com/getnoan/agent-pack)
+   to your account, verifies and stores your Anthropic 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 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.
+6. **The report.** What happened, and the one thing to do next.
+
+## For a coding assistant
+
+The wizard is meant to be run by an agent mid-session, so every prompt has a flag:
+
+```bash
+NOAN_API_KEY=npak_… npx -y @getnoan/wizard@latest --yes --json
+```
+
+`--yes` takes every default and never prompts; `--json` prints the report as one object on stdout
+(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.
+
+Exit codes: 0 done, 2 the key did not work, 3 cancelled, 1 anything else.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `-y`, `--yes` | non-interactive |
+| `--json` | machine-readable report (implies `--yes`) |
+| `--api-key <key>` | the NOAN key (else `NOAN_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 |
+| `--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=1`) |
+
+## Telemetry
+
+Three counts and nothing else: runs started, completed, cancelled, with the Node version and
+platform. Never a key, never a path, never a workspace name. Off with `--no-telemetry`.
+
+## Why a wizard and not a prompt
+
+NOAN's published API description is wrong in a few places that a spec-generated client gets
+confidently wrong (fields the spec marks nullable that the API rejects, create responses that nest
+under the resource name, limits that reject rather than truncate). A short deterministic program
+that makes the right calls beats asking a model to work it out from the spec. The wizard makes the
+few calls it needs correctly and hands everything that needs judgement to your assistant.
+
+## Licence
+
+MIT.

package/bin/wizard.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../src/run.mjs";
+import { parseArgs, HELP } from "../src/args.mjs";
+import { createRequire } from "node:module";
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) { process.stdout.write(HELP); process.exit(0); }
+if (args.version) { process.stdout.write(createRequire(import.meta.url)("../package.json").version + "\n"); process.exit(0); }
+run(args).then(code => process.exit(code)).catch(e => { console.error("wizard: " + (e?.message || e)); process.exit(1); });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@getnoan/wizard",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "noan-wizard": "bin/wizard.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/getnoan/wizard.git"
+  },
+  "homepage": "https://getnoan.com/mcp",
+  "keywords": [
+    "noan",
+    "mcp",
+    "agent",
+    "skill",
+    "wizard",
+    "setup",
+    "fact-layer"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agents.mjs

@@ -0,0 +1,98 @@
+/**
+ * The agent pack on the user's own GitHub account: fork, secrets, variables, seeds, one dry run.
+ *
+ * Everything here goes through the GitHub CLI so no token is ever handled by this code. The
+ * seed scripts are the pack's own (run from the clone, output parsed); the variable names are
+ * the pack's documented ones. Safe mode stays on: the wizard never sets DRY_RUN to 0.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { writeEnv } from "./env-file.mjs";
+
+export const PACK_REPO = "getnoan/agent-pack";
+
+export function gh(args, opts = {}) {
+  const r = spawnSync("gh", args, { encoding: "utf8", ...opts });
+  return { ok: r.status === 0, out: (r.stdout || "").trim(), err: (r.stderr || "").trim(), status: r.status };
+}
+export function ghReady() {
+  const v = gh(["--version"]); if (!v.ok) return { ok: false, reason: "the GitHub CLI (gh) is not installed — https://cli.github.com" };
+  const a = gh(["auth", "status"]); if (!a.ok) return { ok: false, reason: "gh is not signed in — run: gh auth login" };
+  return { ok: true };
+}
+
+/** Parse what a seed script prints: the two .env lines per agent. */
+export function parseSeedOutput(text) {
+  const vars = {};
+  for (const m of String(text || "").matchAll(/^\s*([A-Z][A-Z0-9_]*_BLOCK_SLUG)=(\S+)\s*$/gm)) vars[m[1]] = m[2];
+  return vars;
+}
+
+/** The secrets and variables the pack documents, and which are required for which agent. */
+export const PACK_SECRETS = ["NOAN_PERSONAL_API_KEY", "RESEND_API_KEY", "ANTHROPIC_API_KEY", "DATABASE_URL", "FIRECRAWL_API_KEY", "NEWSLETTER_UNSUB_SECRET"];
+export const PACK_VARS = ["MAIL_FROM", "REPLY_TO", "ESCALATE_TO", "STATE_BACKEND", "AGENT_NAME", "COMPANY_NAME", "AGENT_IDENTITY_IDS", "COMMANDERS", "REPORT_RECIPIENT_TAG"];
+
+export async function verifyAnthropic(key) {
+  try { const r = await fetch("https://api.anthropic.com/v1/models", { headers: { "x-api-key": key, "anthropic-version": "2023-06-01" } }); return r.status === 200; } catch { return false; }
+}
+export async function verifyResend(key) {
+  try { const r = await fetch("https://api.resend.com/domains", { headers: { Authorization: `Bearer ${key}` } }); return r.status === 200; } catch { return false; }
+}
+export async function verifyFirecrawl(key) {
+  try { const r = await fetch("https://api.firecrawl.dev/v1/team/credit-usage", { headers: { Authorization: `Bearer ${key}` } }); return r.status === 200; } catch { return false; }
+}
+
+/** Fork (or reuse) and clone the pack into dir/noan-agent-pack. */
+export function forkAndClone(dir, { dryRun = false } = {}) {
+  const dest = path.join(dir, "noan-agent-pack");
+  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", PACK_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" };
+}
+
+export function repoSlug(dest) {
+  const r = gh(["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], { cwd: dest });
+  return r.ok ? r.out : null;
+}
+
+export function setSecret(dest, name, value, dryRun) {
+  if (dryRun) return { name, action: "would set" };
+  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] };
+}
+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" });
+  return { name, action: r.status === 0 ? "set" : "failed", error: r.status === 0 ? undefined : (r.stderr || "").trim().split("\n")[0] };
+}
+
+/** Run every seed script the pack ships; collect the block slugs they print. */
+export function runSeeds(dest, env, { dryRun = false } = {}) {
+  const seeds = ["seed-weekly-activity-report.mjs", "seed-fact-alignment.mjs", "seed-market-research-refresh.mjs", "seed-customer-support.mjs", "seed-deck.mjs"];
+  const slugs = {}; const rows = [];
+  for (const s of seeds) {
+    const p = path.join(dest, "agents", s);
+    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: path.join(dest, "agents"), 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 dispatchDryRun(dest, workflow, dryRun) {
+  if (dryRun) return { workflow, action: "would dispatch" };
+  const r = gh(["workflow", "run", workflow, "-f", "dry_run=1"], { cwd: dest });
+  return { workflow, action: r.ok ? "dispatched" : "failed", error: r.ok ? undefined : r.err.split("\n")[0] };
+}
+
+export const randomSecret = () => randomBytes(24).toString("hex");
+
+/** 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

@@ -0,0 +1,59 @@
+/** Flags. A coding assistant runs this too, so every prompt has a flag that answers it. */
+export const HELP = `noan-wizard — one command from nothing to a grounded agent
+
+  npx -y @getnoan/wizard@latest [options]
+
+What it does, in order:
+  1. Auth      takes your NOAN API key (or reads NOAN_API_KEY), checks it with GET /me,
+               writes it to .env and makes sure .env is gitignored
+  2. Clients   finds your coding assistants and points each at the NOAN MCP server
+  3. Skill     installs the NOAN skill and leaves a pointer in CLAUDE.md / AGENTS.md
+  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
+
+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)
+  --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)
+  --agents             also set up the agent pack (default: ask; with --yes: skip unless given)
+  --no-mcp             skip the client wiring
+  --no-skill           skip the skill install
+  --dry-run            show every write without making it
+  --no-telemetry       send nothing about this run (also: NOAN_WIZARD_NO_TELEMETRY=1)
+  -h, --help           this text
+  -v, --version        the version
+
+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,
+              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];
+    const next = () => { const v = argv[++i]; if (v === undefined) throw new Error(`${t} needs a value`); return v; };
+    if (t === "-y" || t === "--yes") a.yes = true;
+    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 === "--global") a.global = true;
+    else if (t === "--dir") a.dir = next();
+    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 === "--no-mcp") a.mcp = false;
+    else if (t === "--no-skill") a.skill = false;
+    else if (t === "--dry-run") a.dryRun = true;
+    else if (t === "--no-telemetry") a.telemetry = false;
+    else if (t === "-h" || t === "--help") a.help = true;
+    else if (t === "-v" || t === "--version") a.version = true;
+    else a.unknown.push(t);
+  }
+  if (a.unknown.length) throw new Error(`unknown option: ${a.unknown.join(" ")}\n\n${HELP}`);
+  return a;
+}

package/src/clients.mjs

@@ -0,0 +1,119 @@
+/**
+ * Coding-assistant clients: detect what is installed and point each at the NOAN MCP server.
+ *
+ * Every write is an idempotent merge: an existing `noan` entry is updated in place, other
+ * servers are untouched, unknown files are created. OAuth-capable clients get the URL only —
+ * they sign the user in themselves. Codex reads the key from the environment by name, so no
+ * secret is ever written into a config file. Claude Desktop and ChatGPT have no config file to
+ * write; they get instructions in the report.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { MCP_URL } from "./noan.mjs";
+
+export function readJson(p) { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } }
+function writeJson(p, obj, dryRun) { if (dryRun) return; mkdirSync(path.dirname(p), { recursive: true }); writeFileSync(p, JSON.stringify(obj, null, 2) + "\n"); }
+
+/** Merge a `noan` server entry into a JSON config at `container` (e.g. "mcpServers"). */
+export function mergeJsonServer(existing, container, entry) {
+  const obj = existing && typeof existing === "object" ? existing : {};
+  const servers = obj[container] && typeof obj[container] === "object" ? obj[container] : {};
+  const before = JSON.stringify(servers.noan ?? null);
+  servers.noan = { ...(servers.noan || {}), ...entry };
+  obj[container] = servers;
+  return { obj, action: before === "null" ? "added" : before === JSON.stringify(servers.noan) ? "unchanged" : "updated" };
+}
+
+/** Codex's config is TOML; add or replace the [mcp_servers.noan] table without touching the rest. */
+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");
+  if (rx.test(src)) {
+    const cur = src.match(rx)[0];
+    if (cur.trim() === block.trim()) return { text: src, action: "unchanged" };
+    return { text: src.replace(rx, block), action: "updated" };
+  }
+  return { text: (src && !src.endsWith("\n") ? src + "\n" : src) + (src ? "\n" : "") + block, action: "added" };
+}
+
+const HOME = os.homedir();
+const onPath = (cmd) => (process.env.PATH || "").split(path.delimiter).some(d => d && existsSync(path.join(d, cmd)));
+
+/** The clients, with how to detect them and where their config lives at each scope. */
+export function clientCatalog({ dir, home = HOME }) {
+  return [
+    {
+      id: "claude-code", label: "Claude Code",
+      detect: () => existsSync(path.join(home, ".claude.json")) || existsSync(path.join(home, ".claude")) || onPath("claude"),
+      project: { file: path.join(dir, ".mcp.json"), kind: "json", container: "mcpServers", entry: { type: "http", url: MCP_URL } },
+      global:  { file: path.join(home, ".claude.json"), kind: "json", container: "mcpServers", entry: { type: "http", url: MCP_URL } },
+      after: "In a session, type /mcp and pick NOAN to sign in.",
+    },
+    {
+      id: "cursor", label: "Cursor",
+      detect: () => existsSync(path.join(home, ".cursor")),
+      project: { file: path.join(dir, ".cursor", "mcp.json"), kind: "json", container: "mcpServers", entry: { url: MCP_URL } },
+      global:  { file: path.join(home, ".cursor", "mcp.json"), kind: "json", container: "mcpServers", entry: { url: MCP_URL } },
+      after: "Cursor asks you to sign in to NOAN once.",
+    },
+    {
+      id: "codex", label: "OpenAI Codex",
+      detect: () => existsSync(path.join(home, ".codex")) || onPath("codex"),
+      project: null,   // Codex config is user-level only
+      global:  { file: path.join(home, ".codex", "config.toml"), kind: "toml", table: "mcp_servers.noan",
+                 lines: [`url = "${MCP_URL}"`, `bearer_token_env_var = "NOAN_API_KEY"`] },
+      after: "Codex sends NOAN_API_KEY from your environment as the bearer token.",
+    },
+    {
+      id: "vscode", label: "VS Code",
+      detect: () => existsSync(path.join(dir, ".vscode")) || onPath("code"),
+      project: { file: path.join(dir, ".vscode", "mcp.json"), kind: "json", container: "servers", entry: { type: "http", url: MCP_URL } },
+      global:  null,   // user-level MCP in VS Code lives in the profile UI, not a file we should edit
+      after: "Open the MCP view and start the NOAN server; VS Code signs you in.",
+    },
+    {
+      id: "windsurf", label: "Windsurf",
+      detect: () => existsSync(path.join(home, ".codeium", "windsurf")),
+      project: null,
+      global:  { file: path.join(home, ".codeium", "windsurf", "mcp_config.json"), kind: "json", container: "mcpServers", entry: { serverUrl: MCP_URL } },
+      after: "Refresh the MCP list in Windsurf.",
+    },
+    {
+      id: "gemini", label: "Gemini CLI",
+      detect: () => existsSync(path.join(home, ".gemini")),
+      project: { file: path.join(dir, ".gemini", "settings.json"), kind: "json", container: "mcpServers", entry: { httpUrl: MCP_URL } },
+      global:  { file: path.join(home, ".gemini", "settings.json"), kind: "json", container: "mcpServers", entry: { httpUrl: MCP_URL } },
+      after: "Run /mcp in Gemini CLI to check the server is up.",
+    },
+  ];
+}
+
+/** Clients with no file to write — the report tells the user what to click. */
+export const MANUAL_CLIENTS = [
+  { id: "claude-desktop", label: "Claude (desktop and web)", how: `Settings → Connectors → Add custom connector → name it NOAN, address ${MCP_URL}, then Connect and sign in.` },
+  { id: "chatgpt", label: "ChatGPT", how: `Settings → Connectors (developer mode on) → Create → name it NOAN, address ${MCP_URL}, sign in with your NOAN account, then enable it in a chat.` },
+];
+
+/** Wire every detected client at the chosen scope. Returns one row per client. */
+export function wireClients({ dir, global = false, dryRun = false, home = HOME, force = [] }) {
+  const rows = [];
+  for (const c of clientCatalog({ dir, home })) {
+    const detected = c.detect() || force.includes(c.id);
+    const target = global ? (c.global || c.project) : (c.project || c.global);
+    if (!detected) { rows.push({ id: c.id, label: c.label, detected: false }); continue; }
+    if (!target) { rows.push({ id: c.id, label: c.label, detected: true, action: "no config file for this scope" }); continue; }
+    let action;
+    if (target.kind === "json") {
+      const { obj, action: a } = mergeJsonServer(readJson(target.file), target.container, target.entry);
+      action = a; if (a !== "unchanged") writeJson(target.file, obj, dryRun);
+    } else {
+      const cur = existsSync(target.file) ? readFileSync(target.file, "utf8") : "";
+      const { text, action: a } = mergeToml(cur, target.table, target.lines);
+      action = a; if (a !== "unchanged" && !dryRun) { mkdirSync(path.dirname(target.file), { recursive: true }); writeFileSync(target.file, text); }
+    }
+    rows.push({ id: c.id, label: c.label, detected: true, file: target.file, scope: target === c.global ? "user" : "project", action, after: c.after });
+  }
+  return rows;
+}

package/src/env-file.mjs

@@ -0,0 +1,36 @@
+/** .env handling: set keys without disturbing the rest, keep the file private, keep it out of git. */
+import { readFileSync, writeFileSync, existsSync, chmodSync, appendFileSync } from "node:fs";
+import path from "node:path";
+
+/** Returns the new file text with `pairs` set (replacing existing lines for those keys). */
+export function upsertEnv(text, pairs) {
+  const lines = (text || "").split("\n");
+  const done = new Set();
+  const out = lines.map(l => {
+    const m = l.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/);
+    if (m && m[1] in pairs) { done.add(m[1]); return `${m[1]}=${pairs[m[1]]}`; }
+    return l;
+  });
+  while (out.length && out[out.length - 1] === "") out.pop();
+  for (const [k, v] of Object.entries(pairs)) if (!done.has(k)) out.push(`${k}=${v}`);
+  return out.join("\n") + "\n";
+}
+
+export function writeEnv(dir, pairs, { dryRun = false } = {}) {
+  const p = path.join(dir, ".env");
+  const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+  const after = upsertEnv(before, pairs);
+  if (!dryRun) { writeFileSync(p, after); try { chmodSync(p, 0o600); } catch {} }
+  return { path: p, created: !before, changed: before !== after };
+}
+
+/** .gitignore must cover .env; add the line if the directory is a git checkout (or already has a .gitignore). */
+export function ensureGitignored(dir, { dryRun = false } = {}) {
+  const gi = path.join(dir, ".gitignore");
+  const isRepo = existsSync(path.join(dir, ".git"));
+  if (!isRepo && !existsSync(gi)) return { path: gi, action: "not a git repo" };
+  const text = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (text.split("\n").some(l => /^\s*\.env(\s*$|\s+#)/.test(l) || l.trim() === ".env*" || l.trim() === "*.env")) return { path: gi, action: "already ignored" };
+  if (!dryRun) appendFileSync(gi, (text && !text.endsWith("\n") ? "\n" : "") + ".env\n");
+  return { path: gi, action: "added .env" };
+}

package/src/noan.mjs

@@ -0,0 +1,34 @@
+/** The few NOAN calls the wizard makes. Plain fetch; the key travels only in the header. */
+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";
+
+export function looksLikeKey(k) { return typeof k === "string" && /^npak_[A-Za-z0-9_-]{16,}$/.test(k.trim()); }
+
+async function get(path, key) {
+  const r = await fetch(API + path, { headers: { Authorization: `Bearer ${key}` } });
+  let body = null; try { body = await r.json(); } catch {}
+  return { status: r.status, body };
+}
+
+/** GET /me: who the key is, and which workspace. */
+export async function whoAmI(key) {
+  const { status, body } = await get("/me", key);
+  if (status === 401 || status === 403) return { ok: false, reason: "the key was not accepted" };
+  if (status !== 200 || !body?.project) return { ok: false, reason: `unexpected answer from NOAN (${status})` };
+  return { ok: true, project: body.project, identity: body.identity };
+}
+
+/** 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);
+  if (status !== 200) return null;
+  return body?.meta?.totalItems ?? (Array.isArray(body?.items) ? body.items.length : null);
+}
+
+export const EMPTY_THRESHOLD = 10;
+export function classifyWorkspace(count) {
+  if (count == null) return { state: "unknown", empty: false };
+  return { state: count < EMPTY_THRESHOLD ? "empty" : "populated", empty: count < EMPTY_THRESHOLD, count };
+}

package/src/report.mjs

@@ -0,0 +1,21 @@
+/** The last thing the wizard prints: what it did and what to do next. Text for people, JSON for agents. */
+import { MCP_URL, APP_URL } from "./noan.mjs";
+
+export function renderReport(report, { json = false } = {}) {
+  if (json) return JSON.stringify(report, null, 2) + "\n";
+  const s = report.steps; const L = [];
+  L.push("", "──────── what happened ────────");
+  if (s.auth?.ok) L.push(`key: ${s.auth.email} · workspace "${s.auth.workspace}" · .env ${s.auth.envAction} · .gitignore ${s.auth.gitignore}`);
+  else L.push(`key: not accepted${s.auth?.reason ? ` (${s.auth.reason})` : ""}`);
+  if (s.clients?.rows) {
+    const wired = s.clients.rows.filter(r => r.detected);
+    L.push(wired.length ? `clients: ${wired.map(r => `${r.label} ${r.action}`).join(" · ")}` : `clients: none found (MCP address ${MCP_URL})`);
+    for (const r of wired) if (r.after) L.push(`  ${r.label}: ${r.after}`);
+  }
+  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.secrets.length} secrets, ${s.agents.variables.length} variables, safe mode on` : `agents: not set up (${s.agents.reason})`);
+  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

@@ -0,0 +1,149 @@
+/** The wizard, step by step. Each step reports a row; the report at the end is built from the rows. */
+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 { 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 { capture } from "./telemetry.mjs";
+import { renderReport } from "./report.mjs";
+
+export async function run(args) {
+  const ui = makeUI(args);
+  const dir = path.resolve(args.dir);
+  const report = { version: 1, dir, dryRun: args.dryRun, steps: {}, next: [] };
+  const t0 = Date.now();
+  await capture(args, "started");
+  const finish = async (code, event = code === 0 ? "completed" : "cancelled") => {
+    await capture(args, event, { exit: code, ms: Date.now() - t0, empty: report.steps.workspace?.empty });
+    report.exit = code;
+    process.stdout.write(renderReport(report, { json: args.json }));
+    return code;
+  };
+  if (!existsSync(dir)) { ui.warn(`no such directory: ${dir}`); return finish(1, "cancelled"); }
+  ui.say(`NOAN wizard${args.dryRun ? " (dry run: nothing is written)" : ""} — ${dir}`);
+
+  /* 1. auth */
+  ui.step(1, "Your NOAN key");
+  let key = (args.apiKey || process.env.NOAN_API_KEY || process.env.NOAN_PERSONAL_API_KEY || "").trim();
+  if (key) ui.info("using the key from " + (args.apiKey ? "--api-key" : "the environment"));
+  if (!key) {
+    if (!ui.interactive) { ui.warn("no key: set NOAN_API_KEY or pass --api-key"); report.steps.auth = { ok: false, reason: "no key" }; return finish(2, "cancelled"); }
+    ui.info(`Create one at ${KEY_PAGE_HINT} (opening ${APP_URL} is up to you), then paste it here. It is not echoed.`);
+    key = await ask(ui, "NOAN API key", { secret: true, required: true });
+  }
+  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 || "?"}"`);
+  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}`);
+  report.steps.auth = { ok: true, email: me.identity?.email, workspace: me.project?.name, env: env.path, envAction: env.created ? "created" : env.changed ? "updated" : "unchanged", gitignore: gi.action };
+
+  /* 2. clients */
+  ui.step(2, "Your coding assistants");
+  if (args.mcp) {
+    const rows = wireClients({ dir, global: args.global, dryRun: args.dryRun });
+    for (const r of rows) {
+      if (!r.detected) continue;
+      ui.ok(`${r.label}: ${r.action}${r.file ? ` (${r.scope} scope, ${r.file})` : ""}`);
+    }
+    if (!rows.some(r => r.detected)) ui.info("no coding assistant found on this machine; the MCP address is " + MCP_URL);
+    report.steps.clients = { rows, manual: MANUAL_CLIENTS };
+    for (const m of MANUAL_CLIENTS) ui.info(`${m.label}: ${m.how}`);
+  } else { ui.info("skipped (--no-mcp)"); report.steps.clients = { skipped: true }; }
+
+  /* 3. skill */
+  ui.step(3, "The NOAN skill");
+  if (args.skill) {
+    try {
+      const { files, missing } = await fetchSkillFiles();
+      const rows = installSkill(files, skillTargets({ dir, global: args.global }), { dryRun: args.dryRun });
+      for (const m of missing) ui.info(`${m} is not published yet; skipped`);
+      for (const r of rows) ui.ok(`${r.id}: ${r.written} file(s) ${args.dryRun ? "to write" : "written"}, ${r.unchanged} unchanged → ${r.root}`);
+      const pointers = writePointers(dir, { dryRun: args.dryRun });
+      for (const p of pointers) ui.ok(`${path.basename(p.file)}: ${p.action}`);
+      report.steps.skill = { rows, pointers, missing };
+    } catch (e) { ui.warn(`skill install failed: ${e.message}`); report.steps.skill = { error: e.message }; }
+  } else { ui.info("skipped (--no-skill)"); report.steps.skill = { skipped: true }; }
+
+  /* 4. workspace */
+  ui.step(4, "Your fact layer");
+  const count = await factCount(key);
+  const ws = classifyWorkspace(count);
+  report.steps.workspace = ws;
+  if (ws.state === "empty") {
+    ui.warn(`${count} fact(s): the workspace is empty or nearly so. The wizard does not guess facts.`);
+    ui.info("Ask your assistant to set up the workspace: it has the first-connect procedure from the skill and will propose a structure from your website, repo or docs before writing anything.");
+    report.next.push({ id: "first-connect", say: "Set up my NOAN workspace from our website and this repo. Propose the structure first and wait for my yes before writing.", why: "the fact layer is empty" });
+  } else if (ws.state === "populated") ui.ok(`${count} facts in the workspace`);
+  else ui.warn("could not count the facts (the key may be read-scoped to a subset); carrying on");
+
+  /* 5. agents */
+  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 });
+  else { ui.info("skipped" + (args.yes && args.agents == null ? " (pass --agents to include it)" : "")); report.steps.agents = { skipped: true }; }
+
+  /* 6. 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 }) {
+  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 });
+  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, secrets: [], variables: [], seeds: [], skipped: [] };
+
+  // Keys: from the environment (an agent's run) or a prompt (a person's). Verified before they are stored.
+  const need = async (name, verify, prompt, { optional = false } = {}) => {
+    let v = (process.env[name] || "").trim();
+    if (!v && ui.interactive) v = await ui.ask(prompt, { secret: true });
+    if (!v) { out.skipped.push({ name, why: optional ? "not provided" : "required, not provided" }); return null; }
+    if (verify && !(await verify(v))) { ui.warn(`${name} was not accepted by its service; not stored`); out.skipped.push({ name, why: "rejected" }); return null; }
+    return v;
+  };
+  const anthropic = await need("ANTHROPIC_API_KEY", pack.verifyAnthropic, "Anthropic API key (the agents' model)");
+  const resend = await need("RESEND_API_KEY", pack.verifyResend, "Resend API key (the agents' email)");
+  const db = await need("DATABASE_URL", null, "Postgres URL for the agents' state ledger (blank to skip; then only market research runs)", { optional: true });
+  const firecrawl = await need("FIRECRAWL_API_KEY", pack.verifyFirecrawl, "Firecrawl API key (market research; blank to skip)", { optional: true });
+  const mailFrom = process.env.MAIL_FROM || (ui.interactive ? await ui.ask("Sender for the agents' mail, e.g. Agent <agent@yourdomain.com> (a domain verified in Resend)") : "");
+  const replyTo = process.env.REPLY_TO || (ui.interactive ? await ui.ask("Reply-to address (a mailbox someone reads)", { dflt: mailFrom.replace(/^.*<|>.*$/g, "") }) : "");
+  const escalateTo = process.env.ESCALATE_TO || (ui.interactive ? await ui.ask("Where the support agent escalates when it cannot answer") : "");
+
+  const secrets = { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { ANTHROPIC_API_KEY: anthropic }), ...(resend && { RESEND_API_KEY: resend }),
+                    ...(db && { DATABASE_URL: db }), ...(firecrawl && { FIRECRAWL_API_KEY: firecrawl }), NEWSLETTER_UNSUB_SECRET: pack.randomSecret() };
+  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}` : ""}`); }
+  const vars = { DRY_RUN: "1", STATE_BACKEND: db ? "postgres" : "local", ...(mailFrom && { MAIL_FROM: mailFrom }), ...(replyTo && { REPLY_TO: replyTo }), ...(escalateTo && { ESCALATE_TO: escalateTo }),
+                 COMPANY_NAME: me.project?.name || "", ...(me.identity?.id && { AGENT_IDENTITY_IDS: me.identity.id }), ...(me.identity?.email && { COMMANDERS: me.identity.email }) };
+  // 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 && { ANTHROPIC_API_KEY: anthropic }), ...(resend && { RESEND_API_KEY: resend }) }, args.dryRun);
+  const seeds = pack.runSeeds(fork.dest, { NOAN_PERSONAL_API_KEY: key }, { dryRun: args.dryRun });
+  out.seeds = seeds.rows;
+  for (const r of seeds.rows) ui.ok(`${r.seed}: ${r.action}${r.slugs != null ? ` (${r.slugs} slug(s))` : ""}${r.error ? ` — ${r.error}` : ""}`);
+  Object.assign(vars, seeds.slugs);
+  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)`);
+  // No point dispatching a run that will only fail for a missing key: say what is missing instead.
+  if (!anthropic || !resend) {
+    const missing = [!anthropic && "ANTHROPIC_API_KEY", !resend && "RESEND_API_KEY"].filter(Boolean);
+    out.incomplete = missing;
+    ui.warn(`not dispatching a run: ${missing.join(" and ")} still missing. Add them as repository secrets (or re-run with them in the environment), then run any agent workflow with dry_run=1.`);
+  } else {
+    const wf = firecrawl ? "market-research-refresh.yml" : "weekly-activity-report.yml";
+    const d = pack.dispatchDryRun(fork.dest, wf, args.dryRun);
+    out.dryRunDispatch = d;
+    ui.ok(`${wf}: ${d.action}${d.error ? ` — ${d.error}` : ""} — read it under Actions, then set DRY_RUN=0 for the agents you trust`);
+  }
+  out.repo = pack.repoSlug(fork.dest);
+  return out;
+}

package/src/skill.mjs

@@ -0,0 +1,80 @@
+/**
+ * The NOAN skill: fetched from the public repo and placed where each assistant reads skills.
+ * Files are copied, not symlinked, so the install survives a moved checkout; re-running
+ * overwrites with the current published version.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export const SKILLS_REPO = "getnoan/skills";
+const RAW = `https://raw.githubusercontent.com/${SKILLS_REPO}/main/skills`;
+export const SKILL_FILES = [
+  "noan-fact-layer/SKILL.md",
+  "noan-fact-layer/references/first-connect.md",
+  "noan-fact-layer/references/interview.md",
+  "noan-fact-layer/references/writing-facts.md",
+];
+/** Published later than the core skill; installed when present, skipped with a note when not. */
+export const OPTIONAL_SKILL_FILES = ["noan-fact-candidate-capture/SKILL.md"];
+
+export async function fetchSkillFiles(fetchImpl = fetch) {
+  const out = {}; const missing = [];
+  for (const f of [...SKILL_FILES, ...OPTIONAL_SKILL_FILES]) {
+    const r = await fetchImpl(`${RAW}/${f}`);
+    if (!r.ok) {
+      if (OPTIONAL_SKILL_FILES.includes(f) && r.status === 404) { missing.push(f); continue; }
+      throw new Error(`could not fetch ${f} from ${SKILLS_REPO} (${r.status})`);
+    }
+    out[f] = await r.text();
+  }
+  return { files: out, missing };
+}
+
+/** Where skills go: Claude Code reads .claude/skills (project) or ~/.claude/skills (user); Codex reads ~/.codex/skills. */
+export function skillTargets({ dir, global = false, home = os.homedir() }) {
+  const t = [{ id: "claude-code", root: global ? path.join(home, ".claude", "skills") : path.join(dir, ".claude", "skills") }];
+  if (existsSync(path.join(home, ".codex"))) t.push({ id: "codex", root: path.join(home, ".codex", "skills") });
+  return t;
+}
+
+export function installSkill(files, targets, { dryRun = false } = {}) {
+  const rows = [];
+  for (const t of targets) {
+    let written = 0, unchanged = 0;
+    for (const [rel, text] of Object.entries(files)) {
+      const p = path.join(t.root, rel);
+      const cur = existsSync(p) ? readFileSync(p, "utf8") : null;
+      if (cur === text) { unchanged++; continue; }
+      if (!dryRun) { mkdirSync(path.dirname(p), { recursive: true }); writeFileSync(p, text); }
+      written++;
+    }
+    rows.push({ id: t.id, root: t.root, written, unchanged });
+  }
+  return rows;
+}
+
+export const POINTER_MARK = "<!-- noan-wizard -->";
+export function pointerText() {
+  return `${POINTER_MARK}
+## NOAN
+
+This project is grounded in the NOAN fact layer. The key is \`NOAN_API_KEY\` in \`.env\`; the MCP server is
+configured for this assistant; the \`noan-fact-layer\` skill (installed under the skills folder) says how to read
+and write facts. Read facts before answering questions about the business. If the workspace is empty, follow the
+skill's first-connect procedure to seed it, and confirm the plan with the user before writing.
+`;
+}
+
+/** Append the pointer to CLAUDE.md and AGENTS.md (creating them if absent); idempotent on the marker. */
+export function writePointers(dir, { dryRun = false } = {}) {
+  const rows = [];
+  for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+    const p = path.join(dir, name);
+    const cur = existsSync(p) ? readFileSync(p, "utf8") : "";
+    if (cur.includes(POINTER_MARK)) { rows.push({ file: p, action: "already present" }); continue; }
+    if (!dryRun) appendFileSync(p, (cur && !cur.endsWith("\n") ? "\n" : "") + (cur ? "\n" : "") + pointerText());
+    rows.push({ file: p, action: cur ? "appended" : "created" });
+  }
+  return rows;
+}

package/src/telemetry.mjs

@@ -0,0 +1,17 @@
+/** Runs, completions and cancels — the three counts that say whether the wizard works for strangers.
+ *  Off until a public project token is set here; off whenever the user says so. Never a key, never a path. */
+export const POSTHOG_TOKEN = "";   // public (write-only) PostHog project token; empty = telemetry off
+const HOST = "https://us.i.posthog.com";
+
+export function telemetryEnabled(args) {
+  return !!POSTHOG_TOKEN && args.telemetry !== false && process.env.NOAN_WIZARD_NO_TELEMETRY !== "1";
+}
+export async function capture(args, event, props = {}) {
+  if (!telemetryEnabled(args)) return false;
+  try {
+    await fetch(`${HOST}/capture/`, { method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_key: POSTHOG_TOKEN, event: `wizard_${event}`, distinct_id: "anonymous",
+        properties: { $process_person_profile: false, node: process.version, platform: process.platform, yes: !!args.yes, json: !!args.json, ...props } }) });
+    return true;
+  } catch { return false; }
+}

package/src/ui.mjs

@@ -0,0 +1,35 @@
+/** Prompts. Every one has a non-interactive answer so an agent can run the wizard with --yes. */
+import readline from "node:readline";
+
+export function makeUI({ yes = false, json = false } = {}) {
+  const out = json ? () => {} : (s = "") => process.stderr.write(s + "\n");   // --json keeps stdout for the report
+  const say = out;
+  const step = (n, title) => out(`\n${n}. ${title}`);
+  const ok = (s) => out(`   ✓ ${s}`);
+  const warn = (s) => out(`   ! ${s}`);
+  const info = (s) => out(`   ${s}`);
+
+  async function ask(question, { dflt = "", secret = false, required = false } = {}) {
+    if (yes) return dflt;
+    if (!process.stdin.isTTY) return dflt;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    const label = dflt && !secret ? `${question} [${dflt}]: ` : `${question}: `;
+    if (secret) {
+      // Mute the echo: the key never appears on screen, in a scrollback, or in a recording.
+      rl._writeToOutput = function (s) { if (s.includes(label)) rl.output.write(label); };
+    }
+    const answer = await new Promise(res => rl.question(label, res));
+    rl.close();
+    if (secret) process.stderr.write("\n");
+    const v = String(answer || "").trim() || dflt;
+    if (required && !v) return ask(question, { dflt, secret, required });
+    return v;
+  }
+  async function confirm(question, dflt = true) {
+    if (yes || !process.stdin.isTTY) return dflt;
+    const v = (await ask(`${question} (${dflt ? "Y/n" : "y/N"})`)).toLowerCase();
+    if (!v) return dflt;
+    return v.startsWith("y");
+  }
+  return { say, step, ok, warn, info, ask, confirm, interactive: !yes && !!process.stdin.isTTY };
+}