jev-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gourav Das
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# jev-audit
+
+[![npm version](https://img.shields.io/npm/v/jev-audit.svg)](https://www.npmjs.com/package/jev-audit)
+[![npm downloads](https://img.shields.io/npm/dm/jev-audit.svg)](https://www.npmjs.com/package/jev-audit)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A516-green.svg)](package.json)
+[![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/jev-audit.svg)](https://bundlephobia.com/package/jev-audit)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg)](https://github.com/MagicBeansAI/jev-audit/pulls)
+
+**Your LLM bill is full of decisions pretending to be generations.**
+
+`jev-audit` finds every LLM call in your codebase that is really a *decision* — classify, route, score, verify — and shows you exactly what it looks like on [Jev](https://docs.typesafe.ai), TypeSafe AI's System One decision model.
+
+```text
+              frontier LLM          Jev
+output        free text             typed decision + calibrated confidence
+latency       1–10 s                ~100 ms
+input cost    $3–15 / M tokens      $0.042 / M tokens
+output cost   $15–75 / M tokens     free
+hallucination whenever it wants     structurally impossible (fixed option set)
+```
+
+No API key. No network. Nothing leaves your machine.
+
+## The 30-second version
+
+```bash
+npx jev-audit
+```
+
+```text
+jev-audit scan — ~/acme-support
+files scanned: 214    llm touchpoints: 37    decision-shaped: 11
+
+hottest files:
+    9  src/triage.js
+    6  src/moderation.py
+    4  src/router.ts
+
+decision-shaped call sites (prime Jev candidates):
+  src/triage.js:42      [chat-completion]  const dept = await openai.chat.completions.create({
+  src/moderation.py:17  [chain-class]      classifier = ChatOpenAI(model="gpt-4o-mini")
+  src/router.ts:88      [message-create]   const res = await anthropic.messages.create({
+  ...
+
+→ full inventory: jev-scan.json
+```
+
+Eleven of those 37 calls are decisions wearing a generator's clothes. That's usually where most of the spend and most of the latency lives.
+
+## Then let your agent write the report
+
+```bash
+npm install -g jev-audit          # or keep using npx
+jev-audit install claude          # claude | codex | cursor | grok | agy | pi | zcode | agents
+                                  # anything else: jev-audit install --dir <skills-dir>
+```
+
+Ask your agent:
+
+```text
+> audit this repo with jev-audit
+```
+
+You get a **`JEV_AUDIT.md`** in the repo root:
+
+```markdown
+# Jev Audit — acme-support
+
+- 37 LLM call sites · 11 Replace · 3 Hybrid · 19 Keep LLM · 4 Pure code
+- Estimated saving on the Replace set: $212 per 1,000 calls (math in §5)
+- Best quick win: src/triage.js:42 — leaf classification, lowest blast radius
+
+| # | Location            | Job of the call                     | Tier                          |
+|---|---------------------|-------------------------------------|-------------------------------|
+| 1 | src/triage.js:42    | department + urgency + frustration  | Replace → choice + noul + score |
+| 2 | src/moderation.py:17| safe / unsafe / borderline          | Replace → choice               |
+| 3 | src/router.ts:88    | query → specialist agent            | Replace → choice + noul        |
+| 4 | src/draft.js:12     | write the customer-facing reply     | Keep LLM (real generation)     |
+
+…plus the draft Jev question JSON, confidence thresholds, target
+architecture diagram, and a shadow-mode migration plan.
+```
+
+### What a replacement looks like
+
+**Before** — 1.4 s, ~$0.003/call, JSON-parse roulette:
+
+```js
+const res = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'system', content: 'Classify this ticket. Reply with JSON…' }, …],
+});
+const { department, urgent } = JSON.parse(res.choices[0].message.content);
+```
+
+**After** — ~100 ms, ~$0.0000004/call, typed:
+
+```js
+const r = await client.systemOne({
+  state: ticket,
+  questions: {
+    department: choice({ instructions: 'Which team should handle this',
+                         criteria: { billing: '…', technical: '…', sales: '…' } }),
+    is_urgent: noul({ instructions: 'The message conveys urgency' }),
+    frustration: score({ instructions: 'How frustrated the customer appears',
+                         criteria: ['Calm', 'Frustrated but civil', 'Very angry'] }),
+  },
+});
+
+r.answers.department.choice     // "billing" — it cannot be anything else
+r.answers.department.confidence // 0.84 → gate automation on this
+```
+
+## The one table that matters
+
+| Job at the call site | Verdict |
+|---|---|
+| Yes/no judgment on text (spam, urgent, jailbreak) | **Replace** → Jev `noul` |
+| Pick one of N (intent, routing, category, moderation) | **Replace** → Jev `choice` |
+| Level on a rubric (severity, quality, priority) | **Replace** → Jev `score` |
+| Decide, then write | **Hybrid** — Jev decides, LLM writes |
+| LLM output that needs checking against rules/sources | **Hybrid** — LLM writes, Jev verifies |
+| Prose, summaries, code, translation | **Keep LLM** |
+| Counting, dates, exact matching | **Pure code** — not even Jev |
+
+## How it works
+
+1. **Local scanner** — zero dependencies, zero network. Regex-inventories SDK imports (`openai`, `@anthropic-ai/sdk`, `langchain`, `@ai-sdk`, …), raw endpoints, env keys, and call shapes, and flags *decision-shaped* lines as prime candidates.
+2. **Agent skill** — `skill/jev-audit/SKILL.md` makes your coding agent read each call site, apply the tiering table, show the savings math, and write `JEV_AUDIT.md` with the target architecture (`code → Jev → LLM`) mapped onto your modules.
+
+Works with any SKILL.md-compatible harness: Claude Code, Codex, Cursor, Grok, Agy, Pi, ZCode, …
+
+```bash
+# GitHub install (skills.sh-compatible layout):
+npx skills add MagicBeansAI/jev-audit --skill jev-audit
+```
+
+## FAQ
+
+**Does it send my code anywhere?** No. The scanner is local regex; the analysis runs in your own agent session. The audit never calls Jev — it only tells you where *you* should.
+
+**Is it affiliated with TypeSafe AI?** No — independent community tool by [MagicBeansAI](https://github.com/MagicBeansAI). Jev pricing/limits are quoted from the public docs; verify before budgeting.
+
+**Why "decision-shaped"?** If downstream code branches on the output instead of a human reading it, a typed decision beats a generation: cheaper, faster, and structurally incapable of inventing a fourth option.
+
+**I already use structured output / JSON mode. Why change?** Structured output still pays generation prices and generation latency for a decision, still drifts outside the schema often enough to need retries, and gives you no calibrated confidence to gate automation on.
+
+## Contributing
+
+Pattern misses (an SDK we don't spot, a call shape that escapes us) are the highest-value PRs — they live in one file: [`skill/jev-audit/scripts/scan.js`](skill/jev-audit/scripts/scan.js). Report false positives/negatives as issues with the offending line.
+
+## License
+
+[MIT](LICENSE) © MagicBeansAI

package/bin/jev-audit.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// jev-audit CLI — scan a repo for replaceable LLM calls, install the agent skill.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const VERSION = '0.1.0';
+const SKILL_SRC = path.join(__dirname, '..', 'skill', 'jev-audit');
+
+const HARNESS_DIRS = {
+  claude: '.claude',
+  codex: '.codex',
+  cursor: '.cursor',
+  grok: '.grok',
+  agy: '.agy',
+  pi: '.pi',
+  zcode: '.zcode',
+  agents: '.agents',
+};
+
+function usage() {
+  console.log(`
+jev-audit v${VERSION} — find the decisions hiding in your LLM bill
+
+Usage:
+  jev-audit [scan] [path]     Inventory LLM call sites (local regex scan, no network).
+                              Writes jev-scan.json and prints the summary.
+  jev-audit install <target>  Install the jev-audit skill into an agent harness.
+                              Targets: ${Object.keys(HARNESS_DIRS).join(' | ')}
+                              Options: --project (cwd instead of ~), --dir <path>
+  jev-audit help              This message.
+
+Then, inside your agent:  "audit this repo with jev-audit"
+`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name);
+    const d = path.join(dest, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function cmdInstall(target, opts) {
+  const t = HARNESS_DIRS[target] ? target : 'agents';
+  if (target && !HARNESS_DIRS[target]) {
+    console.log(`Unknown harness "${target}" — defaulting to "agents" (~/.agents/skills is the cross-tool location). Use --dir to override.`);
+  }
+  let dest;
+  if (opts.dir) {
+    dest = path.join(opts.dir, 'jev-audit');
+  } else {
+    const base = opts.project ? process.cwd() : os.homedir();
+    dest = path.join(base, HARNESS_DIRS[t], 'skills', 'jev-audit');
+  }
+  copyDir(SKILL_SRC, dest);
+  console.log(`Installed skill → ${dest}`);
+  console.log(`Restart your agent if it was running, then ask: "audit this repo with jev-audit"`);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const opts = { dir: null, project: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--dir') opts.dir = argv[++i];
+    else if (argv[i] === '--project') opts.project = true;
+    else if (argv[i] === '--version' || argv[i] === '-v') return console.log(VERSION);
+    else positional.push(argv[i]);
+  }
+  const cmd = positional[0] || 'scan';
+
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') return usage();
+
+  if (cmd === 'install') {
+    return cmdInstall(positional[1], opts);
+  }
+
+  if (cmd === 'scan' || !fs.existsSync(path.resolve(cmd))) {
+    if (cmd !== 'scan') console.log(`"${cmd}" is not a path — treating this as a scan of the current directory.\n`);
+    const { runScan, printSummary } = require(path.join(SKILL_SRC, 'scripts', 'scan.js'));
+    const result = runScan(positional[1] || '.');
+    printSummary(result);
+    fs.writeFileSync(path.join(process.cwd(), 'jev-scan.json'), JSON.stringify(result, null, 2));
+    console.log(`\n→ full inventory: ${path.join(process.cwd(), 'jev-scan.json')}`);
+    console.log(`→ next: npx jev-audit install claude|codex|cursor|grok|agy|pi|zcode|agents, then ask your agent to "audit this repo with jev-audit".`);
+    return;
+  }
+
+  // bare path argument: scan it
+  const { runScan, printSummary } = require(path.join(SKILL_SRC, 'scripts', 'scan.js'));
+  const result = runScan(cmd);
+  printSummary(result);
+  fs.writeFileSync(path.join(process.cwd(), 'jev-scan.json'), JSON.stringify(result, null, 2));
+  console.log(`\n→ full inventory: ${path.join(process.cwd(), 'jev-scan.json')}`);
+}
+
+main();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "jev-audit",
+  "version": "0.1.0",
+  "description": "Find every LLM call in your codebase that should be a Jev decision instead of a generation. Scans locally, classifies call sites, and designs the replacement architecture.",
+  "license": "MIT",
+  "author": "MagicBeansAI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MagicBeansAI/jev-audit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MagicBeansAI/jev-audit/issues"
+  },
+  "homepage": "https://github.com/MagicBeansAI/jev-audit#readme",
+  "bin": {
+    "jev-audit": "bin/jev-audit.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "jev",
+    "typesafe",
+    "system-one",
+    "llm",
+    "audit",
+    "cost-optimization",
+    "agent",
+    "skill",
+    "claude",
+    "codex",
+    "cursor",
+    "grok"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/skill/jev-audit/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: jev-audit
+description: Audit a codebase to find LLM calls that can be replaced with Jev (TypeSafe AI's System One decision model) and design the replacement architecture, producing a JEV_AUDIT.md report. Use when the user asks to evaluate or audit AI/LLM usage in a repo, cut LLM costs or latency, replace/migrate LLM calls to Jev or decision models, figure out which calls are decisions vs generation, or mentions jev-audit, typesafe, System One, or "what can I move to Jev".
+---
+
+# Jev Audit
+
+You are auditing this codebase to answer one question: **which LLM calls here are actually decisions, and what would they look like as Jev calls?**
+
+Jev is a decision model, not a text generator. You send it a `state` (context) plus typed questions and get back calibrated decisions — `noul` (yes/no probability), `choice` (pick from options), `score` (rubric level) — with confidence. It is ~2 orders of magnitude faster and cheaper than LLMs for these calls, and cannot hallucinate because it cannot emit anything outside the types you declared. Generation stays on the LLM. Read `references/jev-reference.md` before proposing any code.
+
+## Ground rules
+
+- Cite `file:line` for every claim in the report. No invented call sites.
+- Every cost number is an estimate — show the arithmetic and the assumptions (volume, tokens/call). If volume is unknown, express savings per 1,000 calls, not per month.
+- Never propose Jev for generation, summarization, code writing, math/counting, date comparison, or anything involving images/audio. Proposing these destroys the report's credibility.
+- Never propose any model (Jev included) where a plain `if`, regex, or schema validation already works. An if-statement that costs nothing beats a model call that can be wrong.
+
+## Step 1 — Inventory the LLM surface
+
+Run the bundled scanner (local, zero network, zero dependencies):
+
+```bash
+node <this-skill-dir>/scripts/scan.js <repo-path>
+```
+
+It writes `jev-scan.json` with every hit as `{file, line, category, pattern, snippet, decisionShaped}`. If the scanner is unavailable, reproduce it with ripgrep over `*.js *.jsx *.ts *.tsx *.mjs *.cjs *.py *.rb *.go *.rs *.java *.kt *.swift *.php *.cs *.sh *.yaml *.yml *.toml *.json` plus `.env*`, searching for:
+
+- SDK imports: `openai`, `@anthropic-ai/sdk`, `@google/generative-ai`, `@ai-sdk/`, `from "ai"`, `langchain`, `@langchain`, `llamaindex`, `mistral`, `cohere`, `groq`, `@xai/sdk`, `ollama`, `@azure/openai`, `bedrock`
+- Endpoints: `api.openai.com`, `api.anthropic.com`, `generativelanguage.googleapis.com`, `api.groq.com`, `api.x.ai`, `openrouter.ai`, `api.deepseek.com`, `api.together.xyz`, `api.mistral.ai`, `api.cohere.com`
+- Keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `COHERE_API_KEY`
+- Call shapes: `chat.completions.create`, `messages.create`, `generateContent`, `respond`, `invoke(`, `ChatOpenAI`, `agent(`
+
+Lines already using `@typesafe-ai/sdk`, `typesafe_sdk`, or `api.typesafe.ai` are migrated — list them as "already Jev" and exclude from savings.
+
+## Step 2 — Read every call site
+
+The scanner finds lines; only reading code reveals the *job*. For each hit, open the file and record:
+
+- **Job**: what the call decides or produces (read the prompt, the system message, how the caller consumes the output).
+- **Output consumption**: does downstream code branch/compare/route on the result (decision-shaped), or display/use free text (generation)?
+- **Model + sizes**: model name, rough input tokens, `max_tokens`/output size.
+- **Frequency hints**: request path, queue consumer, cron, batch script, or user-facing per-request.
+- **Failure handling**: retries, fallbacks, JSON parsing of model output (a JSON-parse-after-LLM is a strong decision-in-disguise smell).
+
+Skip vendored/generated code, tests with mocked calls (note them, don't count them), and documentation.
+
+## Step 3 — Classify each call site
+
+Assign exactly one tier per call site:
+
+| Job at the call site | Tier | Jev primitive |
+|---|---|---|
+| Yes/no judgment on text: spam, urgent, toxic, refund requested, jailbreak attempted, field is empty-ish | **Replace** | `noul` |
+| Pick one of N: intent → team, category labeling, route to model/prompt/agent/tool, moderation class, which candidate matches an entity | **Replace** | `choice` |
+| Level on a rubric: severity, quality, priority, relevance, frustration, lead score | **Replace** | `score` |
+| Multi-factor judgment ("rate this pitch") | **Replace** | composite: several `score`s, weighted in code |
+| Decide then write: classify/route first, generate only for the chosen branch | **Hybrid** | Jev decides, LLM generates the branch that needs prose |
+| LLM generates, then its output needs checking against rules/sources | **Hybrid** | LLM writes, Jev verifies (`noul` per claim / `choice` per class) |
+| Free-text generation: summaries, drafts, code, translations, answers | **Keep LLM** | — |
+| Arithmetic, counting, comparing dates, exact string/schema matching | **Pure code** | — |
+
+Anything you cannot confidently assign after reading the code goes in a final "Needs human judgment" section — do not guess it into Replace.
+
+## Step 4 — Estimate impact
+
+For each Replace/Hybrid call site: `savings ≈ calls × input_tokens × (LLM_input_$per_M − 0.042) + calls × output_tokens × LLM_output_$per_M` (Jev output tokens are free; check current prices in `references/jev-reference.md`). Show per-1,000-call savings when volume is unknown, and state the blended assumption you used for the incumbent LLM.
+
+## Step 5 — Design the target architecture
+
+Read `references/architecture.md`, then produce:
+
+1. A target-architecture diagram (mermaid) of the three layers: deterministic code → Jev decisions → LLM generation, with this repo's actual modules on it.
+2. For each of the top 3–5 Replace candidates, the exact draft Jev question set (JSON with `state` source, `type`, `instructions`, `criteria`) and the confidence thresholds for act / human-review / escalate-to-LLM.
+3. A migration order: leaf classification calls first (lowest blast radius), verification loops second, routing last — with a shadow-mode step (Jev runs alongside the LLM, results compared, before cutover).
+
+## Step 6 — Write the report
+
+Fill in `assets/REPORT_TEMPLATE.md` and write it to `JEV_AUDIT.md` at the repo root. Keep the attribution footer intact — it is how the report travels. If the user wants starter code, additionally emit `jev/questions.ts` (or `.py`) with the draft question definitions behind a thin adapter so Jev and LLM stay swappable.
+
+Finally, give the user a short summary in chat: total call sites, counts per tier, the single best quick win, and point at `JEV_AUDIT.md`.

package/skill/jev-audit/assets/REPORT_TEMPLATE.md

@@ -0,0 +1,87 @@
+# Jev Audit — <repo name>
+
+> Which LLM calls in this codebase are actually decisions, and what would they look like on Jev?
+> Generated <date> · Scanner hits: <N> · Call sites reviewed: <M> · Analysis by the coding agent using **jev-audit**
+
+## 1. Executive summary
+
+- LLM call sites found: **<total>** across <files> files (<sdks>).
+- **<n1> can move to Jev now** (Replace), **<n2> split into decide + generate** (Hybrid), **<n3> should stay on the LLM**, **<n4> shouldn't be a model call at all** (pure code).
+- Estimated saving on the Replace set: **<$X per 1,000 calls** (assumptions in §5).
+- Best quick win: <one sentence — highest confidence, lowest blast radius>.
+
+## 2. Inventory
+
+| # | Location | SDK / model | Job of the call | Calls/day | Tier |
+|---|---|---|---|---|---|
+| 1 | `src/triage.js:42` | openai / gpt-4o-mini | Classify ticket → department + urgency | ~4,000 | Replace |
+| 2 | … | | | | |
+
+Every row must cite `file:line`. `Calls/day` = observed (queue/cron/route) or **assumed** in bold.
+
+## 3. Tier detail
+
+### 3.1 Replace — move to Jev now
+
+For each: the job, why it's a decision not a generation, and the draft Jev question set.
+
+#### <Call site #1 — `src/triage.js:42`>
+
+```json
+{
+  "model": "jev-latest",
+  "state": { "subject": "<from ticket>", "body": "<from ticket>", "plan": "<customer plan>" },
+  "questions": {
+    "department": {
+      "type": "choice",
+      "instructions": "Which team should handle this `body`",
+      "criteria": { "billing": "…", "technical": "…", "sales": "…" }
+    },
+    "is_urgent": { "type": "noul", "instructions": "The `body` conveys urgency or time-sensitivity" }
+  }
+}
+```
+
+Confidence plan: ≥0.9 act · 0.5–0.9 template path · <0.5 human queue.
+
+### 3.2 Hybrid — Jev decides, LLM generates
+
+<Which sub-call moves, which stays, and where the seam goes.>
+
+### 3.3 Keep on LLM
+
+<Each with one honest sentence why: output is prose consumed by humans / genuine generation.>
+
+### 3.4 Pure code — stop calling a model
+
+<Schema checks, exact matches, counting — the deterministic call that was always there.>
+
+### 3.5 Needs human judgment
+
+<Couldn't determine from code alone — what to check and how.>
+
+## 4. Target architecture
+
+```mermaid
+flowchart LR
+  %% current flow with LLM call sites colored by tier, then target three-layer flow
+```
+
+<Diagram + narrative: code layer → Jev layer → LLM layer with this repo's real module names; adapter seam location; shadow-mode → canary → rollback plan.>
+
+## 5. Savings estimate
+
+| Call site | Calls/mo | In tok/call | Out tok/call | LLM $/mo | Jev $/mo | Saving |
+|---|---|---|---|---|---|---|
+
+Arithmetic shown per row. Assumptions: <blended incumbent price, volumes, token sizes>. **These are estimates from static analysis — validate against real usage logs before budgeting.**
+
+## 6. Migration order
+
+1. <Leaf classification call — lowest blast radius, shadow-mode first>
+2. …
+3. <Routing change last — biggest downstream impact>
+
+---
+
+*Audit generated with **jev-audit** — find the decisions hiding in your LLM bill: `npx jev-audit`*

package/skill/jev-audit/references/architecture.md

@@ -0,0 +1,94 @@
+# Target architecture patterns
+
+The governing principle is a three-layer split, each layer doing only what it is good at:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Layer 1 — Code (deterministic)                         │
+│  if / regex / schema validation. Free, exact, testable. │
+├─────────────────────────────────────────────────────────┤
+│  Layer 2 — Jev (decisions)                              │
+│  classify, route, score, verify. Typed, calibrated,     │
+│  ~100ms, $0.042/M input, output free.                   │
+├─────────────────────────────────────────────────────────┤
+│  Layer 3 — LLM (generation)                             │
+│  write prose/code only when prose/code is the product.  │
+└─────────────────────────────────────────────────────────┘
+```
+
+An if-statement that costs nothing beats a model call that can be wrong; a Jev decision beats an LLM call whenever the output is consumed by code rather than read by a human. Cost savings = (share of calls that are decisions) × (price delta on those calls) — so report savings only against calls that actually move.
+
+## Pattern 1 — Confidence-gated routing
+
+Every Jev answer carries `confidence` (and Choice gives the full probability distribution). Route on it:
+
+```
+noul ≥ 0.9            → act autonomously
+0.5 ≤ noul < 0.9      → cheap LLM double-check or template path
+noul < 0.5            → human review queue
+```
+
+Thresholds are product decisions, not defaults — set them per question in one reviewable config file, and tune with real traffic. This is how you get "zero hallucination" in practice: low confidence never reaches automation.
+
+## Pattern 2 — Hybrid pipeline (Jev decides, LLM writes)
+
+Classic support-flow replacement:
+
+```
+ticket in ──▶ Jev: department(choice) + urgency(noul) + frustration(score)
+                 │
+                 ├─ billing + urgent + frustrated ──▶ LLM drafts empathetic reply (only here)
+                 ├─ technical                      ──▶ template + KB link (no model at all)
+                 └─ low confidence                 ──▶ human queue
+```
+
+The LLM call now happens on a fraction of tickets, and the decision calls cost ~nothing. Same shape applies to content moderation, lead handling, and agent tool-selection (Jev picks the tool; the LLM fills arguments only when needed).
+
+## Pattern 3 — Speculative fan-out
+
+Questions in one request run in parallel and in isolation — ask everything that *might* matter, even if some answers go unused on a given input. Latency stays ~flat; cost is input tokens only (output is free). A TypeSafe cookbook batched 13 questions in one call for a reported 12.2× cost cut vs sequential calls. So: one call per request context, all atomic questions together.
+
+## Pattern 4 — Composite scoring with code-owned weights
+
+Never ask Jev one blobby "rate this". Decompose into atomic `score`s (each a judgment a knowledgeable person makes in seconds), then combine in code:
+
+```ts
+const pitchScore =
+  0.4 * normalize(answers.market_size.score) +
+  0.35 * normalize(answers.feasibility.score) +
+  0.25 * normalize(answers.differentiation.score);
+```
+
+When priorities shift, change a coefficient — no prompt rewrite, no re-eval of everything else.
+
+## Pattern 5 — Extraction as selection
+
+Jev picks, it doesn't recall. Pipeline: regex/parser/cheap-LLM produces candidate values → Jev `choice` selects the right one (with confidence). Use for entity alignment, field extraction from messy text, picking which of N retrieved passages answers a query (cookbooks show BM25 shortlist + Jev rerank lifting top-1 accuracy meaningfully).
+
+## Pattern 6 — Verify what the LLM generates
+
+Keep generation on the LLM; add a Jev verification pass: each factual claim → `noul` "is this supported by `source`?" or output class → `choice` safe/unsafe. Low-confidence claims get flagged or stripped before the user sees them. This converts "LLM output, hopefully fine" into "LLM output with a calibrated check" — usually the easiest sell to whoever owns reliability.
+
+## Migration sequencing
+
+1. **Inventory + label** (this audit's report).
+2. **Adapter seam**: put decisions behind an interface so implementations are swappable and the LLM stays as fallback:
+
+```ts
+interface Triager {
+  triage(ticket: Ticket): Promise<{ dept: Dept; urgent: boolean; confidence: number }>;
+}
+// JevTriager (primary) — LlmTriager (existing behavior, kept as fallback)
+```
+
+3. **Shadow mode**: route real traffic through both, log disagreements, tune thresholds/criteria wording offline.
+4. **Canary cutover** on the leaf classification calls first (lowest blast radius), then verification passes, then routing (which changes downstream behavior most).
+5. **Rollback** = flip the adapter back. Keep the LLM path until Jev has weeks of clean production data.
+
+## What the report's architecture section must contain
+
+- Mermaid diagram of current flow with each LLM call marked by tier.
+- Same diagram for the target three-layer flow, using the repo's real module names.
+- The draft Jev question set for top candidates (exact JSON).
+- Confidence thresholds and what each band does (act / verify / human).
+- The adapter seam location (file + interface name) and the shadow-mode plan.

package/skill/jev-audit/references/jev-reference.md

@@ -0,0 +1,138 @@
+# Jev reference — API, primitives, limits, pricing
+
+Facts only; verify against https://docs.typesafe.ai before finalizing generated integration code — early-access details move fast.
+
+## Mental model
+
+Jev is TypeSafe AI's System One model. You send a `state` (the context: string, object, or array) plus typed `questions`; it returns decisions your code branches on. It does not generate text. Every question in a request is evaluated independently and in parallel against the shared state — batching does not change answers.
+
+## Primitives
+
+| Type | Question | Answer fields |
+|---|---|---|
+| `noul` | Is this true? | `noul`: P(true), 0–1 |
+| `choice` | Which option? | `choice`, `probabilities` (full distribution), `confidence` |
+| `score` | Which level on an ordered rubric? | `score` (probability-weighted mean over levels), `legend`, `probabilities`, `confidence` |
+
+`confidence` is the model's self-assessed reliability — distinct from `probability`, and the signal you gate autonomous action on.
+
+## HTTP API
+
+```
+POST https://api.typesafe.ai/v1/systemone
+Authorization: Bearer $TYPESAFE_API_KEY
+Content-Type: application/json
+```
+
+Models: `jev-latest`, `jev-preview`, and pinned versions like `jev-1.13.0` (responses echo the exact model that answered — pin versions when you tune thresholds). Key: https://console.typesafe.ai/keys
+
+### Request
+
+```json
+{
+  "model": "jev-latest",
+  "state": { "message": "Hi, I've been trying to connect my Stripe account for 3 days..." },
+  "questions": {
+    "department": {
+      "type": "choice",
+      "instructions": "Which team should handle this",
+      "criteria": {
+        "billing": "Payment or subscription issues",
+        "technical": "Bugs or integration problems",
+        "sales": "Pricing or account questions"
+      }
+    },
+    "frustration": {
+      "type": "score",
+      "instructions": "How frustrated the customer appears",
+      "criteria": [
+        "Calm, just stating facts",
+        "Frustrated but civil",
+        "Very angry, strong language"
+      ]
+    },
+    "is_urgent": {
+      "type": "noul",
+      "instructions": "The message conveys urgency or time-sensitivity"
+    }
+  }
+}
+```
+
+Backtick a state path inside `instructions` (e.g. "Does `message` mention a duplicate charge?") to pin the question to a field.
+
+### Response
+
+```json
+{
+  "model": "jev-latest",
+  "answers": {
+    "department": {
+      "type": "choice",
+      "choice": "billing",
+      "probabilities": { "billing": 0.84, "technical": 0.159, "sales": 0.001 },
+      "confidence": 0.596
+    },
+    "frustration": {
+      "type": "score",
+      "score": 1.035,
+      "legend": { "0": "Calm, just stating facts", "1": "Frustrated but civil", "2": "Very angry, strong language" },
+      "probabilities": { "0": 0.05, "1": 0.88, "2": 0.07 },
+      "confidence": 0.842
+    },
+    "is_urgent": { "type": "noul", "noul": 0.999 }
+  },
+  "usage": { "input_tokens": 312, "output_tokens": 48 }
+}
+```
+
+Structural guarantee: Jev cannot invent a fourth choice option — type-error rate on the label is 0 by construction.
+
+## SDKs
+
+**Python** (≥3.10): `pip install typesafe-sdk`
+
+```python
+from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
+
+client = TypeSafeClient()  # reads TYPESAFE_API_KEY
+r = client.system_one(
+    state=ticket_text,
+    questions={
+        "is_urgent": Noul(instructions="The message conveys urgency"),
+        "department": Choice(instructions="Which team should handle this",
+                             criteria={"billing": "...", "technical": "...", "sales": "..."}),
+        "frustration": Score(instructions="How frustrated the customer appears",
+                             criteria=["Calm, just stating facts", "Frustrated but civil", "Very angry"]),
+    },
+)
+r.answers["department"].choice      # "billing"
+r.answers["frustration"].score      # 1.035
+r.answers["is_urgent"].noul         # 0.999
+```
+
+**JavaScript/TypeScript** (Node ≥20): `npm install @typesafe-ai/sdk` — `TypeSafeClient` plus `noul()` / `choice()` / `score()` helpers; Choice labels infer as TypeScript literal unions.
+
+**Vercel AI SDK ≥7.0.105**: provider `@ai-sdk/typesafe-ai` (or gateway `typesafe-ai/jev`) via `experimental_evaluate`; vocabulary differs — "boolean" instead of noul, answer field is `probability`, confidence lives in `providerMetadata.typesafe.confidence`.
+
+## Limits and errors
+
+- State + questions ≤ ~64K tokens; state + longest question ≤ ~32K tokens (~150K chars).
+- Choice: up to 255 options. Score: 2–10 levels. Text input only — no images/audio/video.
+- Errors: 401 bad key, 422 validation, 429/529 → retry with backoff. Early-access rate limits: ~250K tokens/sec, ~1,200 req/min.
+- Rate limits and version pins matter for threshold-tuned code — re-check the docs when generating final integration code.
+
+## Pricing and latency (as of 2026-09, early access)
+
+- Input: **$0.042 per million tokens**. Output tokens: **free**.
+- 70–500 ms end-to-end, ~100 ms typical, roughly flat in number of questions.
+- Vendor headline vs frontier LLMs on decision workloads: ~193× faster, ~444× cheaper (their ceiling numbers — treat as directional).
+- For savings math, price the incumbent LLM at its real list price (e.g. ~$3–15/M input, ~$15–75/M output depending on model class), not at Jev's marketing comparison.
+
+## Known jagged edges — never move these to Jev
+
+- Text generation of any kind: summaries, drafts, code, translations.
+- Arithmetic, counting, exact comparison (fails things like hex-color similarity).
+- Date/time reasoning (treats dates as text).
+- Interpolating a Score of 1.4 as "40% between levels" — use scores for thresholds and ranking only.
+- Extraction by free recall: Jev picks from candidates, it doesn't name them. Find candidates with regex/LLM, let Jev choose.

package/skill/jev-audit/scripts/scan.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// jev-audit scanner — local, zero-dependency inventory of LLM call sites.
+// Usage: node scan.js <path>   (writes jev-scan.json in cwd, prints a summary)
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', 'vendor', '.next', '.nuxt',
+  'coverage', '.venv', 'venv', '__pycache__', '.cache', '.terraform', '.idea',
+  '.vscode', 'target', '.gradle', 'bower_components', '.pytest_cache',
+  '.mypy_cache', '.circleci', '.github',
+  // agent-harness config + project-local installed skills are not app call sites
+  '.agents', '.claude', '.codex', '.cursor', '.zcode', '.grok', '.agy', '.pi',
+]);
+const EXTS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py', '.rb', '.go', '.rs',
+  '.java', '.kt', '.swift', '.php', '.cs', '.sh', '.yaml', '.yml', '.toml', '.json',
+]);
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+
+const PATTERNS = [
+  // SDK imports / clients
+  { id: 'openai', category: 'sdk', re: /(?:from\s+|import\s+[\w{},\s]*from\s+|require\(\s*)['"]openai[/'"]|@azure\/openai|new\s+OpenAI\b/ },
+  { id: 'anthropic', category: 'sdk', re: /@anthropic-ai\/sdk|(?:from\s+|require\(\s*)['"]@?anthropic(?:-ai)?[/'"]/ },
+  { id: 'google-ai', category: 'sdk', re: /@google\/generative-ai|google\.generativeai|@google-cloud\/vertexai|vertexai/ },
+  { id: 'vercel-ai', category: 'sdk', re: /@ai-sdk\/|from\s+['"]ai['"]|require\(\s*['"]ai['"]\s*\)/ },
+  { id: 'langchain', category: 'sdk', re: /langchain/ },
+  { id: 'llamaindex', category: 'sdk', re: /llamaindex|llama_index/ },
+  { id: 'mistral', category: 'sdk', re: /(?:from\s+|require\(\s*)['"]mistralai?[/'"]/ },
+  { id: 'cohere', category: 'sdk', re: /(?:from\s+|require\(\s*)['"]cohere[-_\/]/ },
+  { id: 'groq', category: 'sdk', re: /(?:from\s+|require\(\s*)['"]groq(?:-sdk)?[/'"]/ },
+  { id: 'xai', category: 'sdk', re: /@xai\/sdk|(?:from\s+|require\(\s*)['"]@?xai[/'"]/ },
+  { id: 'ollama', category: 'sdk', re: /['"]ollama(?:\/|-sdk)?[/'"]|from\s+['"]ollama[/'"]/ },
+  { id: 'bedrock', category: 'sdk', re: /@aws-sdk\/client-bedrock|bedrock-runtime|bedrock\.Runtime/ },
+  // raw HTTP endpoints
+  { id: 'openai', category: 'endpoint', re: /api\.openai\.com/ },
+  { id: 'anthropic', category: 'endpoint', re: /api\.anthropic\.com/ },
+  { id: 'google-ai', category: 'endpoint', re: /generativelanguage\.googleapis\.com/ },
+  { id: 'mistral', category: 'endpoint', re: /api\.mistral\.ai/ },
+  { id: 'cohere', category: 'endpoint', re: /api\.cohere\.(?:ai|com)/ },
+  { id: 'groq', category: 'endpoint', re: /api\.groq\.com/ },
+  { id: 'xai', category: 'endpoint', re: /api\.x\.ai\b/ },
+  { id: 'together', category: 'endpoint', re: /api\.together\.xyz/ },
+  { id: 'openrouter', category: 'endpoint', re: /openrouter\.ai\/api/ },
+  { id: 'deepseek', category: 'endpoint', re: /api\.deepseek\.com/ },
+  // API keys in env/config
+  { id: 'env-keys', category: 'env-key', re: /\b(?:OPENAI|ANTHROPIC|GEMINI|GOOGLE|GOOGLE_AI|GOOGLE_VERTEX|MISTRAL|GROQ|XAI|COHERE|TOGETHER|DEEPSEEK|OPENROUTER|PERPLEXITY|FIREWORKS)_API_KEY\b/ },
+  // call-site shapes
+  { id: 'chat-completion', category: 'call', re: /chat\.completions\.create|completions\.create|responses\.create/ },
+  { id: 'message-create', category: 'call', re: /\.messages\.create|client\.respond\b/ },
+  { id: 'generate-content', category: 'call', re: /generateContent|generate_content/ },
+  { id: 'chain-class', category: 'call', re: /ChatOpenAI|ChatAnthropic|AzureChatOpenAI|ChatGoogleGenerativeAI|GoogleGenerativeAI/ },
+  { id: 'llm-invoke', category: 'call', re: /\bllm\s*\.\s*(?:invoke|predict|call)\b|\.invoke\(\s*['"]/ },
+  { id: 'agent-run', category: 'call', re: /\bagent\s*\(/ },
+  { id: 'llm-params', category: 'param', re: /\bmax_tokens\b|\btemperature\s*[:=]/ },
+  // already on Jev
+  { id: 'jev', category: 'jev', re: /@typesafe-ai\/sdk|typesafe_sdk|api\.typesafe\.ai|typesafe-ai|system_one|systemone/ },
+];
+
+const DECISION_RE = /classif|categor|intent|route|routing|label|spam|toxic|moderat|guardrail|jailbreak|sentiment|urgen|prioriti|triage|severity|relevan|rating|verif|validat|is_|should_|detect|screen|escalat|fraud|disput|refund|complaint|lead\b|qualif/i;
+
+function* walk(dir, depth) {
+  if (depth > 14) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) yield* walk(full, depth + 1);
+    } else if (e.isFile()) {
+      const base = e.name;
+      const ext = path.extname(base).toLowerCase();
+      if (EXTS.has(ext) || base.startsWith('.env') || base === 'env') yield full;
+    }
+  }
+}
+
+function looksBinary(buf) {
+  return buf.slice(0, 4096).includes(0);
+}
+
+function scanFile(file, root) {
+  let buf;
+  try {
+    const st = fs.statSync(file);
+    if (st.size > MAX_FILE_BYTES) return [];
+    buf = fs.readFileSync(file);
+  } catch { return []; }
+  if (looksBinary(buf)) return [];
+  const lines = buf.toString('utf8').split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    for (const p of PATTERNS) {
+      if (!p.re.test(line)) continue;
+      const window = (lines[i - 2] || '') + '\n' + line + '\n' + (lines[i + 1] || '') + '\n' + (lines[i + 2] || '');
+      hits.push({
+        file: path.relative(root, file) || file,
+        line: i + 1,
+        category: p.category,
+        id: p.id,
+        snippet: line.trim().slice(0, 160),
+        decisionShaped: DECISION_RE.test(line) || DECISION_RE.test(window),
+      });
+      break; // one record per line, first matching pattern
+    }
+  }
+  return hits;
+}
+
+function runScan(rootDir) {
+  const root = path.resolve(rootDir || '.');
+  const hits = [];
+  let filesScanned = 0;
+  for (const file of walk(root, 0)) {
+    if (path.basename(file) === 'jev-scan.json') continue;
+    filesScanned++;
+    hits.push(...scanFile(file, root));
+  }
+  const bySdk = {};
+  const byCategory = {};
+  const byFile = {};
+  for (const h of hits) {
+    byCategory[h.category] = (byCategory[h.category] || 0) + 1;
+    if (h.category !== 'param') bySdk[h.id] = (bySdk[h.id] || 0) + 1;
+    byFile[h.file] = (byFile[h.file] || 0) + 1;
+  }
+  return {
+    scanner: 'jev-audit',
+    version: '0.1.0',
+    scannedAt: new Date().toISOString(),
+    root,
+    filesScanned,
+    summary: {
+      touchpoints: hits.filter((h) => h.category !== 'jev').length,
+      decisionShaped: hits.filter((h) => h.decisionShaped && h.category !== 'jev' && h.category !== 'param').length,
+      alreadyJev: hits.filter((h) => h.category === 'jev').length,
+      byCategory,
+      bySdk,
+      byFile,
+    },
+    hits,
+  };
+}
+
+function printSummary(result) {
+  const s = result.summary;
+  console.log(`\njev-audit scan — ${result.root}`);
+  console.log(`files scanned: ${result.filesScanned}   llm touchpoints: ${s.touchpoints}   decision-shaped: ${s.decisionShaped}${s.alreadyJev ? `   already-jev: ${s.alreadyJev}` : ''}`);
+  const sdks = Object.entries(s.bySdk).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join(', ');
+  if (sdks) console.log(`signals: ${sdks}`);
+  const files = Object.entries(s.byFile).sort((a, b) => b[1] - a[1]).slice(0, 8);
+  if (files.length) {
+    console.log('\nhottest files:');
+    for (const [f, n] of files) console.log(`  ${String(n).padStart(3)}  ${f}`);
+  }
+  const candidates = result.hits.filter((h) => h.decisionShaped && (h.category === 'call' || h.category === 'sdk'));
+  if (candidates.length) {
+    console.log('\ndecision-shaped call sites (prime Jev candidates):');
+    for (const c of candidates.slice(0, 8)) console.log(`  ${c.file}:${c.line}  [${c.id}]  ${c.snippet.slice(0, 80)}`);
+  }
+}
+
+if (require.main === module) {
+  const target = process.argv[2] || '.';
+  const result = runScan(target);
+  printSummary(result);
+  const out = path.join(process.cwd(), 'jev-scan.json');
+  fs.writeFileSync(out, JSON.stringify(result, null, 2));
+  console.log(`\n→ full inventory: ${out}`);
+  console.log('→ next: run the jev-audit skill in your agent ("audit this repo with jev-audit") for tiers, savings, and architecture.');
+}
+
+module.exports = { runScan, printSummary };