weftens 0.1.4 → 0.1.5

package/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# Weftens — Architecture
+
+How the code is organized. For what Weftens *is* and how it's positioned, see
+the positioning doc kept outside this repo; this file is the technical map.
+
+## The shape
+
+```
+weftens send "<request>"
+        │
+        ▼
+   agent-router.js ── deterministic keyword routing → one agent (+ why)
+        │
+        ▼
+   invoke.js ── runs the chosen agent by one of three paths:
+        ├── core-in-the-loop   a deterministic agent-cores package runs on an exported
+        │                      report and returns a checkable change sheet. No model.
+        ├── content-pipeline   the `content` lead runs the content-org media pipeline.
+        └── model-produce      a seat's .md is the system prompt, run through the user's
+                               own AI CLI (provider.js) — their subscription, no API key.
+```
+
+Richy and PIO have a second, older path of their own (`weftens ask`/`chat`/`route`): a
+Claude-driven tool loop and a deterministic synthesizer (`agent.js`, `weftens.js`,
+`router.js`, `synthesize.js`) that join representation + operations into one answer. The
+front door routes to them; they also run standalone.
+
+## Files
+
+| File | Role |
+|---|---|
+| `src/registry.js` | The agent directory — one entry per agent (tier, team, core, seat, routeHints). Source of truth for which agents exist. |
+| `src/agent-router.js` | The **front-door** router. Deterministic, explainable keyword match over the registry. |
+| `src/invoke.js` | Runs a routed agent (core CLI / content pipeline / model-produce). Degrades to a plain note; never fabricates. |
+| `src/provider.js` | Bring-your-own-model. Shells the user's chosen AI CLI (config, not code). |
+| `src/router.js` | The **Richy/PIO intent** classifier (representation vs operations). A sub-router, not the front door. |
+| `src/weftens.js` | The Richy+PIO orchestrator — gathers from both over their wire contracts and synthesizes one answer. |
+| `src/agent.js` | The Claude-driven Richy+PIO conversational agent (SDK tool loop). |
+| `src/synthesize.js` | Deterministic join of representation + operations. |
+| `src/richy-client.js`, `src/pio-client.js` | HTTP clients for the live Richy / PIO services (with fixtures for offline runs). |
+| `bin/weftens.js` | The CLI: `list`, `send`, `--route`, and the older `ask`/`chat`/`route`. |
+
+## Design rules
+
+- **Routing is deterministic and explainable.** A request matches an agent by declared keywords; the
+  CLI shows which matched. No model call to route — the routing layer runs with no API key.
+- **Bring-your-own-model.** Model-backed agents run on the user's own AI subscription via their CLI.
+  No key is stored, nobody is billed through Weftens.
+- **Propose-only where it matters.** The ad/SEO cores propose changes and write nothing to a live account.
+- **Portable.** Paths resolve relative to the install (`WEFTENS_WORKSPACE`, `WEFTENS_AGENTS_DIR`), not
+  to any one machine.
+- **Honest degradation.** When a step can't run (no input, missing provider CLI), invoke returns a plain
+  reason — never a fabricated result.
+
+## Invariants (do not break)
+
+- Each agent stays independently runnable; the front door routes to them, it does not absorb them.
+- Richy ↔ PIO integration is a PII-free wire contract, never repo coupling.
+- PIO's wire-shape (`grantengine_session` cookie, `x-grantengine-*` headers) is frozen.
+- The privacy spine — sanitized exports, human review gates, receipts — is shared across all names.
+
+## Naming
+
+Weftens is the company; **Richy** and **PIO** are named agents under it (not merged into one
+orchestrator). The naming history and business strategy live in the memory files and `WEFTENS_PICTURE.md`,
+not here. The repo is public and the package is on npm (2026-07-19). This file is the technical map, not a gate.

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.1.2
+
+Applied an outside code review. Four defects, each reproduced before it was fixed.
+
+- **The SDK and the CLI disagreed.** Specialist handling — resolving which organization a request
+  is about, mapping it to an intent, calling the orchestrator — was implemented in the CLI only.
+  `weftens("audit our listings")` from the published package returned a note saying the specialist
+  couldn't be invoked, while the same request through the CLI did the real work. Every test drove
+  the CLI, so nothing caught it. That logic moved into `invoke()`, client construction moved to
+  `src/specialists.js`, and `index.js` now exports the renderer. `test/sdk.test.js` drives the
+  entry point that actually ships.
+- **Every execution failure exited 0.** A missing input file, an absent provider CLI, a specialist
+  with no organization — all reported success. The tool wasn't scriptable, and the CI step meant to
+  prove a fresh clone works couldn't fail: with `agent-cores/` missing entirely it stayed green.
+- **The renderer threw on malformed input**, in the one place in the stack that must not — every
+  layer upstream fails soft with a plain note. Now guarded, and unit-tested as the pure function it
+  is (19 tests, 22ms, versus four subprocesses to assert on a string builder). It also hardcoded a
+  dollar sign while parsing reports denominated in the account's currency; currency now comes from
+  the report, or the amount prints bare.
+- **The routing confidence threshold was tuned rather than derived.** The constant meant a request
+  silently needed three weak signals while the comment claimed two, and it refused *"review the
+  site"* — an ordinary sentence at a door whose whole pitch is plain language. Five entries in the
+  weak-signal list matched nothing in the registry at all. A new registry-invariants suite makes
+  both impossible to reintroduce, and it immediately found a real one: `instagram` was claimed by
+  both the paid-social and organic-social seats, a permanent tie decided by scoring accident.
+
+Also: `engines` relaxed to Node >=20 (nothing required 22; the core-test runner is now portable
+instead of depending on a Node 21 glob), `exports` gained `./package.json`, the bin got its exec
+bit, and CI grew to eight jobs — Ubuntu and Windows across Node 20/22/24, plus a job that installs
+the actual packed tarball, because a git clone and an `npm install` are different artifacts and
+only one is what users get.
+
+207 tests.
+
+## 0.1.1
+
+Rewrote the front page for someone landing on it cold, and made the output on it real.
+
+Change sheets were emitted as raw JSON — correct for a program, useless to the person deciding
+whether to act. `src/format.js` renders one as plain text: rank, what to change, where, why, what
+it's worth, and what could go wrong. `--json` still returns the raw object for piping.
+
+Two honesty fixes, now enforced by tests. "Recoverable" became "flagged": the tool measures spend
+against a threshold, it does not establish that the money comes back — and the top-ranked line is
+a keyword that *converted*, so the old wording contradicted its own risk note on the same screen.
+"Never touches your ad account" was true of the seven deterministic auditors and stated as a
+property of all 27 seats; it is now scoped where it belongs, alongside what is finished, what is
+model-backed, what is a client for a service not in this repo, and what is still a placeholder.
+
+## 0.1.0
+
+First working release. A deterministic router over 27 agent seats, seven of them deterministic
+auditors that read an exported report and produce a ranked, propose-only change sheet with no
+model involved. Model-backed seats run on an AI CLI the user already has and is logged into — no
+API key, nobody billed through Weftens.
+
+Packaging fixes in the same release: the end-to-end test resolved `agent-cores/` from the repo's
+*parent*, so the suite passed only on a machine with a sibling checkout and failed in every fresh
+clone. The test runner also globbed the `node --test` core suites and reported nine phantom
+failures. Added the MIT license — a "free tool" with no license is unusable inside a company — a
+`files` allowlist, and a README whose claims match what was actually run.

package/README.md

@@ -23,7 +23,7 @@ wrong if you're wrong.
 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
+    npx weftens send paid-search audit --input node_modules/weftens/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
@@ -57,7 +57,7 @@ Free, MIT licensed, no account, no billing.
 ## Install
 
 ```
-git clone git@github.com:Weftens/weftens.git
+git clone https://github.com/Weftens/weftens.git
 cd weftens
 npm install
 npm test
@@ -140,7 +140,7 @@ CLI prints which words matched, so you always see why a request went where it di
 ## Honest status
 
 - **Verified:** deterministic routing, all seven auditor cores end-to-end, both specialist legs
-  (Richy/PIO) through the door, and BYOM model-produce via `claude`. **207 tests pass — 103 unit/CLI
+  (Richy/PIO) through the door, and BYOM model-produce via `claude`. **217 tests pass — 113 unit/CLI
   (vitest) + 104 core (`node --test`)**, confirmed in a fresh clone at an unrelated path, not just in
   the author's workspace.
 - **Richy and PIO are interfaces here, not implementations — read this before you install.**
@@ -153,10 +153,18 @@ CLI prints which words matched, so you always see why a request went where it di
   never mistake it for a finding about a real business. Everything else in this repo — all seven
   deterministic auditors, the router, the CLI, the SDK — runs entirely on what you just cloned.
   `weftens send richy --org "Acme Co" "audit our listings"` shows you exactly this.
+- **A file it cannot read is never reported as clean.** Hand an auditor the wrong export and it
+  says so — *"could not read this as the report this agent expects… this is NOT a finding that your
+  account is clean"* — and exits non-zero. Six of the seven cores are covered by this; `content-ops`
+  reports item counts with no monetary values, so the generic check cannot distinguish a wrong file
+  from a real inventory. Treat a `content-ops` run on an unexpected file with suspicion.
+- **`ask` and `chat` are the exception to "no API key".** Those two commands drive a conversational
+  orchestrator and need `ANTHROPIC_API_KEY`. Everything else — all routing, every deterministic
+  auditor, and every model-backed seat via your own CLI — needs no key.
 - **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.
-- **Published:** `npm i weftens` installs the real thing (`weftens@0.1.4`, MIT). Verified from the
+- **Published:** `npm i weftens` installs the real thing (`weftens@0.1.5`, 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.)

package/agents/growth-marketing.md

@@ -16,7 +16,6 @@ Experience" / "Ecommerce Marketing Account Director" (GH 5160651007 / 5118461007
 own acquisition channels, plan and run campaign tests, manage budget pacing, lifecycle/email
 programs, CRO, report against CAC/LTV/pipeline.
 
-
 ## What this agent does when run
 1. **Growth planning for real assets** — channel strategy, campaign concepts, test roadmaps, and
  funnel diagnostics for Machines Rule, client properties, or PIO's tenant work. Output is a plan
@@ -24,11 +23,7 @@ programs, CRO, report against CAC/LTV/pipeline.
 2. **Drill the ladder** — Tier-1 crash-week coaching (cert order, practice-campaign design for the
  $50 runs, platform walk-throughs), and Tier-2 concept drills (pacing scenarios, "ROAS dropped
  40% overnight — what do you check first" style).
-3. **Interview prep against live JDs** — fetch a current posting, map her true experience to its
- bullets, build the 2–3 campaign stories WITH numbers that hold the room, rehearse the probes
- (tools hands-on, budget scale, what was your number). Truth rule: stories are real; numbers are
- real; "certified" only when certified. No invented quota history — that claim family is probed
- and reference-checked.
+
 4. **Audit-and-propose on live channels** — reads exports/analytics and proposes changes. Composes
  with the audit seats: paid-search (Google Ads), amazon-ppc, supply-verify. PROPOSE-ONLY: a
  human applies changes in any live account; no spend moved by the agent.
@@ -42,12 +37,4 @@ programs, CRO, report against CAC/LTV/pipeline.
 
 ## Boundaries
 1. Propose-only on anything live: ad accounts, budgets, email sends to real lists.
-2. Job-hunt outputs follow the HONEST_CLAIMS scope rule — move fast, but resume/interview claims
- stay true (held = provable; the forward-looking framing lives in the skills file, not on the
- resume).
-3. This seat drills and prepares the owner for the paid seat; interviews and the job are performed by
- her.
 
-Good output: a channel plan a hiring manager would recognize as the job, or a drill that leaves
-her able to answer a real JD bullet with a true story and a number. Bad output: generic growth
-listicles, invented metrics, or plans with no hypothesis.

package/agents/security-writer.md

@@ -55,8 +55,7 @@ this seat exists partly to build them.
  notes — the writing surface of security engineering.
 
 ## Boundaries
-- The paid AI-trainer gig is human-performed work — the platform pays for the owner's judgment; this
- agent prepares and drills her, it does not do the gig for her.
+
 - Defensive and educational scope only: evaluation, explanation, documentation, and defensive
  patterns. No offensive tooling beyond what understanding published material requires.
 

package/agents/seo-content.md

@@ -1,6 +1,6 @@
 ---
 name: seo-content
-description: Content & entity SEO seat — the strategy-and-authority half of heavy SEO. Run on keyword/GSC/Semrush/Ahrefs data, a competitor set, or a topic to decide what a site should rank and be cited for, then turn that into briefs the content team produces. Owns keyword and entity strategy, answer-surface visibility, and rank/traffic/citation measurement. Consumes Richy's resolution audit and the technical seat's clean site; produces gated briefs, never publishes. Anchors to the content/strategy half of the Senior SEO/AEO Specialist (UPG) and SEO & Website Optimization Specialist (BrandMinded) postings.
+description: Content & entity SEO seat — the strategy-and-authority half of heavy SEO. Run on keyword/GSC/Semrush/Ahrefs data, a competitor set, or a topic to decide what a site should rank and be cited for, then turn that into briefs the content team produces. Owns keyword and entity strategy, answer-surface visibility, and rank/traffic/citation measurement. Consumes Richy's resolution audit and the technical seat's clean site; produces gated briefs, never publishes.
 ---
 
 You are the content and entity SEO seat — you decide what the site should win and hand the content

package/agents/seo-technical.md

@@ -1,6 +1,6 @@
 ---
 name: seo-technical
-description: Technical SEO seat — the site-plumbing half of heavy SEO. Run on a crawl, GSC export, log-file sample, or a live URL to find what stops machines from crawling, indexing, and rendering a site correctly, and to write schema/structured data that earns rich results and AI-answer grounding. Diagnoses and proposes; site and DNS changes are the owner's/developer's to apply. Anchors to the technical half of the Senior SEO/AEO Specialist (UPG) and SEO & Website Optimization Specialist (BrandMinded) postings.
+description: Technical SEO seat — the site-plumbing half of heavy SEO. Run on a crawl, GSC export, log-file sample, or a live URL to find what stops machines from crawling, indexing, and rendering a site correctly, and to write schema/structured data that earns rich results and AI-answer grounding. Diagnoses and proposes; site and DNS changes are the owner's/developer's to apply.
 ---
 
 You are the technical SEO seat — the plumbing under the search surface. Richy tells you how the

package/bin/weftens.js

@@ -15,7 +15,7 @@
 import { readFileSync } from "node:fs";
 import readline from "node:readline";
 import { orchestrate } from "../src/weftens.js";
-import { isChangeSheet, formatChangeSheet } from "../src/format.js";
+import { isChangeSheet, formatChangeSheet, looksUnparsed, unparsedNotice } from "../src/format.js";
 import { askWeftens } from "../src/agent.js";
 import { buildSpecialistClients } from "../src/specialists.js";
 import { route } from "../src/agent-router.js";
@@ -153,6 +153,13 @@ async function cmdSend(args, { routeOnly } = {}) {
   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 && looksUnparsed(outcome.result)) {
+      process.stdout.write(`
+${unparsedNotice(outcome.result)}
+`);
+      process.exitCode = 1;
+      return;
+    }
     if (!asJson && isChangeSheet(outcome.result)) {
       process.stdout.write(`\n${formatChangeSheet(outcome.result)}\n`);
     } else {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "weftens",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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.",
+  "description": "Weftens — 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",
@@ -23,6 +23,8 @@
     "providers.json.example",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
     "!**/.preflight",
     "!**/.preflight/**"
   ],
@@ -39,7 +41,8 @@
     "vitest": "^2.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.110.0"
+    "@anthropic-ai/sdk": "^0.110.0",
+    "weftens": "^0.1.4"
   },
   "repository": {
     "type": "git",

package/src/format.js

@@ -35,6 +35,80 @@ export function isChangeSheet(result) {
   return Boolean(result && typeof result === "object" && Array.isArray(result.changes));
 }
 
+
+// A core that was handed the WRONG report does not usually error — it parses the rows, finds none of
+// the columns it wants, and returns a well-formed sheet with zero changes. Rendered normally that
+// reads as "your account is clean", which is the most expensive lie this tool could tell: a user
+// exports the wrong file and is told there is nothing to fix. Five of seven cores did exactly this.
+//
+// The signal is that rows were read but every money/volume figure came back zero or null. A real
+// account under audit always has spend. An account with genuinely zero activity is indistinguishable
+// — and for that one, "this doesn't look like the right export, or there was no activity" is also
+// the truthful answer.
+// Two different kinds of number, and conflating them is what let four cores slip past the first two
+// versions of this check. ROW fields count what was READ — a non-zero row count proves the file was
+// opened, not that it was understood. VALUE fields are what the report is FOR. The signal for "wrong
+// file" is: rows were read, and every value came back zero.
+const ROW_FIELDS = ["rows", "terms", "placements", "urls", "pages", "items", "searchTermRows", "campaignRows"];
+const VALUE_FIELDS = [
+  "totalCost", "totalSpend", "totalClicks", "totalImpressions", "totalConversions",
+  "totalResults", "spend", "cost", "clicks", "impressions", "conversions", "sales", "orders",
+  "flaggedSpend", "reclaimableSpend", "totalViews", "views",
+];
+
+export function looksUnparsed(result) {
+  if (!result || typeof result !== "object") return false;
+  if (Array.isArray(result.changes) && result.changes.length > 0) return false;
+  // Cores don't share one result shape: some report totals under `account`, others under `summary`,
+  // others at the top level. Check wherever the volume figures actually live rather than assuming a
+  // shape — assuming `account` is why four of the five cores slipped past the first version of this.
+  // Every core names its totals block differently — `account`, `summary`, `totals` — and the first
+  // two versions of this guard each missed the cores they didn't happen to name. Scan any one-level
+  // block that carries volume fields instead of guessing at keys; a new core is covered for free.
+  const blocks = [result, ...Object.values(result).filter((v) => v && typeof v === "object" && !Array.isArray(v))];
+  const zero = (v) => v === 0 || v === null || v === undefined;
+
+  // Strongest signal first: a core that reports it read ZERO rows read nothing at all. Whatever the
+  // file was, it was not this report.
+  for (const b of blocks) {
+    for (const f of ROW_FIELDS) if (b[f] === 0) return true;
+  }
+
+  for (const b of blocks) {
+    const values = VALUE_FIELDS.filter((f) => f in b && typeof b[f] !== "object");
+    if (values.length === 0) continue;
+    if (!values.every((f) => zero(b[f]))) continue;
+    // Every value is zero. If rows were read, the file parsed as text but not as this report.
+    // If no row count is reported either, an all-zero result is still not a clean bill of health.
+    return true;
+  }
+  return false;
+}
+
+/** Row count from wherever a core reports it — used only to make the refusal message concrete. */
+function rowsRead(result) {
+  if (!result || typeof result !== "object") return null;
+  const blocks = [result, ...Object.values(result).filter((v) => v && typeof v === "object" && !Array.isArray(v))];
+  for (const b of blocks) {
+    for (const f of ROW_FIELDS) if (typeof b[f] === "number" && b[f] > 0) return b[f];
+  }
+  return null;
+}
+
+
+/** The one message for "this file did not parse", shared by every core shape. */
+export function unparsedNotice(result) {
+  const rows = rowsRead(result);
+  return [
+    "Could not read this as the report this agent expects.",
+    typeof rows === "number" && rows > 0
+      ? `  ${rows} row(s) were read, but none of the expected columns (spend, clicks, results) had values.`
+      : "  No rows with the expected columns were found.",
+    "  This is NOT a finding that your account is clean — it means the file did not parse.",
+    "  Check you exported the right report for this agent, then run it again.",
+  ].join("\n");
+}
+
 /**
  * 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.
@@ -50,6 +124,9 @@ export function formatChangeSheet(result) {
   const changes = result.changes.filter((c) => c && typeof c === "object");
   const dropped = result.changes.length - changes.length;
 
+  // Refuse to present an unreadable file as a clean bill of health.
+  if (looksUnparsed(result)) return unparsedNotice(result);
+
   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