toolroll 0.5.0

package/dist/keys.js

@@ -0,0 +1,229 @@
+/**
+ * Provider API keys, managed instead of ambient (the gap the gemini
+ * live-auth work exposed): one 0600 file per provider under
+ * ~/.toolroll/keys/ (or an older ~/.standing-orders/keys/), written from the settings card or piped into
+ * the CLI — never typed into an argv, never rendered back, never stored
+ * in the database a backup might carry.
+ *
+ * The injection contract lives in the invocation gateway: a stored key is
+ * added to EXACTLY its own provider's child environment at spawn, where
+ * the adapter's foreign-credential strip has already shed everybody
+ * else's. The plane's own process never needs the key in its environment
+ * at all — a restart or a rotation is a file write, not a relaunch — and
+ * an ambient env var still works as the fallback it always was (the file,
+ * being deliberate, wins).
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { namedPath } from "./names.js";
+/** The ONE env name each provider's own harness reads its key from —
+ * where a managed key is INJECTED. */
+export const PROVIDER_KEY_ENV = {
+    claude: "ANTHROPIC_API_KEY",
+    codex: "OPENAI_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
+    gemini: "GEMINI_API_KEY",
+};
+/** EVERY env name a provider reads its OWN key from — what subscription
+ * mode STRIPS so an ambient key cannot override the login. gemini reads
+ * two; the rest read one. */
+export const OWN_KEY_ENV = {
+    // v105: the bearer-token and Codex-specific aliases bill a key just the same, so a sign-in run sheds them too.
+    claude: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+    codex: ["OPENAI_API_KEY", "CODEX_API_KEY"],
+    openrouter: ["OPENROUTER_API_KEY"],
+    gemini: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+};
+export function keysDir(home = homedir()) {
+    return namedPath(home, ["keys"], { dot: true });
+}
+/** Providers that CAN authenticate without an API key (a subscription or
+ * cached login). openrouter cannot — it is api-key only. */
+export const SUBSCRIPTION_CAPABLE = {
+    claude: true,
+    codex: true,
+    gemini: true,
+    openrouter: false,
+};
+/** The default when nothing is set: subscription where it exists (prefer
+ * the plan the operator already pays for), api-key otherwise. */
+export const DEFAULT_AUTH_MODE = {
+    // Claude and Codex have first-class subscriptions most operators
+    // already pay for — prefer them. Gemini support here is key-based (a
+    // Google cached login is possible but not our road), and openrouter is
+    // key-only — both default to the key. Every default is switchable.
+    claude: "subscription",
+    codex: "subscription",
+    gemini: "api-key",
+    openrouter: "api-key",
+};
+function authModeFileFor(provider, home) {
+    return join(keysDir(home), `${provider}.auth`);
+}
+export function readAuthMode(provider, home = homedir()) {
+    if (!SUBSCRIPTION_CAPABLE[provider])
+        return "api-key";
+    try {
+        const value = readFileSync(authModeFileFor(provider, home), "utf8").trim();
+        return value === "api-key" ? "api-key" : "subscription";
+    }
+    catch {
+        return DEFAULT_AUTH_MODE[provider];
+    }
+}
+/**
+ * The auth mode as an AUTHORITY reads it (raw authority repair): an absent
+ * file is the provider's default, but a file that is present and says
+ * neither `subscription` nor `api-key` is a stated problem — never the
+ * subscription default a lenient read would coerce it to. A provider with
+ * no subscription login is the key, whatever the file says.
+ */
+export function readAuthModeStrict(provider, home = homedir()) {
+    if (!SUBSCRIPTION_CAPABLE[provider])
+        return { ok: true, mode: "api-key" };
+    let raw;
+    try {
+        raw = readFileSync(authModeFileFor(provider, home), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ok: true, mode: DEFAULT_AUTH_MODE[provider] };
+        return { ok: false, problem: `the ${provider} auth-mode file cannot be read (${error.code ?? "error"}) — run \`keys auth ${provider} subscription|api-key\` to restate it` };
+    }
+    const value = raw.trim();
+    if (value !== "subscription" && value !== "api-key") {
+        return { ok: false, problem: `the ${provider} auth-mode file says ${JSON.stringify(value.slice(0, 40))}, not subscription or api-key — run \`keys auth ${provider} subscription|api-key\` to restate it` };
+    }
+    return { ok: true, mode: value };
+}
+export function setAuthMode(provider, mode, home = homedir()) {
+    if (mode === "subscription" && !SUBSCRIPTION_CAPABLE[provider]) {
+        return { ok: false, reason: "no-subscription" };
+    }
+    mkdirSync(keysDir(home), { recursive: true, mode: 0o700 });
+    writeFileSync(authModeFileFor(provider, home), mode, { mode: 0o600 });
+    return { ok: true };
+}
+export function keyFileFor(provider, home = homedir()) {
+    return join(keysDir(home), provider);
+}
+/** Shape check only — never a validity claim. A key is printable ASCII
+ * without whitespace, bounded; anything else is a paste accident. */
+export function plausibleKey(value) {
+    return value.length >= 8 && value.length <= 512 && /^[\x21-\x7e]+$/.test(value);
+}
+export function saveProviderKey(provider, value, home = homedir()) {
+    const trimmed = value.trim();
+    if (!plausibleKey(trimmed))
+        return { ok: false, reason: "implausible" };
+    mkdirSync(keysDir(home), { recursive: true, mode: 0o700 });
+    writeFileSync(keyFileFor(provider, home), trimmed, { mode: 0o600 });
+    // An existing file keeps its old mode through writeFileSync — restate it.
+    chmodSync(keyFileFor(provider, home), 0o600);
+    return { ok: true };
+}
+export function readProviderKey(provider, home = homedir()) {
+    try {
+        const value = readFileSync(keyFileFor(provider, home), "utf8").trim();
+        return plausibleKey(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearProviderKey(provider, home = homedir()) {
+    const file = keyFileFor(provider, home);
+    if (!existsSync(file))
+        return false;
+    rmSync(file, { force: true });
+    return true;
+}
+const VERIFY_ENDPOINT = {
+    gemini: {
+        // The key rides the x-goog-api-key HEADER (round 2, finding 6):
+        // Google's current guidance, and it keeps the secret out of the URL
+        // where a diagnostic or intermediary could surface it.
+        url: "https://generativelanguage.googleapis.com/v1beta/models",
+        headers: key => ({ "x-goog-api-key": key }),
+    },
+    codex: {
+        url: "https://api.openai.com/v1/models",
+        headers: key => ({ authorization: `Bearer ${key}` }),
+    },
+    openrouter: {
+        url: "https://openrouter.ai/api/v1/key",
+        headers: key => ({ authorization: `Bearer ${key}` }),
+    },
+    claude: {
+        url: "https://api.anthropic.com/v1/models",
+        headers: key => ({ "x-api-key": key, "anthropic-version": "2023-06-01" }),
+    },
+};
+export async function verifyProviderKey(provider, value, fetcher = fetch, timeoutMs = 10_000) {
+    const key = value.trim();
+    if (!plausibleKey(key))
+        return { ok: false, reason: "rejected", status: 0 };
+    const endpoint = VERIFY_ENDPOINT[provider];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetcher(endpoint.url, { headers: endpoint.headers(key), redirect: "error", signal: controller.signal });
+    }
+    catch {
+        return { ok: false, reason: "unreachable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.status === 200)
+        return { ok: true };
+    // 401/403 are the auth boundary saying no, on every provider (round 2,
+    // finding 6). A 400 is AMBIGUOUS — malformed request vs a bad key — so
+    // it is a rejection ONLY when the body names a key/auth failure; our
+    // request is a trivial GET, so a 400 that is NOT about the key is a
+    // genuine surprise and reads as `unexpected`, not a false rejection.
+    if (response.status === 401 || response.status === 403) {
+        return { ok: false, reason: "rejected", status: response.status };
+    }
+    if (response.status === 400) {
+        let body = "";
+        try {
+            body = (await response.text()).slice(0, 2048).toLowerCase();
+        }
+        catch {
+            body = "";
+        }
+        // A 400 is a rejection ONLY with an actual NEGATIVE marker near the
+        // key/auth phrase (round 3, finding 6) — "API key not valid" rejects,
+        // but "API key accepted; malformed page size" does not.
+        const negativeAuth = /(api[ _]?key[^.]{0,30}(invalid|not valid|expired|missing|revoked))|((invalid|expired|missing|revoked)[^.]{0,20}api[ _]?key)|unauthenticated|permission[ _]denied|invalid authentication|api_key_invalid/;
+        if (negativeAuth.test(body)) {
+            return { ok: false, reason: "rejected", status: 400 };
+        }
+        return { ok: false, reason: "unexpected", status: 400 };
+    }
+    return { ok: false, reason: "unexpected", status: response.status };
+}
+/** Words for a verdict, safe to render on any surface (never the key). */
+export function verdictWords(provider, verdict) {
+    if (verdict.ok)
+        return `the ${provider} key works`;
+    if (verdict.reason === "rejected")
+        return `${provider} rejected this key — check the paste, or whether it is the right provider`;
+    if (verdict.reason === "unreachable")
+        return `couldn't reach ${provider} to check the key — it is stored; verify later`;
+    return `${provider} gave an unexpected response (${verdict.status}) — the key is stored, but unverified`;
+}
+/** What a surface may say about a key: that it exists and when it last
+ * changed — NEVER the value, never a prefix, never a length. */
+export function keyStatus(provider, home = homedir()) {
+    try {
+        const stat = statSync(keyFileFor(provider, home));
+        return { set: true, updatedAt: stat.mtime.toISOString() };
+    }
+    catch {
+        return { set: false, updatedAt: null };
+    }
+}

package/dist/kits-ui.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Starter kits pages: the gallery — each kit's promise, what it sets
+ * up, one button — and a kit's own page: its checklist, with the next step on
+ * each line (connect email, connect a tool, try a sample card).
+ */
+import type { Store } from "./store.js";
+import { type Kit } from "./kits.js";
+export declare const KITS_CSS: string;
+/** The gallery: every kit, set up in a project with one button (or opened, when it's already there). */
+export declare function kitsGalleryHtml(store: Store, projects: readonly string[], projectName: (repo: string) => string, csrf: string, canSetUp: boolean, notice: {
+    problem?: string | null;
+}): string;
+/** A kit's own page: what's set up, and the next step on each line. */
+export declare function kitPageHtml(store: Store, kit: Kit, repo: string, dir: string | null, csrf: string, canSetUp: boolean, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;

package/dist/kits-ui.js

@@ -0,0 +1,46 @@
+import { kitChecklist, kitInstalled, KITS } from "./kits.js";
+import { TEAMMATE_TEMPLATES } from "./teammates.js";
+const e = (text) => text.replace(/[&<>"']/g, one => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[one]);
+const hidden = (csrf) => `<input type="hidden" name="csrf" value="${e(csrf)}">`;
+const CHECK = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg>`;
+const RING = `<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="8"/></svg>`;
+export const KITS_CSS = `.kits{max-width:960px;min-width:0}.kits-lede{color:var(--so-muted);margin:.25rem 0 1.5rem;max-width:40rem}.kit-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:16px}` +
+    `.kit{display:flex;flex-direction:column;gap:10px;padding:20px;border:1px solid var(--so-line);border-radius:12px;background:var(--so-paper)}.kit h2{font-size:1.1rem;margin:0}.kit p{margin:0}.kit .kit-promise{line-height:1.5}` +
+    `.kit .kit-gets{font-size:.85rem;color:var(--so-muted);line-height:1.5}.kit form{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin-top:auto;padding-top:6px}.kit form label{display:grid;gap:4px;font-size:.85rem;flex:1 1 140px}` +
+    `.kit button,.kit .kit-open{min-height:44px}.kit .kit-open{display:inline-flex;align-items:center;margin-top:auto;font-weight:600}` +
+    `.kit-steps{list-style:none;padding:0;margin:1rem 0;display:grid;gap:2px;max-width:44rem}.kit-steps li{display:flex;align-items:center;gap:12px;padding:12px 14px;border:1px solid var(--so-line);border-radius:10px;background:var(--so-paper)}` +
+    `.kit-steps svg{flex:none;width:20px;height:20px;fill:none;stroke:currentColor;stroke-width:2.2;stroke-linecap:round;stroke-linejoin:round}.kit-steps li[data-done="true"] svg{color:var(--so-success)}.kit-steps li[data-done="false"] svg{color:var(--so-muted)}` +
+    `.kit-steps .kit-step-said{flex:1;min-width:0}.kit-steps li[data-done="true"] .kit-step-said{color:var(--so-muted)}.kit-steps form{margin:0}.kit-steps button,.kit-steps .kit-step-go{min-height:40px;white-space:nowrap}` +
+    `.kit-steps .kit-step-go{display:inline-flex;align-items:center;padding:0 12px;border:1px solid var(--so-line);border-radius:8px;text-decoration:none;font-size:.9rem}` +
+    `@media(max-width:600px){.kit-steps li{flex-wrap:wrap}.kit-steps .kit-step-said{flex-basis:calc(100% - 40px)}.kit form select{font-size:16px}}`;
+const teammateWords = (kit) => { const template = TEAMMATE_TEMPLATES.find(one => one.id === kit.teammate.template); return template === undefined ? kit.teammate.handle : template.label.toLowerCase(); };
+/** The gallery: every kit, set up in a project with one button (or opened, when it's already there). */
+export function kitsGalleryHtml(store, projects, projectName, csrf, canSetUp, notice) {
+    const cards = KITS.map(kit => {
+        const here = projects.filter(repo => kitInstalled(store, kit, repo) !== null);
+        const open = projects.length === 1 && here.length === 1;
+        const name = kit.teammate.handle.charAt(0).toUpperCase() + kit.teammate.handle.slice(1);
+        const gets = `${name} (${teammateWords(kit)}) · the ${kit.flowName} flow${kit.tools.length === 0 ? "" : ` · works with ${kit.tools.map(one => one.label).join(" and ")}`}`;
+        const action = open ? `<a class="kit-open" href="/kits/${kit.id}?repo=${encodeURIComponent(projects[0])}">Open ${e(kit.name)} →</a>`
+            : !canSetUp || projects.length === 0 ? ""
+                : `<form method="post" action="/kits/${kit.id}/setup">${hidden(csrf)}${projects.length === 1 ? `<input type="hidden" name="repo" value="${e(projects[0])}">`
+                    : `<label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}${here.includes(repo) ? " (set up)" : ""}</option>`).join("")}</select></label>`}<button>Set it up</button></form>`;
+        return `<article class="kit" data-kit="${kit.id}"><h2>${e(kit.name)}</h2><p class="kit-promise">${e(kit.promise)}</p><p class="kit-gets">${e(gets)}</p>${action}</article>`;
+    }).join("");
+    return `<section class="kits">${notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : ""}<p class="kits-lede">A working setup in one click: an AI teammate, the flow it works, and what to connect next. Nothing goes out without you approving it.</p><div class="kit-grid">${cards}</div></section>`;
+}
+/** A kit's own page: what's set up, and the next step on each line. */
+export function kitPageHtml(store, kit, repo, dir, csrf, canSetUp, notice) {
+    const steps = kitChecklist(store, kit, repo, dir);
+    const set = kitInstalled(store, kit, repo);
+    const rows = steps.map(step => {
+        const go = step.done ? (step.href === null ? "" : `<a class="kit-step-go" href="${e(step.href)}">Open</a>`)
+            : step.action === "sample" || step.action === "github"
+                ? (canSetUp ? `<form method="post" action="/kits/${kit.id}/${step.action}">${hidden(csrf)}<input type="hidden" name="repo" value="${e(repo)}"><button${step.action === "sample" ? "" : ' class="secondary"'}>${step.action === "sample" ? "Try it" : "Bring them in"}</button></form>` : "")
+                : step.href === null ? "" : `<a class="kit-step-go" href="${e(step.href)}">${step.action === "connect" ? "Connect" : "Set up"}</a>`;
+        return `<li data-step="${e(step.id)}" data-done="${step.done}">${step.done ? CHECK : RING}<span class="kit-step-said">${e(step.said)}</span>${go}</li>`;
+    }).join("");
+    const setUp = set === null && canSetUp ? `<form method="post" action="/kits/${kit.id}/setup">${hidden(csrf)}<input type="hidden" name="repo" value="${e(repo)}"><button>Set up ${e(kit.name)}</button></form>` : "";
+    return `<section class="kits">${notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : ""}${notice.said ? `<p class="said" role="status">${e(notice.said)}</p>` : ""}` +
+        `<p class="kits-lede">${e(kit.promise)}</p>${setUp}${rows === "" ? "" : `<ol class="kit-steps">${rows}</ol>`}<p class="meta"><a href="/kits">All starter kits</a></p></section>`;
+}

package/dist/kits.d.ts

@@ -0,0 +1,86 @@
+import { type FlowStepInput } from "./flows.js";
+import type { FlowRow, Store, TeammateRow } from "./store.js";
+import { type ToolIo } from "./teammate-tools.js";
+/** A tool a kit's teammate works better with: the catalog entry that connects it, and why. */
+export type KitTool = {
+    tool: string;
+    label: string;
+    why: string;
+};
+export type Kit = {
+    id: string;
+    name: string;
+    promise: string;
+    /** The teammate it hires: a template, and the name it starts with. */
+    teammate: {
+        template: string;
+        handle: string;
+    };
+    flowName: string;
+    steps: FlowStepInput[];
+    /** Triggers safe to add at once: buttons (they fire only when pressed). */
+    buttons: {
+        label: string;
+        questions: string[];
+    }[];
+    /** Other ways in, offered on its checklist. */
+    email?: boolean;
+    github?: boolean;
+    tools: KitTool[];
+    sample: {
+        title: string;
+        description: string;
+    };
+};
+export declare const KITS: readonly Kit[];
+export declare const kitOf: (id: string) => Kit | null;
+type Done = {
+    ok: true;
+    said: string;
+    flow: number;
+    teammate: number;
+} | {
+    ok: false;
+    said: string;
+};
+/** A kit set up in a project: its flow (by name) and its teammate, when both are there. */
+export declare function kitInstalled(store: Store, kit: Kit, repo: string): {
+    flow: FlowRow;
+    mate: TeammateRow;
+} | null;
+/**
+ * Set a kit up: its teammate (kept if one of that name is already there), its
+ * flow, and its button triggers; then its teammate may use whichever of the
+ * kit's tools the project already has (reading free, writing asking first).
+ */
+export declare function setUpKit(store: Store, kit: Kit, repo: string, by: string, now: Date, dir: string | null, io?: ToolIo): Promise<Done>;
+/** The same, all at once (a chat confirmation can't wait on a tool): its teammate is given the kit's connected tools by the names their last test found, and each is listed properly on its first turn. */
+export declare function setUpKitNow(store: Store, kit: Kit, repo: string, by: string, now: Date, dir: string | null, grantByName?: boolean): Done;
+/** One line of a kit's checklist: done, or the next step with where to take it. */
+export type KitStep = {
+    id: string;
+    done: boolean;
+    said: string;
+    href: string | null;
+    action?: "sample" | "github" | "connect";
+    tool?: string;
+};
+/** What's set up and what's left, read fresh each time. */
+export declare function kitChecklist(store: Store, kit: Kit, repo: string, dir: string | null): KitStep[];
+/** A sample card in the kit's first zone, so its teammate starts on it at once. */
+export declare function addKitSample(store: Store, kit: Kit, repo: string, by: string, now: Date): {
+    ok: true;
+    href: string;
+} | {
+    ok: false;
+    said: string;
+};
+/** Bring new issues from the project's GitHub repository into the kit's flow (issues from anyone, polled). */
+export declare function addKitGithubTrigger(store: Store, kit: Kit, repo: string, by: string, now: Date, dir: string | null): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    said: string;
+};
+export {};

package/dist/kits.js

@@ -0,0 +1,215 @@
+/**
+ * Starter kits: a working setup in one click — an AI teammate, the flow
+ * it works, and the triggers that are safe to add straight away — plus a
+ * checklist of what's left (connect email, connect a tool) and a sample card
+ * that shows the teammate at work within seconds.
+ *
+ * A kit adds nothing a person couldn't add by hand, and nothing that acts
+ * outside: replies go out only after you approve them, a code change is filed
+ * as an ordinary task you approve, and tools start with reading free and
+ * writing asking first.
+ */
+import { addCardToFlow, flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { flowFromSteps } from "./flows.js";
+import { addFlowTriggerTo, githubRepoOf, triggerConfigOf } from "./flow-triggers.js";
+import { googleConnected } from "./google-mail.js";
+import { readEmailSettings } from "./email-settings.js";
+import { mailboxReady } from "./mailbox.js";
+import { projectToolsOf } from "./project-tools.js";
+import { createTeammateFrom, nameOf } from "./teammate-admin.js";
+import { grantListed, grantTool } from "./teammate-tools.js";
+import { TEAMMATE_TEMPLATES } from "./teammates.js";
+export const KITS = [
+    {
+        id: "support-desk", name: "Support desk",
+        promise: "Maya answers customer emails, looks orders up and refunds within limits you set. You approve each reply before it goes out.",
+        teammate: { template: "support", handle: "maya" },
+        flowName: "Support desk",
+        steps: [
+            { id: "answer", title: "Maya answers", kind: "teammate", teammate: "maya",
+                instructions: "Read the customer's message. Look things up (and refund, within your rules) with your tools when it helps. Write the reply we'd send in \"text\". Pick Reply when it's ready for the customer, or Needs a person when your rules say to ask first or you can't help.",
+                routes: [{ answer: "Reply", goesTo: "You check the reply" }, { answer: "Needs a person", goesTo: "For you" }], ifFails: "For you" },
+            { id: "check", title: "You check the reply", kind: "approval", decider: "owner", next: "Send it", ifFails: "Maya answers" },
+            { id: "send", title: "Send it", kind: "email", to: "{{card.email}}", subject: "Re: {{card.title}}", body: "{{stage.answer}}", next: "Done", ifFails: "For you" },
+            { id: "person", title: "For you", kind: "inbox" },
+            { id: "done", title: "Done", kind: "done" },
+        ],
+        buttons: [], email: true,
+        tools: [
+            { tool: "stripe", label: "Stripe", why: "so Maya can look payments up and refund within its limit" },
+            { tool: "intercom", label: "Intercom", why: "so Maya can read and answer your support conversations" },
+        ],
+        sample: { title: "Where's my order? It's been 9 days", description: "Hi! I ordered a desk lamp on the 14th (order #1042) and it still hasn't arrived. Could you check where it is? Thanks, Priya (priya@example.com)\n\nOrder #1042 in the shop: shipped on the 15th by UPS, out for delivery tomorrow." },
+    },
+    {
+        id: "bug-triage", name: "Bug triage",
+        promise: "Theo reads every new issue, says what it is and how urgent, answers questions, and turns real bugs into fixes you approve.",
+        teammate: { template: "triage", handle: "theo" },
+        flowName: "Bug triage",
+        steps: [
+            { id: "sort", title: "Theo sorts it", kind: "teammate", teammate: "theo",
+                instructions: "Read the report. In \"text\", say in one or two sentences what it is and how urgent (for a bug, add what you'd check first; for a question, write the answer). Pick Bug for something broken in this project's code, Question for someone asking how something works, or Duplicate or noise for anything else, saying why.",
+                routes: [{ answer: "Bug", goesTo: "Fix it" }, { answer: "Question", goesTo: "Answered" }, { answer: "Duplicate or noise", goesTo: "Closed" }], ifFails: "For you" },
+            { id: "fix", title: "Fix it", kind: "task", planning: "auto", instructions: "Fix the bug this card reports. Theo's notes on it: {{stage.sort}}", next: "You review the fix" },
+            { id: "review", title: "You review the fix", kind: "approval", decider: "owner", next: "Done", ifFails: "Fix it" },
+            { id: "answered", title: "Answered", kind: "inbox" },
+            { id: "person", title: "For you", kind: "inbox" },
+            { id: "closed", title: "Closed", kind: "done" },
+            { id: "done", title: "Done", kind: "done" },
+        ],
+        buttons: [{ label: "Report a bug", questions: ["What's wrong?", "How do we see it happen?"] }], github: true,
+        tools: [
+            { tool: "sentry", label: "Sentry", why: "so Theo can see the errors behind a report" },
+            { tool: "linear", label: "Linear", why: "so Theo can find duplicates in your issues" },
+        ],
+        sample: { title: "Checkout button does nothing on Safari", description: "On Safari 18 (Mac), pressing Checkout on the cart page does nothing: no error on screen, no redirect. Chrome works fine. Started after yesterday's release." },
+    },
+    {
+        id: "sales-follow-up", name: "Sales follow-up",
+        promise: "Leo writes back to every new lead within minutes, you approve the email, and it waits for their answer, so no lead goes cold.",
+        teammate: { template: "sales", handle: "leo" },
+        flowName: "Sales follow-up",
+        steps: [
+            { id: "write", title: "Leo writes back", kind: "teammate", teammate: "leo",
+                instructions: "Read the lead. In \"text\", write a short, friendly first reply that answers what they asked and suggests one clear next step. Pick Write back, or Not a fit (say why).",
+                routes: [{ answer: "Write back", goesTo: "You check it" }, { answer: "Not a fit", goesTo: "Not a fit" }], ifFails: "Not a fit" },
+            { id: "check", title: "You check it", kind: "approval", decider: "owner", next: "Send it", ifFails: "Leo writes back" },
+            { id: "send", title: "Send it", kind: "email", to: "{{card.email}}", subject: "Re: {{card.title}}", body: "{{stage.write}}", next: "Wait for them", ifFails: "Not a fit" },
+            { id: "wait", title: "Wait for them", kind: "wait", waitFor: "reply", wait: "3 days", next: "They replied", ifNoReply: "No reply yet" },
+            { id: "replied", title: "They replied", kind: "inbox" },
+            { id: "quiet", title: "No reply yet", kind: "inbox" },
+            { id: "no-fit", title: "Not a fit", kind: "done" },
+        ],
+        buttons: [{ label: "New lead", questions: ["Who are they?", "Their email", "What do they want?"] }], email: true,
+        tools: [{ tool: "attio", label: "Attio", why: "so Leo can look leads up in your CRM and log each reply" }],
+        sample: { title: "Acme Co wants a demo", description: "Hi, I'm Dana, head of ops at Acme Co (about 40 people). We're looking for a better way to handle customer requests and would love a demo next week. dana@acme.example" },
+    },
+    {
+        id: "ops-requests", name: "Ops requests",
+        promise: "Ada approves routine requests under $200 without you and brings you everything else, so the team gets answers the same day.",
+        teammate: { template: "ops", handle: "ada" },
+        flowName: "Ops requests",
+        steps: [
+            { id: "decide", title: "Ada decides", kind: "approval", teammate: "ada", decider: "owner", next: "Tell the team", ifFails: "Needs more" },
+            { id: "tell", title: "Tell the team", kind: "notify", message: "Approved: {{card.title}}", next: "Done" },
+            { id: "more", title: "Needs more", kind: "inbox" },
+            { id: "done", title: "Done", kind: "done" },
+        ],
+        buttons: [{ label: "Ask for something", questions: ["What do you need?", "Why?", "What will it cost?"] }],
+        tools: [
+            { tool: "notion", label: "Notion", why: "so Ada can check your team's policies and past requests" },
+            { tool: "atlassian", label: "Jira", why: "so Ada can file the ticket once something's approved" },
+        ],
+        sample: { title: "New monitor for Sam", description: "Sam's monitor died this morning. A replacement 27\" monitor, same model as the rest of the team: $180. Sam needs it to work. Owner: Sam." },
+    },
+];
+export const kitOf = (id) => KITS.find(one => one.id === id) ?? null;
+/** A kit set up in a project: its flow (by name) and its teammate, when both are there. */
+export function kitInstalled(store, kit, repo) {
+    const mate = store.teammateByHandle(repo, kit.teammate.handle);
+    const flow = store.listFlows([repo]).find(one => one.name === kit.flowName && one.state === "active") ?? null;
+    return mate === null || flow === null ? null : { flow, mate };
+}
+/**
+ * Set a kit up: its teammate (kept if one of that name is already there), its
+ * flow, and its button triggers; then its teammate may use whichever of the
+ * kit's tools the project already has (reading free, writing asking first).
+ */
+export async function setUpKit(store, kit, repo, by, now, dir, io = {}) {
+    const made = setUpKitNow(store, kit, repo, by, now, dir);
+    if (!made.ok || made.said.endsWith("already set up here."))
+        return made;
+    const mate = store.getTeammate(made.teammate);
+    const present = new Set(projectToolsOf(store, repo).map(one => one.name));
+    for (const tool of kit.tools.filter(one => present.has(one.tool))) {
+        try {
+            await grantTool(store, mate, tool.tool, by, now, io);
+        }
+        catch { /* it can be given the tool on its page */ }
+    }
+    return made;
+}
+/** The same, all at once (a chat confirmation can't wait on a tool): its teammate is given the kit's connected tools by the names their last test found, and each is listed properly on its first turn. */
+export function setUpKitNow(store, kit, repo, by, now, dir, grantByName = false) {
+    const had = kitInstalled(store, kit, repo);
+    if (had !== null)
+        return { ok: true, said: `${kit.name} is already set up here.`, flow: had.flow.id, teammate: had.mate.id };
+    let mate = store.teammateByHandle(repo, kit.teammate.handle);
+    if (mate === null) {
+        const template = TEAMMATE_TEMPLATES.find(one => one.id === kit.teammate.template);
+        if (template === undefined)
+            return { ok: false, said: "That kit's teammate template is missing." };
+        const made = createTeammateFrom(store, { repo, template: template.id, by }, now);
+        if (!made.ok)
+            return { ok: false, said: made.said };
+        mate = store.getTeammate(made.id);
+    }
+    let definition;
+    try {
+        definition = flowFromSteps(kit.steps, null);
+    }
+    catch (error) {
+        return { ok: false, said: `The kit's flow didn't fit: ${error instanceof Error ? error.message : "unknown"}` };
+    }
+    const flowId = store.createFlow({ repo, name: kit.flowName, definitionJson: JSON.stringify(definition), by }, now);
+    const flow = store.getFlow(flowId);
+    for (const button of kit.buttons)
+        addFlowTriggerTo(store, flow, { kind: "button", label: button.label, questions: button.questions, zone: definition.start }, by, now, dir);
+    if (grantByName)
+        for (const tool of projectToolsOf(store, repo).filter(one => kit.tools.some(each => each.tool === one.name)))
+            grantListed(store, mate, tool, null, by, now);
+    return { ok: true, said: `${kit.name} is ready: ${nameOf(mate)} works its ${kit.flowName} flow.`, flow: flowId, teammate: mate.id };
+}
+/** What's set up and what's left, read fresh each time. */
+export function kitChecklist(store, kit, repo, dir) {
+    const set = kitInstalled(store, kit, repo);
+    if (set === null)
+        return [];
+    const name = nameOf(set.mate);
+    const steps = [
+        { id: "teammate", done: true, said: `${name} joined the team`, href: `/teammates/${set.mate.id}` },
+        { id: "flow", done: true, said: `The ${kit.flowName} flow is ready`, href: `/flows/${set.flow.id}` },
+    ];
+    if (kit.email === true) {
+        // (flow-actions' sendingReady, without its imports: kits load beside the chat actions.)
+        const ready = (googleConnected(dir) !== null || readEmailSettings(dir) !== null) && mailboxReady(dir);
+        steps.push({ id: "email", done: ready, said: ready ? "Email is connected" : "Connect your email so replies go out and answers come back", href: "/settings#email" });
+    }
+    if (kit.github === true) {
+        const github = githubRepoOf(repo);
+        const watching = store.flowTriggers(set.flow.id).some(one => one.state !== "removed" && triggerConfigOf(one)?.kind === "github");
+        if (github !== null)
+            steps.push({ id: "github", done: watching, said: watching ? `New issues on ${github} come in` : `Bring in new issues from ${github}`, href: watching ? `/flows/${set.flow.id}` : null, ...(watching ? {} : { action: "github" }) });
+    }
+    const tools = projectToolsOf(store, repo);
+    for (const tool of kit.tools) {
+        const connected = tools.some(one => one.name === tool.tool);
+        const granted = store.teammateGrant(set.mate.id, tool.tool) !== null;
+        steps.push(connected && granted
+            ? { id: `tool-${tool.tool}`, done: true, said: `${name} can use ${tool.label}`, href: `/teammates/${set.mate.id}#tools` }
+            : connected
+                ? { id: `tool-${tool.tool}`, done: false, said: `Let ${name} use ${tool.label}, ${tool.why}`, href: `/teammates/${set.mate.id}#tools` }
+                : { id: `tool-${tool.tool}`, done: false, said: `Connect ${tool.label}, ${tool.why}`, href: `/settings/tools?repo=${encodeURIComponent(repo)}&kit=${kit.id}&connect=${tool.tool}#connect`, action: "connect", tool: tool.tool });
+    }
+    const tried = store.flowCards(set.flow.id, true).length > 0;
+    steps.push({ id: "sample", done: tried, said: tried ? `${name} has worked a card` : `See ${name} work a sample card`, href: tried ? `/flows/${set.flow.id}` : null, ...(tried ? {} : { action: "sample" }) });
+    return steps;
+}
+/** A sample card in the kit's first zone, so its teammate starts on it at once. */
+export function addKitSample(store, kit, repo, by, now) {
+    const set = kitInstalled(store, kit, repo);
+    if (set === null)
+        return { ok: false, said: `Set ${kit.name} up first.` };
+    const definition = flowDefinitionOf(set.flow);
+    const added = addCardToFlow(store, set.flow, { title: kit.sample.title, description: kit.sample.description, stage: definition?.start ?? null }, by, now);
+    return added.ok ? { ok: true, href: flowCardHref(set.flow.id, added.card) } : { ok: false, said: added.message };
+}
+/** Bring new issues from the project's GitHub repository into the kit's flow (issues from anyone, polled). */
+export function addKitGithubTrigger(store, kit, repo, by, now, dir) {
+    const set = kitInstalled(store, kit, repo);
+    const github = githubRepoOf(repo);
+    if (set === null || github === null)
+        return { ok: false, said: "This project isn't on GitHub." };
+    const made = addFlowTriggerTo(store, set.flow, { kind: "github", repo: github, watch: "issues", from: "anyone", delivery: "poll", zone: flowDefinitionOf(set.flow)?.start }, by, now, dir);
+    return made.ok ? { ok: true, said: `New issues on ${github} now come into ${kit.flowName}.` } : { ok: false, said: made.message };
+}