weftens 0.1.0 → 0.1.2

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,187 @@
-#!/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 { buildSpecialistClients } from "../src/specialists.js";
+import { route } from "../src/agent-router.js";
+import { invoke } from "../src/invoke.js";
+import { REGISTRY, dispatchableAgents } from "../src/registry.js";
+
+// Client construction lives in src/specialists.js so the CLI and the SDK build them the
+// same way. The CLI adds one thing: a stderr warning when a specialist falls back to
+// sample data, so the person watching knows before they read a number.
+function buildAgents() {
+  return buildSpecialistClients({
+    onFixture: (names) =>
+      process.stderr.write(`weftens: ${names.join(" and ")} not configured — using clearly-flagged sample data
+`),
+  });
+}
+
+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;
+
+  // Specialist handling (org resolution, intent mapping, orchestrate) lives in invoke() so
+  // the CLI and the SDK cannot disagree about what invoking richy does. This used to be a
+  // second copy here, and the SDK regressed against it.
+  const outcome = await invoke(decision.agent, { text: request.text, inputFile, provider, org, website });
+  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`);
+    }
+    return;
+  }
+
+  // No result means the run produced nothing usable — a missing input file, a provider CLI
+  // that isn't installed, a specialist with no org. All of those exited 0 before, which made
+  // the tool unscriptable and made the fresh-clone CI step incapable of failing.
+  process.exitCode = 1;
+}
+
+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/index.js

@@ -1,32 +1,40 @@
-// Weftens SDK — the programmatic front door. The same deterministic routing and invoke
-// the CLI uses, exposed as an importable API so Weftens can be embedded in other code.
-//
-//   import { weftens, route, invoke, REGISTRY } from "weftens";
-//
-//   // one call: route a request and run the chosen agent
-//   const { decision, outcome } = await weftens("audit our facebook ads", { inputFile: "meta.csv" });
-//
-//   // or drive the pieces yourself
-//   const decision = route({ text: "who are the funders for this grant" });
-//   const outcome  = await invoke(decision.agent, { text: "..." });
-
-import { route } from "./src/agent-router.js";
-import { invoke } from "./src/invoke.js";
-import { REGISTRY, agentByName, dispatchableAgents } from "./src/registry.js";
-import { complete, loadProviders } from "./src/provider.js";
-
-export { route, invoke, REGISTRY, agentByName, dispatchableAgents, complete, loadProviders };
-
-/**
- * Route a request and run the chosen agent — the one-call front door.
- * @param request  a string (free text) or { text?, agent? } (agent = direct address)
- * @param opts     { inputFile?, provider?, dry? } — passed through to invoke
- * @returns { decision, outcome }  outcome is null when nothing routed
- */
-export async function weftens(request, opts = {}) {
-  const req = typeof request === "string" ? { text: request } : request;
-  const decision = route(req);
-  if (!decision.agent) return { decision, outcome: null };
-  const outcome = await invoke(decision.agent, { text: req.text, ...opts });
-  return { decision, outcome };
-}
+// Weftens SDK — the programmatic front door. The same deterministic routing and invoke
+// the CLI uses, exposed as an importable API so Weftens can be embedded in other code.
+//
+//   import { weftens, route, invoke, REGISTRY } from "weftens";
+//
+//   // one call: route a request and run the chosen agent
+//   const { decision, outcome } = await weftens("audit our facebook ads", { inputFile: "meta.csv" });
+//
+//   // or drive the pieces yourself
+//   const decision = route({ text: "who are the funders for this grant" });
+//   const outcome  = await invoke(decision.agent, { text: "..." });
+
+import { route } from "./src/agent-router.js";
+import { invoke } from "./src/invoke.js";
+import { REGISTRY, agentByName, dispatchableAgents } from "./src/registry.js";
+import { complete, loadProviders } from "./src/provider.js";
+import { isChangeSheet, formatChangeSheet } from "./src/format.js";
+import { buildSpecialistClients } from "./src/specialists.js";
+
+export {
+  route, invoke, REGISTRY, agentByName, dispatchableAgents, complete, loadProviders,
+  // The renderer is part of the product, not a CLI detail: an SDK consumer gets the same
+  // human-readable change sheet the terminal shows, instead of having to build one.
+  isChangeSheet, formatChangeSheet,
+  buildSpecialistClients,
+};
+
+/**
+ * Route a request and run the chosen agent — the one-call front door.
+ * @param request  a string (free text) or { text?, agent? } (agent = direct address)
+ * @param opts     { inputFile?, provider?, dry?, org?, website? } — passed through to invoke
+ * @returns { decision, outcome }  outcome is null when nothing routed
+ */
+export async function weftens(request, opts = {}) {
+  const req = typeof request === "string" ? { text: request } : request;
+  const decision = route(req);
+  if (!decision.agent) return { decision, outcome: null };
+  const outcome = await invoke(decision.agent, { text: req.text, ...opts });
+  return { decision, outcome };
+}

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "weftens",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
   "exports": {
     ".": "./index.js",
-    "./cli": "./bin/weftens.js"
+    "./cli": "./bin/weftens.js",
+    "./package.json": "./package.json"
   },
   "bin": {
     "weftens": "bin/weftens.js"
   },
   "license": "MIT",
   "files": [
+    "scripts",
     "bin",
     "src",
     "agents",
@@ -26,11 +28,11 @@
   "scripts": {
     "test": "npm run test:unit && npm run test:cores",
     "test:unit": "vitest run",
-    "test:cores": "node --test \"agent-cores/**/test/*.test.mjs\" \"agent-cores/**/test/*.test.js\"",
+    "test:cores": "node scripts/run-core-tests.mjs",
     "start": "node bin/weftens.js"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/scripts/run-core-tests.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Runs the agent-cores test files under Node's built-in runner.
+//
+// Why this exists rather than `node --test "agent-cores/**/test/*.test.mjs"`: glob expansion
+// inside `node --test` needs Node 21+, and this package supports Node 20. Passing an explicit
+// file list works everywhere, so the supported range in package.json is a claim CI can
+// actually check rather than an aspiration.
+//
+// The cores are deliberately zero-dependency and run under `node --test` (not vitest) so a
+// single auditor can be handed to someone who has nothing but Node installed. Keep it that way.
+
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CORES = join(ROOT, "agent-cores");
+
+function findTests(dir, found = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return found; // a missing agent-cores/ is a packaging problem, reported below, not a crash here
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === "node_modules") continue;
+      findTests(full, found);
+    } else if (/\.test\.m?js$/.test(e.name)) {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+const files = findTests(CORES).sort();
+
+if (files.length === 0) {
+  // Silence here would be indistinguishable from "all core tests passed" — exactly the failure
+  // this repo already shipped once: a green check over a step that could not fail.
+  console.error(`No core test files found under ${CORES}. Expected at least one.`);
+  process.exit(1);
+}
+
+console.log(`Running ${files.length} core test files under node --test`);
+const result = spawnSync(process.execPath, ["--test", ...files], { stdio: "inherit", cwd: ROOT });
+process.exit(result.status ?? 1);

package/src/agent-router.js

@@ -41,14 +41,21 @@ function hintRegex(hint) {
 //   "we need people ops"     -> pio     (matched: people)
 // They still count, at a third of a point, so a request with real signal alongside them
 // routes as before — but a lone weak hit can no longer clear the confidence floor.
+// Only words that (a) are actually declared as a hint by some agent and (b) carry almost no
+// meaning alone in ordinary English. Five entries here previously matched nothing in the
+// registry at all — proof the list had been written from intuition about English rather than
+// from the data it operates on. `registry-invariants.test.js` now fails if that recurs.
 const WEAK_HINTS = new Set([
   "site", "online", "listing", "people", "post", "content", "brief", "topic", "entity",
-  "profile", "record", "page", "search", "report", "data", "review",
 ]);
 
-// A route must earn at least this much to be dispatched confidently. One ordinary hint
-// (1) clears it; one weak hint (0.34) does not; two weak hints do.
+// A route must earn at least this much to dispatch. One ordinary hint (1) clears it; a lone
+// weak hint (0.5) does not; two weak hits (1.0) do. The old value was 0.34, which meant it
+// silently took THREE weak hits — and the comment claimed two. The constant was tuned until
+// two adversarial strings failed rather than derived from the rule, and it cost real requests:
+// "review the site" was refused.
 const CONFIDENCE_FLOOR = 1;
+const WEAK_WEIGHT = 0.5;
 
 // Longer (multi-word) hints weigh more — "made for advertising" is a far stronger
 // signal than a bare "seo" — so specific phrases beat generic single words.
@@ -59,7 +66,7 @@ function scoreAgent(agent, text) {
   for (const hint of agent.routeHints) {
     if (hintRegex(hint).test(text)) {
       if (hint.includes(" ")) { matched.push(hint); score += 3; }
-      else if (WEAK_HINTS.has(hint)) { weak.push(hint); score += 0.34; }
+      else if (WEAK_HINTS.has(hint)) { weak.push(hint); score += WEAK_WEIGHT; }
       else { matched.push(hint); score += 1; }
     }
   }
@@ -121,4 +128,4 @@ export function route(request = {}) {
   };
 }
 
-export { REGISTRY };
+export { REGISTRY, WEAK_HINTS };

package/src/format.js

@@ -0,0 +1,90 @@
+// 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.
+
+// Currency comes from the report, not from an assumption. Ad exports are denominated in
+// whatever the account uses; hardcoding "$" renders a GBP account as dollars, which is a
+// wrong number on a page whose whole job is numbers. With no currency declared, print the
+// bare amount rather than assert one.
+const money = (n, currency) => {
+  if (typeof n !== "number" || !Number.isFinite(n)) return null;
+  const opts = currency
+    ? { style: "currency", currency, minimumFractionDigits: 2, maximumFractionDigits: 2 }
+    : { minimumFractionDigits: 2, maximumFractionDigits: 2 };
+  try {
+    return n.toLocaleString("en-US", opts);
+  } catch {
+    // An unrecognised currency code must not take down the render.
+    return n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+  }
+};
+
+/**
+ * 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) {
+  // Defensive by design: this is the last thing before the user's terminal, and everything
+  // upstream of it (tryCore, the clients, complete) fails soft with a plain note. A
+  // malformed core payload must degrade, never throw a stack trace at someone auditing an
+  // ad account.
+  if (!isChangeSheet(result)) return "";
+  const out = [];
+  const currency = typeof result.currency === "string" ? result.currency : null;
+  const changes = result.changes.filter((c) => c && typeof c === "object");
+  const dropped = result.changes.length - changes.length;
+
+  const flagged = money(result.wastedSpendRecoverable, currency);
+  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 && typeof result.account === "object" ? result.account : null;
+  if (a) {
+    const bits = [];
+    if (typeof a.totalCost === "number") bits.push(`spend ${money(a.totalCost, currency)}`);
+    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, currency)}`);
+    if (bits.length) out.push(`account: ${bits.join(", ")}`);
+  }
+  out.push("");
+
+  for (const c of changes) {
+    const amount = money(c.dollars, currency);
+    // A core that doesn't describe its change has nothing worth rendering as a headline;
+    // say so rather than printing "[object Object]".
+    const label = typeof c.change === "string" && c.change.trim() ? c.change : "(change not described)";
+    out.push(`${c.rank ?? "-"}. ${label}${amount ? `   ${amount}` : ""}`);
+    const line = (tag, v) => { if (typeof v === "string" && v.trim()) out.push(`   ${tag} ${v}`); };
+    line("where ", c.where);
+    line("why   ", c.why);
+    line("effect", c.expectedEffect);
+    line("risk  ", c.risk);
+    out.push("");
+  }
+
+  if (dropped > 0) out.push(`(${dropped} malformed entr${dropped === 1 ? "y" : "ies"} skipped)`, "");
+  if (result.proposeOnly) {
+    out.push("Proposals only — nothing was sent to your ad account. Apply what you agree with.");
+  }
+  return out.join("\n");
+}

package/src/invoke.js

@@ -60,10 +60,35 @@ async function tryCore(agent, inputFile) {
 export async function invoke(agent, opts = {}) {
   if (!agent) return { agent: null, path: "none", note: "no agent to invoke" };
 
+  // Specialist legs (richy, pio) answer about an ORGANIZATION, so they run through
+  // orchestrate() rather than as leaf agents. This used to return a note saying so and
+  // stop — which meant the CLI (which had its own copy of this logic) did the real work
+  // while the SDK returned a dead end for the same call. One implementation, both doors.
   if (agent.tier === 1 && agent.wire) {
+    const org = opts.org ?? process.env.WEFTENS_ORG ?? null;
+    const website = opts.website ?? process.env.WEFTENS_WEBSITE ?? null;
+    if (!org) {
+      return {
+        agent: agent.name, path: "orchestrator", needs: "org",
+        note: `${agent.name} answers about a specific organization — pass an org.
+` +
+              `  once:    weftens send ${agent.name} --org "Acme Co" [--website acme.com] "<question>"
+` +
+              `  always:  set WEFTENS_ORG="Acme Co" (and optionally WEFTENS_WEBSITE)
+` +
+              `  SDK:     weftens("<question>", { org: "Acme Co" })`,
+      };
+    }
+    const { orchestrate } = await import("./weftens.js");
+    const { buildSpecialistClients } = await import("./specialists.js");
+    const intent = agent.name === "richy" ? "representation" : "operations";
+    const result = await orchestrate(
+      { org: { name: org, ...(website ? { website } : {}) }, intent, question: opts.text || undefined },
+      opts.agents ?? buildSpecialistClients()
+    );
     return {
-      agent: agent.name, path: "orchestrator",
-      note: `${agent.name} runs through the Weftens orchestrator over its wire contract (use the orchestrate() path); not invoked as a leaf`,
+      agent: agent.name, path: "orchestrator", result,
+      note: `ran ${agent.name} over ${org} (intent: ${intent})`,
     };
   }
 

package/src/registry.js

@@ -1,160 +1,163 @@
-// The Weftens agent registry — the single source of truth for which agents exist and
-// how a request finds one.
-//
-// Routing is deterministic and explainable (see agent-router.js): a request matches an
-// agent by its declared routeHints, and you can always see which hints matched. No
-// model call is needed to route — the model only runs when an agent is invoked to
-// produce, so the routing layer is verifiable with no API key.
-//
-// Fields:
-//   tier      1 = lead that owns sub-agents (richy, pio, content); 2 = leaf. invoke()
-//             branches on this.
-//   core      path to a deterministic agent-cores package, or absent.
-//   coreBin,  how to shell that core's CLI (it does parse+analyze+format). Present only
-//   coreInputFlag  where wired; absent -> invoke reports the core isn't wired yet.
-//   leads     tier-1 content only: the pipeline it delegates to.
-//   wire      tier-1 richy/pio only: they answer through the existing orchestrator, not here.
-//   ownedBy   content-team seats owned by the Content lead — not dispatched by the door.
-//   seatFile  the .md seat used as the system prompt when a seat produces via the model.
-//   routeHints keyword/phrase signals for the router.
-//
-// Note: seo-technical+seo-content and amazon-ppc+paid-search map to single real job
-// postings, so they are merge candidates — but the merge is deferred until the roster
-// actually needs consolidating. Merging early only adds structure nothing reads yet.
-
-// One home: the agent seats live in this repo (weftens/agents). Override with
-// WEFTENS_AGENTS_DIR. No external directory and no fallback — one canonical location.
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const AGENTS_DIR = process.env.WEFTENS_AGENTS_DIR || join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
-const seat = (name) => join(AGENTS_DIR, `${name}.md`);
-
-export const REGISTRY = [
-  // ---- Tier 1: lead agents (own sub-agents / their own engines) ----
-  {
-    name: "richy", tier: 1, team: "weftens", wire: "representationCheck", seatFile: seat("richy"),
-    routeHints: ["represent", "representation", "reputation", "online", "website", "site",
-      "review", "listing", "search", "seo", "visibility", "audit", "appear",
-      "how do we look", "what do people see", "brand", "knowledge panel", "ai answer"],
-  },
-  {
-    name: "pio", tier: 1, team: "weftens", wire: "operationsSummary", seatFile: seat("pio"),
-    routeHints: ["event", "attendee", "participant", "check-in", "checkin", "roster",
-      "grant", "funding", "funder", "program", "people", "follow-up", "followup", "donor",
-      "prospect", "attendance", "registration", "operation", "who should i meet", "dossier",
-      // Bare "people" is too generic to dispatch on (it's a weak hint), but these PHRASES are
-      // unambiguous asks that a customer actually types. Without them, "we need people ops"
-      // matched only the weak "people" and fell through to no-route.
-      "people ops", "people operations", "ops help", "back office", "development ops",
-      "who funds", "funding pipeline", "grant research", "prospect research"],
-  },
-  {
-    name: "content", tier: 1, team: "content", leads: "content-org", seatFile: null,
-    routeHints: ["make content", "content", "script", "reel", "video", "caption", "post",
-      "series", "episode", "produce", "storyboard", "shot list"],
-  },
-
-  // ---- Tier 2: marketing/SEO leaves with deterministic agent-cores ----
-  {
-    name: "seo-technical", tier: 2, team: "seo", core: "agent-cores/seo-technical", seatFile: seat("seo-technical"),
-    routeHints: ["crawl", "index", "indexing", "render", "schema", "structured data",
-      "robots", "sitemap", "canonical", "core web vitals", "technical seo", "rich result"],
-  },
-  {
-    name: "seo-content", tier: 2, team: "seo", core: "agent-cores/seo-content", seatFile: seat("seo-content"),
-    routeHints: ["keyword", "topic", "entity", "content strategy", "brief",
-      "serp", "rankings", "answer surface", "citation", "gsc", "search console"],
-  },
-  {
-    // paid-search is the one core whose CLI takes a flag (--search-terms <csv>) rather
-    // than a positional file, so it overrides the positional default in invoke.
-    name: "paid-search", tier: 2, team: "marketing", core: "agent-cores/paid-search",
-    coreInputFlag: "--search-terms", seatFile: seat("paid-search"),
-    routeHints: ["google ads", "paid search", "ppc", "search terms", "negatives",
-      "bid", "budget", "impression share", "quality score", "change sheet"],
-  },
-  {
-    name: "amazon-ppc", tier: 2, team: "marketing", core: "agent-cores/amazon-ppc", seatFile: seat("amazon-ppc"),
-    routeHints: ["amazon", "amazon ads", "sponsored products", "acos", "tacos",
-      "harvest", "negate", "amazon search term", "sponsored brand"],
-  },
-  {
-    name: "meta-ads", tier: 2, team: "marketing", core: "agent-cores/meta-ads", seatFile: seat("meta-ads"),
-    routeHints: ["meta", "facebook", "instagram", "meta ads", "facebook ads", "instagram ads",
-      "ad set", "adset", "creative fatigue", "frequency", "roas", "ads manager"],
-  },
-  {
-    name: "supply-verify", tier: 2, team: "marketing", core: "agent-cores/supply-verify", seatFile: seat("supply-verify"),
-    routeHints: ["placement", "mfa", "made for advertising", "ivt", "invalid traffic",
-      "supply path", "log-level", "programmatic", "ad spend waste", "exclusion"],
-  },
-  {
-    name: "content-ops", tier: 2, team: "content", core: "agent-cores/content-ops", seatFile: seat("content-ops"),
-    routeHints: ["content inventory", "cms export", "keep update retire", "migration",
-      "content audit", "tagging", "metadata cleanup", "template conform"],
-  },
-
-  // ---- Tier 2: marketing/PR leaves (no deterministic core — model-only) ----
-  {
-    name: "social-voice", tier: 2, team: "marketing", seatFile: seat("social-voice"),
-    routeHints: ["social", "instagram", "tiktok", "linkedin", "reply", "engagement",
-      "calendar", "per-platform", "voice-locked", "community management"],
-  },
-  {
-    name: "claims-content", tier: 2, team: "content", seatFile: seat("claims-content"),
-    routeHints: ["health", "pharma", "finance", "supplement", "regulated", "claim",
-      "medical review", "legal review", "compliance", "substantiation"],
-  },
-  {
-    name: "growth-marketing", tier: 2, team: "marketing", seatFile: seat("growth-marketing"),
-    // "cro"/"funnel"/"activation" are the words a practitioner uses; the words a CUSTOMER
-    // uses for the same problem are "converts badly", "signups", "checkout". Without those
-    // the seat was unreachable by anyone describing their own problem in their own words.
-    routeHints: ["growth", "acquisition", "channel", "funnel", "cro", "lifecycle",
-      "campaign design", "experiment", "retention", "activation",
-      "convert", "converts", "conversion", "converting", "signup", "sign-up",
-      "checkout", "landing page", "drop off", "drop-off", "abandon", "onboarding"],
-  },
-  {
-    name: "security-writer", tier: 2, team: "security", seatFile: seat("security-writer"),
-    routeHints: ["security content", "technical writing", "security explainer",
-      "threat", "vulnerability writeup", "security training", "devsecops doc"],
-  },
-
-  // ---- Tier 2: evaluation leaves (agents whose job is judgment — normal pool) ----
-  {
-    name: "hilbert", tier: 2, team: "eval", seatFile: seat("hilbert"),
-    routeHints: ["headline", "tagline", "name", "slogan", "will this survive",
-      "memetic", "does this stop someone", "positioning line", "pitch line", "repeated"],
-  },
-  {
-    name: "lippmann", tier: 2, team: "eval", seatFile: seat("lippmann"),
-    routeHints: ["perception", "what do people believe", "public sources", "reputation read",
-      "how is x seen", "sentiment", "frame provenance", "before committing"],
-  },
-  {
-    name: "agent2060", tier: 2, team: "eval", seatFile: seat("agent2060"),
-    routeHints: ["foresight", "future", "durable", "will this last", "trend", "horizon",
-      "bet", "does this survive", "strategic call", "category"],
-  },
-
-  // ---- Tier 2: content-team seats, owned by the Content lead (not dispatched by the door) ----
-  ...["content-strategy", "ideator", "researcher", "writer", "script-editor",
-    "showrunner", "video-editor", "feed-optimizer", "disclosure-qc", "growth-analyst"]
-    .map((name) => ({
-      name, tier: 2, team: "content", seatFile: seat(name), ownedBy: "content",
-      routeHints: [name.replace(/-/g, " ")],
-    })),
-];
-
-export function agentByName(name) {
-  const key = String(name).toLowerCase().trim();
-  return REGISTRY.find((a) => a.name === key) ?? null;
-}
-
-// Agents the front door auto-dispatches over — everything except the content-team
-// seats the Content lead owns (the door routes to `content`, which owns those).
-export function dispatchableAgents() {
-  return REGISTRY.filter((a) => !a.ownedBy);
-}
+// The Weftens agent registry — the single source of truth for which agents exist and
+// how a request finds one.
+//
+// Routing is deterministic and explainable (see agent-router.js): a request matches an
+// agent by its declared routeHints, and you can always see which hints matched. No
+// model call is needed to route — the model only runs when an agent is invoked to
+// produce, so the routing layer is verifiable with no API key.
+//
+// Fields:
+//   tier      1 = lead that owns sub-agents (richy, pio, content); 2 = leaf. invoke()
+//             branches on this.
+//   core      path to a deterministic agent-cores package, or absent.
+//   coreBin,  how to shell that core's CLI (it does parse+analyze+format). Present only
+//   coreInputFlag  where wired; absent -> invoke reports the core isn't wired yet.
+//   leads     tier-1 content only: the pipeline it delegates to.
+//   wire      tier-1 richy/pio only: they answer through the existing orchestrator, not here.
+//   ownedBy   content-team seats owned by the Content lead — not dispatched by the door.
+//   seatFile  the .md seat used as the system prompt when a seat produces via the model.
+//   routeHints keyword/phrase signals for the router.
+//
+// Note: seo-technical+seo-content and amazon-ppc+paid-search map to single real job
+// postings, so they are merge candidates — but the merge is deferred until the roster
+// actually needs consolidating. Merging early only adds structure nothing reads yet.
+
+// One home: the agent seats live in this repo (weftens/agents). Override with
+// WEFTENS_AGENTS_DIR. No external directory and no fallback — one canonical location.
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const AGENTS_DIR = process.env.WEFTENS_AGENTS_DIR || join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
+const seat = (name) => join(AGENTS_DIR, `${name}.md`);
+
+export const REGISTRY = [
+  // ---- Tier 1: lead agents (own sub-agents / their own engines) ----
+  {
+    name: "richy", tier: 1, team: "weftens", wire: "representationCheck", seatFile: seat("richy"),
+    routeHints: ["represent", "representation", "reputation", "online", "website", "site",
+      "review", "listing", "search", "seo", "visibility", "audit", "appear",
+      "how do we look", "what do people see", "brand", "knowledge panel", "ai answer"],
+  },
+  {
+    name: "pio", tier: 1, team: "weftens", wire: "operationsSummary", seatFile: seat("pio"),
+    routeHints: ["event", "attendee", "participant", "check-in", "checkin", "roster",
+      "grant", "funding", "funder", "program", "people", "follow-up", "followup", "donor",
+      "prospect", "attendance", "registration", "operation", "who should i meet", "dossier",
+      // Bare "people" is too generic to dispatch on (it's a weak hint), but these PHRASES are
+      // unambiguous asks that a customer actually types. Without them, "we need people ops"
+      // matched only the weak "people" and fell through to no-route.
+      "people ops", "people operations", "ops help", "back office", "development ops",
+      "who funds", "funding pipeline", "grant research", "prospect research"],
+  },
+  {
+    name: "content", tier: 1, team: "content", leads: "content-org", seatFile: null,
+    routeHints: ["make content", "content", "script", "reel", "video", "caption", "post",
+      "series", "episode", "produce", "storyboard", "shot list"],
+  },
+
+  // ---- Tier 2: marketing/SEO leaves with deterministic agent-cores ----
+  {
+    name: "seo-technical", tier: 2, team: "seo", core: "agent-cores/seo-technical", seatFile: seat("seo-technical"),
+    routeHints: ["crawl", "index", "indexing", "render", "schema", "structured data",
+      "robots", "sitemap", "canonical", "core web vitals", "technical seo", "rich result"],
+  },
+  {
+    name: "seo-content", tier: 2, team: "seo", core: "agent-cores/seo-content", seatFile: seat("seo-content"),
+    routeHints: ["keyword", "topic", "entity", "content strategy", "brief",
+      "serp", "rankings", "answer surface", "citation", "gsc", "search console"],
+  },
+  {
+    // paid-search is the one core whose CLI takes a flag (--search-terms <csv>) rather
+    // than a positional file, so it overrides the positional default in invoke.
+    name: "paid-search", tier: 2, team: "marketing", core: "agent-cores/paid-search",
+    coreInputFlag: "--search-terms", seatFile: seat("paid-search"),
+    routeHints: ["google ads", "paid search", "ppc", "search terms", "negatives",
+      "bid", "budget", "impression share", "quality score", "change sheet"],
+  },
+  {
+    name: "amazon-ppc", tier: 2, team: "marketing", core: "agent-cores/amazon-ppc", seatFile: seat("amazon-ppc"),
+    routeHints: ["amazon", "amazon ads", "sponsored products", "acos", "tacos",
+      "harvest", "negate", "amazon search term", "sponsored brand"],
+  },
+  {
+    name: "meta-ads", tier: 2, team: "marketing", core: "agent-cores/meta-ads", seatFile: seat("meta-ads"),
+    // No bare "instagram": the platform name is not an intent, and social-voice (organic)
+    // wants the same word. A permanent tie routes by scoring accident, so both sides carry
+    // the phrase that says which job is being asked for.
+    routeHints: ["meta", "facebook", "meta ads", "facebook ads", "instagram ads",
+      "ad set", "adset", "creative fatigue", "frequency", "roas", "ads manager"],
+  },
+  {
+    name: "supply-verify", tier: 2, team: "marketing", core: "agent-cores/supply-verify", seatFile: seat("supply-verify"),
+    routeHints: ["placement", "mfa", "made for advertising", "ivt", "invalid traffic",
+      "supply path", "log-level", "programmatic", "ad spend waste", "exclusion"],
+  },
+  {
+    name: "content-ops", tier: 2, team: "content", core: "agent-cores/content-ops", seatFile: seat("content-ops"),
+    routeHints: ["content inventory", "cms export", "keep update retire", "migration",
+      "content audit", "tagging", "metadata cleanup", "template conform"],
+  },
+
+  // ---- Tier 2: marketing/PR leaves (no deterministic core — model-only) ----
+  {
+    name: "social-voice", tier: 2, team: "marketing", seatFile: seat("social-voice"),
+    routeHints: ["social", "instagram post", "post on instagram", "tiktok", "linkedin", "reply", "engagement",
+      "calendar", "per-platform", "voice-locked", "community management"],
+  },
+  {
+    name: "claims-content", tier: 2, team: "content", seatFile: seat("claims-content"),
+    routeHints: ["health", "pharma", "finance", "supplement", "regulated", "claim",
+      "medical review", "legal review", "compliance", "substantiation"],
+  },
+  {
+    name: "growth-marketing", tier: 2, team: "marketing", seatFile: seat("growth-marketing"),
+    // "cro"/"funnel"/"activation" are the words a practitioner uses; the words a CUSTOMER
+    // uses for the same problem are "converts badly", "signups", "checkout". Without those
+    // the seat was unreachable by anyone describing their own problem in their own words.
+    routeHints: ["growth", "acquisition", "channel", "funnel", "cro", "lifecycle",
+      "campaign design", "experiment", "retention", "activation",
+      "convert", "converts", "conversion", "converting", "signup", "sign-up",
+      "checkout", "landing page", "drop off", "drop-off", "abandon", "onboarding"],
+  },
+  {
+    name: "security-writer", tier: 2, team: "security", seatFile: seat("security-writer"),
+    routeHints: ["security content", "technical writing", "security explainer",
+      "threat", "vulnerability writeup", "security training", "devsecops doc"],
+  },
+
+  // ---- Tier 2: evaluation leaves (agents whose job is judgment — normal pool) ----
+  {
+    name: "hilbert", tier: 2, team: "eval", seatFile: seat("hilbert"),
+    routeHints: ["headline", "tagline", "name", "slogan", "will this survive",
+      "memetic", "does this stop someone", "positioning line", "pitch line", "repeated"],
+  },
+  {
+    name: "lippmann", tier: 2, team: "eval", seatFile: seat("lippmann"),
+    routeHints: ["perception", "what do people believe", "public sources", "reputation read",
+      "how is x seen", "sentiment", "frame provenance", "before committing"],
+  },
+  {
+    name: "agent2060", tier: 2, team: "eval", seatFile: seat("agent2060"),
+    routeHints: ["foresight", "future", "durable", "will this last", "trend", "horizon",
+      "bet", "does this survive", "strategic call", "category"],
+  },
+
+  // ---- Tier 2: content-team seats, owned by the Content lead (not dispatched by the door) ----
+  ...["content-strategy", "ideator", "researcher", "writer", "script-editor",
+    "showrunner", "video-editor", "feed-optimizer", "disclosure-qc", "growth-analyst"]
+    .map((name) => ({
+      name, tier: 2, team: "content", seatFile: seat(name), ownedBy: "content",
+      routeHints: [name.replace(/-/g, " ")],
+    })),
+];
+
+export function agentByName(name) {
+  const key = String(name).toLowerCase().trim();
+  return REGISTRY.find((a) => a.name === key) ?? null;
+}
+
+// Agents the front door auto-dispatches over — everything except the content-team
+// seats the Content lead owns (the door routes to `content`, which owns those).
+export function dispatchableAgents() {
+  return REGISTRY.filter((a) => !a.ownedBy);
+}

package/src/specialists.js

@@ -0,0 +1,50 @@
+// Building the specialist clients (Richy, PIO) from the environment.
+//
+// This lived in bin/weftens.js, which meant the CLI could reach live specialist services
+// and the SDK could not — the same call did different things depending on which door you
+// came through. It belongs in src/ so both surfaces share one implementation.
+//
+// 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 were looking at their own organization.
+
+import { RichyClient, FixtureRichyClient } from "./richy-client.js";
+import { PioClient, FixturePioClient } from "./pio-client.js";
+
+function envGroup(label, names, env) {
+  const set = names.filter((n) => env[n]);
+  if (set.length === 0) return null;
+  if (set.length < names.length) {
+    const missing = names.filter((n) => !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, env[n]]));
+}
+
+/**
+ * @param opts { env?, onFixture? } — onFixture is called with the names of the specialists
+ *             falling back to sample data, so a CLI can warn on stderr and a library can stay quiet.
+ * @returns { richy, pio } clients — real when configured, clearly-flagged fixtures otherwise.
+ */
+export function buildSpecialistClients({ env = process.env, onFixture } = {}) {
+  const richyEnv = envGroup("Richy", ["WEFTENS_RICHY_URL", "WEFTENS_RICHY_KEY"], env);
+  const pioEnv = envGroup("PIO", ["WEFTENS_PIO_URL", "WEFTENS_PIO_MEMBER", "WEFTENS_PIO_PASSWORD"], env);
+
+  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: env.WEFTENS_PIO_TENANT ?? null,
+      })
+    : new FixturePioClient();
+
+  const fixtures = [!richyEnv && "Richy", !pioEnv && "PIO"].filter(Boolean);
+  if (fixtures.length > 0 && typeof onFixture === "function") onFixture(fixtures);
+  return { richy, pio };
+}