weftens 0.1.1 → 0.1.2

package/bin/weftens.js

@@ -17,44 +17,20 @@ 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 { 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";
 
-// 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]]));
-}
-
+// 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() {
-  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 };
+  return buildSpecialistClients({
+    onFixture: (names) =>
+      process.stderr.write(`weftens: ${names.join(" and ")} not configured — using clearly-flagged sample data
+`),
+  });
 }
 
 function parseFlags(args) {
@@ -169,39 +145,10 @@ async function cmdSend(args, { routeOnly } = {}) {
   }
   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 });
+  // 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
@@ -211,7 +158,13 @@ async function cmdSend(args, { routeOnly } = {}) {
     } 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() {

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.1",
+  "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

@@ -1,66 +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.
-
-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");
-}
+// 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 };
+}