weftens 0.0.1 → 0.1.0

package/src/pio-client.js

@@ -0,0 +1,142 @@
+// PIO leg — wired for real. PIO's data plane is tenant-scoped behind a member
+// session (grantengine_session cookie). Weftens authenticates as a member, reads
+// PIO's sanitized /dashboard (which is PII-free by construction — counts and
+// status only, never participant names/contacts), and returns an operations
+// summary for the org. The summary is scoped to the PIO profile whose display name
+// matches the org; if none matches, it reports "not found" plus the names that do
+// exist — never another organization's counts under the requested name.
+//
+// Credentials belong to a real PIO member the operator provisions for Weftens —
+// this reads on their behalf, it does not bootstrap tenants or hold the operator
+// token. Local PIO needs no tenant; hosted PIO needs the tenant slug.
+
+import { requireSafeBaseUrl } from "./richy-client.js";
+
+export class PioError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PioError";
+  }
+}
+
+const SESSION_COOKIE = "grantengine_session";
+
+export class PioClient {
+  constructor({ baseUrl, member, password, tenant = null, fetchImpl = fetch } = {}) {
+    if (!baseUrl || !member || !password) throw new PioError("pio_not_configured");
+    // TLS required (loopback http allowed for local/test) — plain http to any other
+    // host would expose the member password and session cookie on the wire.
+    this.baseUrl = requireSafeBaseUrl(baseUrl, PioError);
+    this.member = member;
+    this.password = password;
+    this.tenant = tenant;
+    this.fetchImpl = fetchImpl;
+    this.cookie = null;
+  }
+
+  // A network-level failure (server down, DNS, reset) must surface as a PioError,
+  // not a raw TypeError — callers branch on PioError to render "PIO unavailable".
+  async _fetch(url, options) {
+    try {
+      return await this.fetchImpl(url, options);
+    } catch {
+      throw new PioError("pio_unreachable");
+    }
+  }
+
+  async _login() {
+    const body = { member: this.member, password: this.password };
+    if (this.tenant) body.tenant = this.tenant;
+    const res = await this._fetch(`${this.baseUrl}/session`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      redirect: "manual", // never follow a 3xx — it could carry creds to an attacker host
+    });
+    if (res.status >= 300 && res.status < 400) throw new PioError("pio_unexpected_redirect");
+    if (!res.ok) throw new PioError(res.status === 401 ? "pio_auth_failed" : "pio_unavailable");
+    const setCookie = res.headers.get("set-cookie") ?? "";
+    const match = setCookie.match(new RegExp(`${SESSION_COOKIE}=([^;]+)`));
+    if (!match) throw new PioError("pio_no_session");
+    this.cookie = `${SESSION_COOKIE}=${match[1]}`;
+  }
+
+  async _get(path) {
+    if (!this.cookie) await this._login();
+    const headers = { cookie: this.cookie };
+    if (this.tenant) headers["x-grantengine-tenant"] = this.tenant;
+    const res = await this._fetch(`${this.baseUrl}${path}`, { headers, redirect: "manual" });
+    if (res.status === 401) {
+      // Session expired mid-run: re-auth once, then fail if it still won't take.
+      this.cookie = null;
+      await this._login();
+      const retry = await this._fetch(`${this.baseUrl}${path}`, {
+        headers: { cookie: this.cookie, ...(this.tenant ? { "x-grantengine-tenant": this.tenant } : {}) },
+        redirect: "manual",
+      });
+      if (retry.status >= 300 && retry.status < 400) throw new PioError("pio_unexpected_redirect");
+      if (!retry.ok) throw new PioError("pio_unavailable");
+      return retry.json();
+    }
+    if (res.status >= 300 && res.status < 400) throw new PioError("pio_unexpected_redirect");
+    if (!res.ok) throw new PioError("pio_unavailable");
+    return res.json();
+  }
+
+  async operationsSummary({ name }) {
+    const dash = await this._get("/dashboard");
+    const profiles = Array.isArray(dash.profiles) ? dash.profiles : [];
+    const profile = profiles.find(
+      (p) => String(p.displayName ?? "").toLowerCase() === String(name).toLowerCase(),
+    );
+    // No profile by that name → say so, with the names that DO exist (org display
+    // names are org-level, not participant PII). Returning workspace-wide counts
+    // here attributed them to an org PIO has never heard of — "you're running 2
+    // events" built from other organizations' numbers. Misattribution, not data.
+    if (!profile) {
+      return {
+        org: name,
+        matchedProfile: null,
+        available: false,
+        reason: `no organization named "${name}" in this PIO workspace`,
+        knownOrganizations: profiles.map((p) => String(p.displayName ?? "")).filter(Boolean),
+      };
+    }
+    const pid = profile.profileId;
+    const countFor = (arr) => (Array.isArray(arr) ? arr : []).filter((x) => x.profileId === pid).length;
+    return {
+      org: name,
+      matchedProfile: profile.displayName,
+      scope: "this organization",
+      programs: countFor(dash.programs),
+      events: countFor(dash.programEvents),
+      participants: countFor(dash.participants),
+      attendance: countFor(dash.attendanceRecords),
+      followUps: countFor(dash.followUps),
+      representationChecks: countFor(dash.representationChecks),
+      available: true,
+      source: "PIO /dashboard (sanitized — counts and status only, no participant PII)",
+    };
+  }
+}
+
+// Deterministic, no-network. Realistic shape so tests exercise the merge, clearly
+// flagged sample:true so a Weftens result is never mistaken for real PIO data.
+export class FixturePioClient {
+  async operationsSummary({ name }) {
+    return {
+      org: name,
+      matchedProfile: name,
+      scope: "this organization",
+      programs: 2,
+      events: 3,
+      participants: 24,
+      attendance: 41,
+      followUps: 5,
+      representationChecks: 1,
+      available: true,
+      source: "sample",
+      sample: true,
+    };
+  }
+}

package/src/provider.js

@@ -0,0 +1,81 @@
+// Bring-your-own-model. A model-backed agent produces by shelling a CLI the user
+// already has and is logged into — their own subscription — so no API key is needed
+// and nobody is billed through Weftens. The user chooses which one.
+//
+// Providers are CONFIG, not code: a name -> { cmd, args } map. Adding or fixing one
+// (grok, gemini, a different flag) is a line, never a new adapter. Defaults cover the
+// known CLIs; override or extend them in a providers.json beside the repo, or point at
+// one with WEFTENS_PROVIDERS_FILE. Pick the active provider with WEFTENS_PROVIDER
+// (default: claude).
+//
+// The prompt is piped to the CLI's stdin (not passed as an argument): it avoids all
+// shell-quoting/injection problems with long prompts, and it lets us run through a shell
+// so a Windows npm shim (claude.cmd / .ps1) resolves — plain execFile can't call those.
+//
+// `claude` and `codex` are both VERIFIED end-to-end on this machine — a real prompt in, a
+// real answer out, through the user's own subscription. `gemini` and `grok` remain honest
+// defaults: correct in shape, unproven because those CLIs are not installed here. invoke.js
+// degrades to a plain note if a provider's CLI is missing or errors; it never fabricates a
+// model answer, so an unverified provider fails visibly rather than silently.
+
+import { exec } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const DEFAULT_PROVIDERS = {
+  claude: { cmd: "claude", args: ["-p"] },      // Claude Code — Pro/Max sub. VERIFIED end-to-end.
+  codex: { cmd: "codex", args: ["exec"] },      // OpenAI Codex CLI — ChatGPT sub. VERIFIED 2026-07-19.
+  gemini: { cmd: "gemini", args: ["-p"] },      // Google Gemini CLI. Unverified — CLI not present here.
+  grok: { cmd: "grok", args: [] },              // xAI grok CLI. Unverified — CLI not present here.
+};
+
+// Merge defaults with a user providers.json ({ providers: { name: {cmd,args} } }).
+export function loadProviders() {
+  const file = process.env.WEFTENS_PROVIDERS_FILE || join(HERE, "..", "providers.json");
+  if (!existsSync(file)) return { ...DEFAULT_PROVIDERS };
+  try {
+    const user = JSON.parse(readFileSync(file, "utf8"))?.providers ?? {};
+    return { ...DEFAULT_PROVIDERS, ...user };
+  } catch {
+    return { ...DEFAULT_PROVIDERS };
+  }
+}
+
+export function activeProviderName() {
+  return process.env.WEFTENS_PROVIDER || "claude";
+}
+
+/**
+ * Run the prompt through a provider's CLI and return its text.
+ * @param prompt  the full prompt (seat instructions + request)
+ * @param opts    { provider?, providers?, timeoutMs? }
+ * @returns Promise<{ ok, text?, provider, reason? }>  — never throws; ok:false carries the reason
+ */
+export function complete(prompt, opts = {}) {
+  const providers = opts.providers || loadProviders();
+  const name = opts.provider || activeProviderName();
+  const cfg = providers[name];
+  if (!cfg) return Promise.resolve({ ok: false, provider: name, reason: `unknown provider "${name}"` });
+
+  return new Promise((resolve) => {
+    // exec runs the command through a shell, so an npm shim (e.g. claude.cmd on Windows)
+    // resolves. cmd + args come from config we control (flags only), never user text; the
+    // prompt goes via stdin, so there is no injection surface from the request.
+    const command = [cfg.cmd, ...cfg.args].join(" ");
+    const child = exec(command, { maxBuffer: 16_000_000, timeout: opts.timeoutMs ?? 180_000 },
+      (err, stdout, stderr) => {
+        if (err) {
+          const missing = err.code === "ENOENT" || /not recognized|not found/i.test(stderr || "");
+          const reason = missing
+            ? `the "${cfg.cmd}" CLI isn't installed / on PATH — install it and log in, or pick another provider`
+            : (String(stderr).trim().split("\n")[0] || err.message);
+          return resolve({ ok: false, provider: name, reason });
+        }
+        resolve({ ok: true, provider: name, text: String(stdout).trim() });
+      });
+    child.stdin.end(prompt);
+  });
+}

package/src/registry.js

@@ -0,0 +1,160 @@
+// 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);
+}

package/src/richy-client.js

@@ -0,0 +1,216 @@
+// Richy leg. Calls Richy's read-only audit service (POST /audit + POST /represent,
+// gated by x-richy-key) and NORMALIZES the responses into the operator-relevant
+// shape the synthesizer needs — an overall score, the top fixes, and which presence
+// lanes are covered. It does not return raw audit JSON (that was the old lossy
+// mistake); it extracts the few fields that mean something to an operator, with a
+// request timeout and a response byte cap so a slow or oversized service can't hang
+// or balloon the caller. Fail-soft: one endpoint down still yields a usable read.
+
+export class RichyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RichyError";
+  }
+}
+
+const MAX_RESPONSE_BYTES = 2_000_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+// Read the body with a running byte counter and stop the moment it exceeds the cap,
+// so an oversized (or malicious) response is aborted mid-stream instead of being
+// fully buffered into memory before the length is checked. Falls back to a capped
+// text() read only if the response exposes no stream reader.
+async function readCapped(res, maxBytes) {
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    const text = await res.text();
+    if (text.length > maxBytes) throw new RichyError("richy_response_too_large");
+    return text;
+  }
+  const decoder = new TextDecoder();
+  let total = 0;
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new RichyError("richy_response_too_large");
+    }
+    out += decoder.decode(value, { stream: true });
+  }
+  return out + decoder.decode();
+}
+
+function clampScore(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+// The live service's /audit answers in the public-GET shape (kind:
+// "richy_public_get_audit"), which carries evidence but NO score on the wire —
+// pathScore only exists in Richy's DPA-packet builder, which the HTTP service
+// never uses. Without this scorer, overallScore is always null against the real
+// service and the cross-domain join (the reason Weftens exists) can never fire.
+// The rubric below is a deliberate copy of PIO's mapPublicGetAudit (verified
+// live 2026-07-08) so both consumers report the SAME number for the same audit —
+// deterministic from documented evidence fields, never invented.
+function scorePublicGetAudit(audit) {
+  const observed = audit.observed_evidence && typeof audit.observed_evidence === "object" ? audit.observed_evidence : {};
+  const crawl = observed.crawl && typeof observed.crawl === "object" ? observed.crawl : {};
+  const fetched = (Array.isArray(observed.fetched) ? observed.fetched : []).filter((x) => x && typeof x === "object");
+  const pagesFetched = typeof crawl.pages_fetched === "number" ? crawl.pages_fetched : 0;
+  // Nothing loaded → we scored nothing. A derived number here would fabricate a
+  // finding about a site we never reached; null is the honest answer.
+  if (pagesFetched === 0) return null;
+
+  const home = fetched.find((x) => x.kind === "page" && x.url === crawl.start_url) ?? fetched.find((x) => x.kind === "page") ?? {};
+  const metadata = home.metadata && typeof home.metadata === "object" ? home.metadata : {};
+  const jsonLd = metadata.json_ld && typeof metadata.json_ld === "object" ? metadata.json_ld : {};
+  const resourceOk = (kind) => fetched.some((x) => x.kind === kind && x.status_code === 200);
+  const hasText = (v) => typeof v === "string" && v.trim().length > 0;
+
+  const discovery =
+    40 + (resourceOk("robots") ? 15 : 0) + (resourceOk("sitemap") ? 15 : 0) +
+    (hasText(metadata.title) ? 15 : 0) + (hasText(metadata.meta_description) ? 15 : 0);
+
+  let penalty = 0;
+  for (const finding of Array.isArray(audit.findings) ? audit.findings : []) {
+    const severity = finding && typeof finding.severity === "string" ? finding.severity : "";
+    if (severity === "high" || severity === "blocked") penalty += 25;
+    else if (severity === "medium") penalty += 10;
+    else if (severity === "low") penalty += 4;
+  }
+  const trust = Math.round(Math.max(0, 100 - penalty) * 0.7) + (jsonLd.present === true ? 15 : 0) + (hasText(metadata.canonical) ? 15 : 0);
+
+  const action =
+    ((Array.isArray(home.cta_anchors) ? home.cta_anchors.length : 0) > 0 ? 60 : 0) +
+    ((Array.isArray(home.forms) ? home.forms.length : 0) > 0 ? 25 : 0) +
+    ((typeof metadata.h1_count === "number" ? metadata.h1_count : 0) >= 1 ? 15 : 0);
+
+  const stages = [discovery, trust, action].map((s) => clampScore(s) ?? 0);
+  return clampScore(stages.reduce((sum, s) => sum + s, 0) / stages.length);
+}
+
+// Richy's /audit answers in one of two shapes. Pull the overall score and up to
+// three fixes from whichever one came back; never assume a shape.
+export function normalizeAudit(body) {
+  const root = body && typeof body === "object" ? body : {};
+  const audit = "audit" in root ? root.audit ?? {} : root;
+  const pathScore = audit.pathScore ?? {};
+  const overall =
+    audit.kind === "richy_public_get_audit" ? scorePublicGetAudit(audit) : clampScore(pathScore.overall);
+  const rawFixes = Array.isArray(audit.topFixes) ? audit.topFixes : Array.isArray(audit.fix_queue) ? audit.fix_queue : [];
+  const topFixes = rawFixes
+    .filter((f) => f && typeof f.title === "string" && f.title.trim())
+    .slice(0, 3)
+    .map((f) => ({ title: String(f.title).slice(0, 200), why: String(f.why ?? "").slice(0, 400) }));
+  return { overallScore: overall, topFixes };
+}
+
+export function normalizePresence(body) {
+  const report = body && typeof body === "object" ? (body.report ?? body) : {};
+  const rawLanes = report.lanes && typeof report.lanes === "object" ? report.lanes : {};
+  const map = { reviews: "reviews", gbp: "businessProfile", listings: "localListings", aiVisibility: "aiAnswers", social: "social" };
+  const lanes = {};
+  for (const [upstream, key] of Object.entries(map)) {
+    lanes[key] = rawLanes[upstream]?.configured === true;
+  }
+  return lanes;
+}
+
+// A configured service endpoint must be reachable over TLS. The only exception is
+// a loopback http URL (127.0.0.1 / ::1 / localhost) for local dev and tests — over
+// any other host, plain http would expose the API key / credentials to the network.
+// Rejecting a bad base URL at construction stops a misconfigured or attacker-supplied
+// endpoint from ever receiving a secret. Reused by both Weftens service clients.
+export function requireSafeBaseUrl(rawUrl, ErrorClass) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new ErrorClass("bad_base_url");
+  }
+  const host = url.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  const loopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
+  if (url.protocol === "https:") return url.toString().replace(/\/$/, "");
+  if (url.protocol === "http:" && loopback) return url.toString().replace(/\/$/, "");
+  throw new ErrorClass("insecure_base_url");
+}
+
+export class RichyClient {
+  constructor({ baseUrl, key, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    if (!baseUrl || !key) throw new RichyError("richy_not_configured");
+    this.baseUrl = requireSafeBaseUrl(baseUrl, RichyError);
+    this.key = key;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async _post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-richy-key": this.key },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+        // Never follow a redirect: a compromised or MITM'd endpoint could 302 us
+        // into internal network space (SSRF) and the redirected request would carry
+        // x-richy-key to the attacker's host. A 3xx from the service is an error.
+        redirect: "manual",
+      });
+      if (res.status >= 300 && res.status < 400) throw new RichyError("richy_unexpected_redirect");
+      if (!res.ok) throw new RichyError(res.status >= 400 && res.status < 500 ? "richy_rejected" : "richy_unavailable");
+      return JSON.parse(await readCapped(res, MAX_RESPONSE_BYTES));
+    } catch (error) {
+      if (error instanceof RichyError) throw error;
+      throw new RichyError(error?.name === "AbortError" ? "richy_timeout" : "richy_unavailable");
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async representationCheck({ name, website, handles = [], queries = [] }) {
+    const [audit, presence] = await Promise.allSettled([
+      website ? this._post("/audit", { url: website, name }) : Promise.reject(new RichyError("no_website")),
+      this._post("/represent", { business: { name, handles }, queries }),
+    ]);
+    const siteOk = audit.status === "fulfilled";
+    const presenceOk = presence.status === "fulfilled";
+    if (!siteOk && !presenceOk) throw new RichyError("richy_unavailable");
+    const mapped = siteOk ? normalizeAudit(audit.value) : { overallScore: null, topFixes: [] };
+    return {
+      org: name,
+      website: website ?? null,
+      overallScore: mapped.overallScore,
+      topFixes: mapped.topFixes,
+      lanes: presenceOk ? normalizePresence(presence.value) : null,
+      siteCheckAvailable: siteOk,
+      presenceAvailable: presenceOk,
+      sample: false,
+    };
+  }
+}
+
+// Deterministic, no-network. Realistic normalized shape, sample:true so a Weftens
+// answer is never mistaken for a real Richy audit.
+export class FixtureRichyClient {
+  async representationCheck({ name, website = null }) {
+    return {
+      org: name,
+      website,
+      overallScore: 61,
+      topFixes: [
+        { title: "Put a clear next step on the homepage", why: "Visitors who can't see how to act usually leave." },
+        { title: "Add an outcomes summary with real numbers", why: "Concrete results are what make you the safe choice." },
+      ],
+      lanes: { reviews: true, businessProfile: false, localListings: false, aiAnswers: true, social: false },
+      siteCheckAvailable: true,
+      presenceAvailable: true,
+      sample: true,
+    };
+  }
+}

package/src/router.js

@@ -0,0 +1,34 @@
+// Intent routing. Weftens' whole job is to decide which named agent answers a
+// request and hand it over — Richy for how an org is represented, PIO for how an
+// org operates. This is deliberately a keyword classifier, not a model call: the
+// routing must be explainable and deterministic (a customer should be able to see
+// *why* their question went to one agent over the other), and an explicit intent
+// on the request always wins over inference.
+
+const REPRESENTATION = [
+  "represent", "representation", "reputation", "online", "website", "site",
+  "review", "listing", "search", "seo", "visibility", "audit", "appear",
+  "how do we look", "what do people see", "brand",
+];
+
+const OPERATIONS = [
+  "event", "attendee", "participant", "check-in", "checkin", "roster",
+  "grant", "funding", "program", "people", "follow-up", "followup", "donor",
+  "attendance", "registration", "operation",
+];
+
+// Returns { intent, confident }. `confident` is false when no keyword matched — in
+// that case we route to BOTH rather than silently guessing one domain (a silent
+// wrong-guess gives an operator a confident answer from the wrong specialist). The
+// caller surfaces the low-confidence routing so the ambiguity is visible, not hidden.
+export function classifyIntent(text = "") {
+  const t = String(text).toLowerCase();
+  const wantsRepresentation = REPRESENTATION.some((k) => t.includes(k));
+  const wantsOperations = OPERATIONS.some((k) => t.includes(k));
+  if (wantsRepresentation && wantsOperations) return { intent: "both", confident: true };
+  if (wantsOperations) return { intent: "operations", confident: true };
+  if (wantsRepresentation) return { intent: "representation", confident: true };
+  return { intent: "both", confident: false };
+}
+
+export const INTENTS = ["representation", "operations", "both"];