weftens 0.1.0 → 0.1.1

package/README.md

@@ -1,18 +1,57 @@
 # Weftens
 
-One front door for marketing and representation work. You say what you need; Weftens routes it
-to the right agent and runs it — on **your own AI subscription**, no API key.
-
-The name comes from **weft** — in weaving, the cross-thread pulled through the warp that binds loose
-strands into one cloth. Weftens binds a set of marketing, SEO, ads, and representation agents behind
-one command.
-
-## Bring your own model
-
-Weftens is a free tool. No account, no billing, no API key — nobody is billed through Weftens. The
-model-backed agents run through whatever AI CLI you already have and are logged into (**Claude**,
-**Gemini**, **Codex/GPT**, or **Grok** — your choice). Many agents need no model at all: the ad and
-SEO auditors are deterministic and run on your exported reports.
+**Where did the ad money go, and what should change?** Give Weftens an exported report from
+Google Ads, Meta, Amazon, or an SEO crawl, and it gives you back a ranked change sheet — each
+recommendation with where it applies, why it's proposed, what it's worth, and what could go
+wrong if you're wrong.
+
+    4 proposed changes  |  $604.27 of spend flagged
+    account: spend $910.00, 208 clicks, 11 conversions, CPA $82.73
+
+    1. Bid down or restrict "premium widget wholesale bulk"   $417.27
+       where  campaign: Brand / Brand - Exact
+       why    CPA $500 vs account $82.73 (6x); $500 for 1 conv
+       risk   Converting term — restricting too hard can cut real volume; prefer a bid cut first.
+
+    2. Add "free blue widgets" as a negative keyword   $90.00
+       where  campaign: Generic / Widgets - Broad
+       why    60 clicks, $90 spent, 0 conversions (expected ~3.2 at the 5.3% account rate)
+       risk   If the query is actually relevant, you forfeit those impressions.
+
+    Proposals only — nothing was sent to your ad account. Apply what you agree with.
+
+That is the actual output of the sample export included in this repo, produced by:
+
+    npm i weftens
+    npx weftens send paid-search audit --input agent-cores/paid-search/test/fixtures/search-terms.csv
+
+**Same file in, same change sheet out, every time.** The ad and SEO auditors are arithmetic, not
+a model — nothing is generated, so nothing can be invented, and two runs can be diffed to prove
+nothing moved. They read a file you already have and **never sign in to your ad account**. Note
+the second line of the first recommendation: that keyword *converted*. "Flagged" means the numbers
+crossed a threshold, not that the money is guaranteed back — the risk line is there because the
+call is still yours.
+
+**Not technical?** You don't have to run this. Send the repo link and your exported report to
+whoever manages your ads, or paste this to an AI assistant that can use your computer
+(Claude, ChatGPT/Codex, Gemini): *"install weftens and run the paid-search audit on my export."*
+
+## What's finished, and what isn't
+
+- **Finished and deterministic — seven auditors:** paid search (Google Ads), paid social (Meta),
+  Amazon PPC, technical SEO, content SEO, supply-path verification, content operations. No model,
+  no key, propose-only.
+- **Model-backed seats** run on an AI CLI *you* already have and are logged into — your
+  subscription, no API key, nobody is billed through Weftens. They are only as good as the model
+  you point them at. `claude` and `codex` are verified; `gemini` and `grok` are configured but have
+  never been run.
+- **Two seats are not in this repo.** `richy` (representation) and `pio` (prospect research) are
+  clients for separate services that aren't open source. Without those services configured they
+  return sample data that says so in its own output.
+- **The content pipeline is a placeholder.** Ten seats exist; it emits stub output and does not yet
+  take a free-text brief.
+
+Free, MIT licensed, no account, no billing.
 
 ## Install
 
@@ -116,9 +155,10 @@ CLI prints which words matched, so you always see why a request went where it di
 - **The router refuses rather than guesses.** Generic words alone ("site", "listing", "people") no
   longer dispatch — a confident wrong route in front of a customer costs more than a reprompt.
 - **Licensed MIT.** Free to use, including commercially.
-- **On npm as a name-holder, not yet as the tool:** `weftens@0.0.1` reserves the package name and
-  contains no code. Clone the repo to run it. The working release follows; `"private": true` in
-  package.json is a deliberate catch so the real publish is a decision, not an accident.
+- **Published:** `npm i weftens` installs the real thing (`weftens@0.1.0`, MIT). Verified from the
+  registry by a clean third-party install — `npx weftens list` prints the registry, and a
+  deterministic core runs a real audit from inside `node_modules`. (`0.0.1` was an empty name-holder;
+  ignore it.)
 - **Two providers verified, not one:** `claude` and `codex` both produce end-to-end through the
   user's own subscription (codex confirmed 2026-07-19). `gemini` and `grok` remain config-only — the
   shape is right, but neither CLI is installed here, so neither has been run. A missing or broken

package/bin/weftens.js

@@ -1,226 +1,234 @@
-#!/usr/bin/env node
-// Weftens CLI — the agent front door.
-//
-//   weftens ask "how do we look online and who came to our events?" --org "Acme" [--website https://…]
-//   weftens chat --org "Acme"                       # interactive conversation
-//   weftens route request.json                      # deterministic router/synthesizer (no LLM, no key)
-//   echo '{"org":{...},"question":"..."}' | weftens route -
-//
-// ask/chat need ANTHROPIC_API_KEY (or an `ant auth login` profile). Specialists:
-//   WEFTENS_RICHY_URL + WEFTENS_RICHY_KEY                       → live Richy audit service
-//   WEFTENS_PIO_URL + WEFTENS_PIO_MEMBER + WEFTENS_PIO_PASSWORD → live PIO (member session)
-//   WEFTENS_PIO_TENANT                                          → tenant slug (hosted PIO only)
-// Without them the specialists run as clearly-flagged fixtures so the agent always works.
-
-import { readFileSync } from "node:fs";
-import readline from "node:readline";
-import { orchestrate } from "../src/weftens.js";
-import { askWeftens } from "../src/agent.js";
-import { RichyClient, FixtureRichyClient } from "../src/richy-client.js";
-import { PioClient, FixturePioClient } from "../src/pio-client.js";
-import { route } from "../src/agent-router.js";
-import { invoke } from "../src/invoke.js";
-import { REGISTRY, dispatchableAgents } from "../src/registry.js";
-
-// A specialist is live only when its FULL env group is set. A partial group is a
-// hard error, not a silent fixture fallback — an operator who typo'd one variable
-// would otherwise get sample data while believing they're looking at their org.
-function envGroup(label, names) {
-  const set = names.filter((n) => process.env[n]);
-  if (set.length === 0) return null;
-  if (set.length < names.length) {
-    const missing = names.filter((n) => !process.env[n]).join(", ");
-    throw new Error(`${label} is partially configured — set ${missing} (or unset ${set.join(", ")} to run with sample data)`);
-  }
-  return Object.fromEntries(names.map((n) => [n, process.env[n]]));
-}
-
-function buildAgents() {
-  const richyEnv = envGroup("Richy", ["WEFTENS_RICHY_URL", "WEFTENS_RICHY_KEY"]);
-  const pioEnv = envGroup("PIO", ["WEFTENS_PIO_URL", "WEFTENS_PIO_MEMBER", "WEFTENS_PIO_PASSWORD"]);
-  const richy = richyEnv
-    ? new RichyClient({ baseUrl: richyEnv.WEFTENS_RICHY_URL, key: richyEnv.WEFTENS_RICHY_KEY })
-    : new FixtureRichyClient();
-  const pio = pioEnv
-    ? new PioClient({
-        baseUrl: pioEnv.WEFTENS_PIO_URL,
-        member: pioEnv.WEFTENS_PIO_MEMBER,
-        password: pioEnv.WEFTENS_PIO_PASSWORD,
-        tenant: process.env.WEFTENS_PIO_TENANT ?? null,
-      })
-    : new FixturePioClient();
-  const fixtures = [!richyEnv && "Richy", !pioEnv && "PIO"].filter(Boolean);
-  if (fixtures.length > 0) {
-    process.stderr.write(`weftens: ${fixtures.join(" and ")} not configured — using clearly-flagged sample data\n`);
-  }
-  return { richy, pio };
-}
-
-function parseFlags(args) {
-  const flags = {};
-  const rest = [];
-  for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === "--org") flags.org = args[++i];
-    else if (args[i] === "--website") flags.website = args[++i];
-    else rest.push(args[i]);
-  }
-  return { flags, rest };
-}
-
-function orgPreamble(flags) {
-  if (!flags.org) return "";
-  const site = flags.website ? ` (website: ${flags.website})` : "";
-  return `The organization we're discussing is "${flags.org}"${site}. `;
-}
-
-async function cmdAsk(args) {
-  const { flags, rest } = parseFlags(args);
-  const question = rest.join(" ").trim();
-  if (!question) {
-    process.stderr.write('usage: weftens ask "<question>" [--org NAME] [--website URL]\n');
-    process.exitCode = 1;
-    return;
-  }
-  const { text } = await askWeftens({ question: orgPreamble(flags) + question, agents: buildAgents() });
-  process.stdout.write(`${text}\n`);
-}
-
-async function cmdChat(args) {
-  const { flags } = parseFlags(args);
-  const agents = buildAgents();
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  let history = [];
-  let first = true;
-  process.stdout.write("Weftens. Ask about how your organization looks online or how it's running. Ctrl+C to exit.\n");
-  for (;;) {
-    const line = await new Promise((resolve) => rl.question("> ", resolve));
-    const question = line.trim();
-    if (!question) continue;
-    if (question === "exit" || question === "quit") break;
-    try {
-      const { text, messages } = await askWeftens({
-        question: first ? orgPreamble(flags) + question : question,
-        history,
-        agents,
-      });
-      history = messages;
-      first = false;
-      process.stdout.write(`${text}\n`);
-    } catch (error) {
-      process.stderr.write(`weftens: ${error?.message ?? error}\n`);
-    }
-  }
-  rl.close();
-}
-
-async function cmdRoute(arg) {
-  const raw = !arg || arg === "-" ? readFileSync(0, "utf8") : readFileSync(arg, "utf8");
-  const result = await orchestrate(JSON.parse(raw), buildAgents());
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-// --- Registry front door: route across the whole roster, not just Richy/PIO ---
-// `list` shows the directory (and prints the live count); `send` routes a request
-// (auto or direct-addressed) and
-// invokes the chosen agent. Deterministic routing needs no key; see src/invoke.js for
-// what producing needs. This sits alongside ask/chat (the Richy+PIO conversational
-// surface) — those two agents are also reachable here through the registry.
-
-function cmdList() {
-  const pad = (s, n) => String(s).padEnd(n);
-  process.stdout.write(`Weftens registry — ${REGISTRY.length} agents (${dispatchableAgents().length} dispatchable at the door)\n\n`);
-  process.stdout.write(`${pad("AGENT", 18)}${pad("TIER", 6)}${pad("TEAM", 12)}${pad("CORE", 6)}OWNED-BY\n`);
-  for (const a of REGISTRY) {
-    const owned = a.ownedBy ?? (a.leads ? `(leads ${a.leads})` : "-");
-    process.stdout.write(`${pad(a.name, 18)}${pad(a.tier, 6)}${pad(a.team, 12)}${pad(a.core ? "yes" : "-", 6)}${owned}\n`);
-  }
-}
-
-async function cmdSend(args, { routeOnly } = {}) {
-  const rest = [];
-  let inputFile = null, provider = null, org = null, website = null;
-  for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === "--input") inputFile = args[++i] ?? null;
-    else if (args[i] === "--provider") provider = args[++i] ?? null;
-    else if (args[i] === "--org") org = args[++i] ?? null;
-    else if (args[i] === "--website") website = args[++i] ?? null;
-    else rest.push(args[i]);
-  }
-  const firstIsAgent = rest.length >= 1 && REGISTRY.some((a) => a.name === rest[0].toLowerCase());
-  const request = firstIsAgent
-    ? { agent: rest[0], text: rest.slice(1).join(" ") }
-    : { text: rest.join(" ") };
-  if (!request.text && !request.agent) {
-    process.stderr.write('usage: weftens send "<request>"  |  weftens send <agent> "<request>"\n');
-    process.exitCode = 1;
-    return;
-  }
-  const decision = route(request);
-  if (!decision.agent) {
-    process.stdout.write(`→ (no route) — ${decision.reason}\n`);
-    process.exitCode = 1;
-    return;
-  }
-  process.stdout.write(`→ ${decision.agent.name}  [${decision.reason}]${decision.confident ? "" : "  (low confidence)"}\n`);
-  if (decision.alternatives?.length) {
-    process.stdout.write(`  also considered: ${decision.alternatives.map((x) => `${x.name}(${x.score})`).join(", ")}\n`);
-  }
-  if (routeOnly) return;
-
-  // Richy and PIO are specialist legs: they answer about an ORGANIZATION, not about a
-  // bare sentence, so they run through orchestrate() rather than as leaf agents. They
-  // used to refuse here with a note about "wire contracts" — true internally, useless
-  // to the person typing, and wrong in effect: the legs are reachable (with fixture
-  // clients when unconfigured), so refusing categorically made the two headline seats
-  // look dead. Now `send richy --org NAME "<question>"` does the real thing.
-  if (decision.agent.tier === 1 && decision.agent.wire) {
-    // An org is genuinely required — Richy audits a specific organization, PIO reports on one —
-    // but demanding a FLAG for it is a door that doesn't open for a plain sentence. Whoever is
-    // running this almost always means the same org every time, so it's config, not an argument:
-    // set WEFTENS_ORG once and `send richy "audit our listings"` just works.
-    org = org ?? process.env.WEFTENS_ORG ?? null;
-    website = website ?? process.env.WEFTENS_WEBSITE ?? null;
-    if (!org) {
-      process.stdout.write(
-        `\n[orchestrator] ${decision.agent.name} answers about a specific organization — which one?\n` +
-        `  once:    weftens send ${decision.agent.name} --org "Acme Co" [--website acme.com] "${request.text || "your question"}"\n` +
-        `  always:  set WEFTENS_ORG="Acme Co" (and optionally WEFTENS_WEBSITE) — then this command works as typed\n`
-      );
-      process.exitCode = 1;
-      return;
-    }
-    const intent = decision.agent.name === "richy" ? "representation" : "operations";
-    const result = await orchestrate(
-      { org: { name: org, ...(website ? { website } : {}) }, intent, question: request.text || undefined },
-      buildAgents()
-    );
-    process.stdout.write(`\n[orchestrator] ran ${decision.agent.name} over ${org} (intent: ${intent})\n`);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-
-  const outcome = await invoke(decision.agent, { text: request.text, inputFile, provider });
-  process.stdout.write(`\n[${outcome.path}] ${outcome.note}\n`);
-  if (outcome.result !== undefined) {
-    process.stdout.write(`\n--- result ---\n${typeof outcome.result === "string" ? outcome.result : JSON.stringify(outcome.result, null, 2)}\n`);
-  }
-}
-
-async function main() {
-  const [command, ...args] = process.argv.slice(2);
-  if (command === "ask") return cmdAsk(args);
-  if (command === "chat") return cmdChat(args);
-  if (command === "list" || command === "--list") return cmdList();
-  if (command === "send") return cmdSend(args);
-  if (command === "--route") return cmdSend(args, { routeOnly: true });
-  if (command === "route" || (command && (command === "-" || command.endsWith(".json")))) {
-    return cmdRoute(command === "route" ? args[0] : command);
-  }
-  process.stderr.write("usage: weftens ask|chat|list|send|--route|route …\n");
-  process.exitCode = 1;
-}
-
-main().catch((error) => {
-  process.stderr.write(`weftens: ${error?.message ?? error}\n`);
-  process.exitCode = 1;
-});
+#!/usr/bin/env node
+// Weftens CLI — the agent front door.
+//
+//   weftens ask "how do we look online and who came to our events?" --org "Acme" [--website https://…]
+//   weftens chat --org "Acme"                       # interactive conversation
+//   weftens route request.json                      # deterministic router/synthesizer (no LLM, no key)
+//   echo '{"org":{...},"question":"..."}' | weftens route -
+//
+// ask/chat need ANTHROPIC_API_KEY (or an `ant auth login` profile). Specialists:
+//   WEFTENS_RICHY_URL + WEFTENS_RICHY_KEY                       → live Richy audit service
+//   WEFTENS_PIO_URL + WEFTENS_PIO_MEMBER + WEFTENS_PIO_PASSWORD → live PIO (member session)
+//   WEFTENS_PIO_TENANT                                          → tenant slug (hosted PIO only)
+// Without them the specialists run as clearly-flagged fixtures so the agent always works.
+
+import { readFileSync } from "node:fs";
+import readline from "node:readline";
+import { orchestrate } from "../src/weftens.js";
+import { isChangeSheet, formatChangeSheet } from "../src/format.js";
+import { askWeftens } from "../src/agent.js";
+import { RichyClient, FixtureRichyClient } from "../src/richy-client.js";
+import { PioClient, FixturePioClient } from "../src/pio-client.js";
+import { route } from "../src/agent-router.js";
+import { invoke } from "../src/invoke.js";
+import { REGISTRY, dispatchableAgents } from "../src/registry.js";
+
+// A specialist is live only when its FULL env group is set. A partial group is a
+// hard error, not a silent fixture fallback — an operator who typo'd one variable
+// would otherwise get sample data while believing they're looking at their org.
+function envGroup(label, names) {
+  const set = names.filter((n) => process.env[n]);
+  if (set.length === 0) return null;
+  if (set.length < names.length) {
+    const missing = names.filter((n) => !process.env[n]).join(", ");
+    throw new Error(`${label} is partially configured — set ${missing} (or unset ${set.join(", ")} to run with sample data)`);
+  }
+  return Object.fromEntries(names.map((n) => [n, process.env[n]]));
+}
+
+function buildAgents() {
+  const richyEnv = envGroup("Richy", ["WEFTENS_RICHY_URL", "WEFTENS_RICHY_KEY"]);
+  const pioEnv = envGroup("PIO", ["WEFTENS_PIO_URL", "WEFTENS_PIO_MEMBER", "WEFTENS_PIO_PASSWORD"]);
+  const richy = richyEnv
+    ? new RichyClient({ baseUrl: richyEnv.WEFTENS_RICHY_URL, key: richyEnv.WEFTENS_RICHY_KEY })
+    : new FixtureRichyClient();
+  const pio = pioEnv
+    ? new PioClient({
+        baseUrl: pioEnv.WEFTENS_PIO_URL,
+        member: pioEnv.WEFTENS_PIO_MEMBER,
+        password: pioEnv.WEFTENS_PIO_PASSWORD,
+        tenant: process.env.WEFTENS_PIO_TENANT ?? null,
+      })
+    : new FixturePioClient();
+  const fixtures = [!richyEnv && "Richy", !pioEnv && "PIO"].filter(Boolean);
+  if (fixtures.length > 0) {
+    process.stderr.write(`weftens: ${fixtures.join(" and ")} not configured — using clearly-flagged sample data\n`);
+  }
+  return { richy, pio };
+}
+
+function parseFlags(args) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--org") flags.org = args[++i];
+    else if (args[i] === "--website") flags.website = args[++i];
+    else rest.push(args[i]);
+  }
+  return { flags, rest };
+}
+
+function orgPreamble(flags) {
+  if (!flags.org) return "";
+  const site = flags.website ? ` (website: ${flags.website})` : "";
+  return `The organization we're discussing is "${flags.org}"${site}. `;
+}
+
+async function cmdAsk(args) {
+  const { flags, rest } = parseFlags(args);
+  const question = rest.join(" ").trim();
+  if (!question) {
+    process.stderr.write('usage: weftens ask "<question>" [--org NAME] [--website URL]\n');
+    process.exitCode = 1;
+    return;
+  }
+  const { text } = await askWeftens({ question: orgPreamble(flags) + question, agents: buildAgents() });
+  process.stdout.write(`${text}\n`);
+}
+
+async function cmdChat(args) {
+  const { flags } = parseFlags(args);
+  const agents = buildAgents();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let history = [];
+  let first = true;
+  process.stdout.write("Weftens. Ask about how your organization looks online or how it's running. Ctrl+C to exit.\n");
+  for (;;) {
+    const line = await new Promise((resolve) => rl.question("> ", resolve));
+    const question = line.trim();
+    if (!question) continue;
+    if (question === "exit" || question === "quit") break;
+    try {
+      const { text, messages } = await askWeftens({
+        question: first ? orgPreamble(flags) + question : question,
+        history,
+        agents,
+      });
+      history = messages;
+      first = false;
+      process.stdout.write(`${text}\n`);
+    } catch (error) {
+      process.stderr.write(`weftens: ${error?.message ?? error}\n`);
+    }
+  }
+  rl.close();
+}
+
+async function cmdRoute(arg) {
+  const raw = !arg || arg === "-" ? readFileSync(0, "utf8") : readFileSync(arg, "utf8");
+  const result = await orchestrate(JSON.parse(raw), buildAgents());
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+// --- Registry front door: route across the whole roster, not just Richy/PIO ---
+// `list` shows the directory (and prints the live count); `send` routes a request
+// (auto or direct-addressed) and
+// invokes the chosen agent. Deterministic routing needs no key; see src/invoke.js for
+// what producing needs. This sits alongside ask/chat (the Richy+PIO conversational
+// surface) — those two agents are also reachable here through the registry.
+
+function cmdList() {
+  const pad = (s, n) => String(s).padEnd(n);
+  process.stdout.write(`Weftens registry — ${REGISTRY.length} agents (${dispatchableAgents().length} dispatchable at the door)\n\n`);
+  process.stdout.write(`${pad("AGENT", 18)}${pad("TIER", 6)}${pad("TEAM", 12)}${pad("CORE", 6)}OWNED-BY\n`);
+  for (const a of REGISTRY) {
+    const owned = a.ownedBy ?? (a.leads ? `(leads ${a.leads})` : "-");
+    process.stdout.write(`${pad(a.name, 18)}${pad(a.tier, 6)}${pad(a.team, 12)}${pad(a.core ? "yes" : "-", 6)}${owned}\n`);
+  }
+}
+
+async function cmdSend(args, { routeOnly } = {}) {
+  const rest = [];
+  let inputFile = null, provider = null, org = null, website = null, asJson = false;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--input") inputFile = args[++i] ?? null;
+    else if (args[i] === "--provider") provider = args[++i] ?? null;
+    else if (args[i] === "--json") asJson = true;
+    else if (args[i] === "--org") org = args[++i] ?? null;
+    else if (args[i] === "--website") website = args[++i] ?? null;
+    else rest.push(args[i]);
+  }
+  const firstIsAgent = rest.length >= 1 && REGISTRY.some((a) => a.name === rest[0].toLowerCase());
+  const request = firstIsAgent
+    ? { agent: rest[0], text: rest.slice(1).join(" ") }
+    : { text: rest.join(" ") };
+  if (!request.text && !request.agent) {
+    process.stderr.write('usage: weftens send "<request>"  |  weftens send <agent> "<request>"\n');
+    process.exitCode = 1;
+    return;
+  }
+  const decision = route(request);
+  if (!decision.agent) {
+    process.stdout.write(`→ (no route) — ${decision.reason}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`→ ${decision.agent.name}  [${decision.reason}]${decision.confident ? "" : "  (low confidence)"}\n`);
+  if (decision.alternatives?.length) {
+    process.stdout.write(`  also considered: ${decision.alternatives.map((x) => `${x.name}(${x.score})`).join(", ")}\n`);
+  }
+  if (routeOnly) return;
+
+  // Richy and PIO are specialist legs: they answer about an ORGANIZATION, not about a
+  // bare sentence, so they run through orchestrate() rather than as leaf agents. They
+  // used to refuse here with a note about "wire contracts" — true internally, useless
+  // to the person typing, and wrong in effect: the legs are reachable (with fixture
+  // clients when unconfigured), so refusing categorically made the two headline seats
+  // look dead. Now `send richy --org NAME "<question>"` does the real thing.
+  if (decision.agent.tier === 1 && decision.agent.wire) {
+    // An org is genuinely required — Richy audits a specific organization, PIO reports on one —
+    // but demanding a FLAG for it is a door that doesn't open for a plain sentence. Whoever is
+    // running this almost always means the same org every time, so it's config, not an argument:
+    // set WEFTENS_ORG once and `send richy "audit our listings"` just works.
+    org = org ?? process.env.WEFTENS_ORG ?? null;
+    website = website ?? process.env.WEFTENS_WEBSITE ?? null;
+    if (!org) {
+      process.stdout.write(
+        `\n[orchestrator] ${decision.agent.name} answers about a specific organization — which one?\n` +
+        `  once:    weftens send ${decision.agent.name} --org "Acme Co" [--website acme.com] "${request.text || "your question"}"\n` +
+        `  always:  set WEFTENS_ORG="Acme Co" (and optionally WEFTENS_WEBSITE) — then this command works as typed\n`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const intent = decision.agent.name === "richy" ? "representation" : "operations";
+    const result = await orchestrate(
+      { org: { name: org, ...(website ? { website } : {}) }, intent, question: request.text || undefined },
+      buildAgents()
+    );
+    process.stdout.write(`\n[orchestrator] ran ${decision.agent.name} over ${org} (intent: ${intent})\n`);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  const outcome = await invoke(decision.agent, { text: request.text, inputFile, provider });
+  process.stdout.write(`\n[${outcome.path}] ${outcome.note}\n`);
+  if (outcome.result !== undefined) {
+    // A change sheet renders for a human by default — the whole point of one is that a
+    // person can read a line and decide. `--json` returns the raw object for piping.
+    if (!asJson && isChangeSheet(outcome.result)) {
+      process.stdout.write(`\n${formatChangeSheet(outcome.result)}\n`);
+    } else {
+      process.stdout.write(`\n--- result ---\n${typeof outcome.result === "string" ? outcome.result : JSON.stringify(outcome.result, null, 2)}\n`);
+    }
+  }
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "ask") return cmdAsk(args);
+  if (command === "chat") return cmdChat(args);
+  if (command === "list" || command === "--list") return cmdList();
+  if (command === "send") return cmdSend(args);
+  if (command === "--route") return cmdSend(args, { routeOnly: true });
+  if (command === "route" || (command && (command === "-" || command.endsWith(".json")))) {
+    return cmdRoute(command === "route" ? args[0] : command);
+  }
+  process.stderr.write("usage: weftens ask|chat|list|send|--route|route …\n");
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  process.stderr.write(`weftens: ${error?.message ?? error}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weftens",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Weftens \u2014 one front door that routes a marketing/representation request to the right agent and runs it on your own AI subscription (bring-your-own-model). Usable as a CLI or an SDK.",
   "main": "index.js",

package/src/format.js

@@ -0,0 +1,66 @@
+// Human-readable rendering of an auditor's change sheet.
+//
+// The auditors always emitted correct JSON, and JSON is the right thing for a program to
+// consume — but it is the wrong thing to put in front of the person deciding whether to
+// act. The whole value of a change sheet is that a human can read one line and know what
+// to do, why, and what it costs to be wrong; a wall of braces hides exactly that. So the
+// CLI renders by default and `--json` returns the raw object for piping.
+//
+// Deliberately plain text: no colour, no box-drawing, no spinners. This output gets pasted
+// into an email to a client or a ticket, and it has to survive being pasted.
+
+const money = (n) =>
+  typeof n === "number" && Number.isFinite(n)
+    ? "$" + n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+    : null;
+
+/**
+ * True when a result looks like an auditor change sheet (rather than, say, a model answer
+ * or an orchestrator payload). Kept structural rather than name-based so a new core gets
+ * the rendering for free.
+ */
+export function isChangeSheet(result) {
+  return Boolean(result && typeof result === "object" && Array.isArray(result.changes));
+}
+
+/**
+ * Render a change sheet as plain text. Never invents a field: anything missing is simply
+ * not printed, so a core that doesn't produce risk/evidence still renders cleanly.
+ */
+export function formatChangeSheet(result) {
+  const out = [];
+  const changes = result.changes ?? [];
+
+  const flagged = money(result.wastedSpendRecoverable);
+  const header = [`${changes.length} proposed change${changes.length === 1 ? "" : "s"}`];
+  // "flagged", not "recoverable": the tool measured spend against a threshold, it did not
+  // establish that the money comes back. Some flagged terms convert — see the risk line.
+  if (flagged) header.push(`${flagged} of spend flagged`);
+  out.push(header.join("  |  "));
+
+  const a = result.account;
+  if (a) {
+    const bits = [];
+    if (typeof a.totalCost === "number") bits.push(`spend ${money(a.totalCost)}`);
+    if (typeof a.totalClicks === "number") bits.push(`${a.totalClicks} clicks`);
+    if (typeof a.totalConversions === "number") bits.push(`${a.totalConversions} conversions`);
+    if (typeof a.accountCPA === "number") bits.push(`CPA ${money(a.accountCPA)}`);
+    if (bits.length) out.push(`account: ${bits.join(", ")}`);
+  }
+  out.push("");
+
+  for (const c of changes) {
+    const amount = money(c.dollars);
+    out.push(`${c.rank ?? "-"}. ${c.change}${amount ? `   ${amount}` : ""}`);
+    if (c.where) out.push(`   where  ${c.where}`);
+    if (c.why) out.push(`   why    ${c.why}`);
+    if (c.expectedEffect) out.push(`   effect ${c.expectedEffect}`);
+    if (c.risk) out.push(`   risk   ${c.risk}`);
+    out.push("");
+  }
+
+  if (result.proposeOnly) {
+    out.push("Proposals only — nothing was sent to your ad account. Apply what you agree with.");
+  }
+  return out.join("\n");
+}