trooth 0.2.0 → 0.3.0

package/README.md

@@ -1,12 +1,13 @@
 # trooth
 
-The trust network your terminal can check. Read any company's **witnessed** trust
-standing from the [Trooth Network](https://trooth.co). Identity, security, privacy,
-AI practices, and more, each witnessed, signed, and dated. It also scans your own Terraform
-plans against SOC 2, ISO 27001, GDPR, HIPAA, NIST AI RMF, and the EU AI Act.
+The trust network your terminal can check. Read any company's **witnessed** record on
+the [Trooth Network](https://trooth.co): identity, security, privacy, AI practices and
+more, each witnessed, signed and dated. It also scans your own Terraform plans against
+SOC 2, ISO 27001, GDPR, HIPAA, NIST AI RMF and the EU AI Act.
 
 **`check` reads only public, already-published records. No key, no account.**
 **`scan` is advisory and report-only. Trooth never applies changes to your infrastructure.**
+**Trooth publishes facts and counts about a company, never one number that sums it up.**
 
 ## Install / run
 
@@ -19,16 +20,37 @@ npm i -g trooth
 trooth check trooth.co
 ```
 
+Requires Node 18+ (uses built-in `fetch`).
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `trooth check <domain>` | Reads a company's witnessed standing from the live Trooth Network (`GET https://api.trooth.co/directory/api/vendors`) and prints the score, the per-discipline breakdown, live probes, attestations, and the badge / scan IDs you can verify. Returns an honest "not listed yet" when a company has no published standing. |
-| `trooth scan <plan>` | Posts your `terraform show -json` plan to Trooth Pre-Flight (`POST https://api.trooth.co/v1/preflight`) and prints the verdict, score, and findings. Accepts a JSON file or a binary `.tfplan` (it runs `terraform show -json` for you). |
-| `trooth eu ...` | Pushes EU AI Act evidence (datasets, evals, drift) into Trooth from CI/CD. Needs a session token or company id. |
-| `trooth lint [path]` | Local, read-only IaC drift check. Never transmits your code. |
+| `trooth check <domain>` | Reads a company's witnessed record from the live Trooth Network (`GET https://api.trooth.co/directory/api/vendors`) and prints whether it is listed, when it was witnessed and first published, the live-probe and attestation counts, the badge / scan ids, and the signature and key id you can verify. Prints an honest "not listed yet" when a company has no published record. |
+| `trooth scan <plan>` | Posts your `terraform show -json` plan to Trooth Pre-Flight (`POST https://api.trooth.co/v1/preflight`) and prints the verdict, the pass / fail / n-a counts, and the findings. Accepts a JSON file or a binary `.tfplan` (it runs `terraform show -json` for you). |
+| `trooth eu ...` | Pushes EU AI Act evidence (`--datasets`, `--evals`, `--drift`, each a JSON file) into Trooth from CI/CD. Needs `--token` / `TROOTH_TOKEN` or `--company` / `TROOTH_COMPANY`. |
+| `trooth lint [path]` | Local, read-only IaC drift check that runs the `@trooth/os` linter if it is installed. Never transmits your code. `@trooth/os` is not yet on the npm registry, so today this exits 3 with a message saying exactly that. |
 | `trooth --help` / `--version` | Help / version. |
 
+## Flags
+
+- `--json` (`check`, `scan`, `eu`): stdout carries exactly one JSON document and nothing
+  else; every diagnostic goes to stderr. On an error the document is
+  `{"ok": false, "error": "...", "exit": N}`.
+- `--strict` (`scan` only): exit 1 if any check fails. Default is advisory: exit 0.
+
+Any other flag is a usage error (exit 2) that names the flag and lists the known ones.
+There is no `--fail-on`, no `--all`, no sort or filter switch.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | ok: company listed; scan ran (no strict failures); help / version |
+| 1 | finding: company not listed; `scan --strict` and at least one check failed |
+| 2 | usage error: missing argument, unknown flag or command, unreadable file |
+| 3 | Trooth unreachable, non-2xx response, malformed response, or `@trooth/os` missing |
+
 ## Examples
 
 ```bash
@@ -38,42 +60,76 @@ trooth check trooth.co
 ```
 Trooth Network // witnessed · public · read-only //
 Trooth, LLC   trooth.co
-Standing: 91/100   Listed   witnessed 2026-08-30
-
-By discipline
-  Legal          ██████████  20/20
-  Security       ████████░░  16/20
-  AI governance  ██████████  19/20
-  Business       █████████░  18/20
-  IP             █████████░  18/20
+Standing: listed and witnessed   witnessed 2026-08-30   first published 2026-08-01
 
 Live probes 64/65     Attestations 27/35
-Badge bronze_rw_...   Scan rw_...
+Probes are checks Trooth read for itself. Attestations are the company's own declarations.
+They are counts, reported apart on purpose. Trooth never adds them up into one number.
+Badge bronze_rw_...   Scan rw_...   Key ed25519-2026-01
 
-A witnessed, point-in-time reading of public evidence. Not a certification.
+Recent witness events
+  • 2026-08-30  rewitnessed  64 of 65 live probes re-run
+
+A witnessed, point-in-time reading of public evidence. Not a certification. Not one number.
+Full record: https://trooth.co/network/trooth.co   ·   Signing keys: https://api.trooth.co/public/keys
 ```
 
 ```bash
-# For scripting: raw JSON, exit code 1 when a company is not listed:
-trooth check acme.com --json
+# For scripting: one JSON document on stdout, exit 1 when a company is not listed.
+trooth check trooth.co --json
 ```
 
-## Flags
+```json
+{
+  "domain": "trooth.co",
+  "listed": true,
+  "company_name": "Trooth, LLC",
+  "witnessed_at": "2026-08-30T00:00:00Z",
+  "first_published_at": "2026-08-01T00:00:00Z",
+  "badge_id": "bronze_rw_...",
+  "scan_id": "rw_...",
+  "probes": { "passed": 64, "total": 65 },
+  "attested": { "passed": 27, "total": 35 },
+  "events": [ { "type": "rewitnessed", "at": "2026-08-30T00:00:00Z", "detail": "64 of 65 live probes re-run" } ],
+  "receipt_signature": "...",
+  "authority_key_id": "ed25519-2026-01",
+  "verify_keys": "https://api.trooth.co/public/keys",
+  "record_url": "https://trooth.co/network/trooth.co"
+}
+```
+
+Those are the only fields `check --json` emits. Anything else the feed happens to carry
+is dropped on the way out, so a script written against this shape keeps working.
+
+```bash
+terraform show -json plan.tfplan > plan.json
+trooth scan plan.json            # advisory, exit 0
+trooth scan plan.json --strict   # exit 1 if any check fails
+```
 
-- `--json`: print the raw JSON record instead of the formatted view.
-- `--strict`: scan only, exit non-zero if there are findings (default: exit 0, advisory).
+```
+Trooth Pre-Flight // advisory · report-only //
+Verdict: WARN   pass 5 · fail 1 · n/a 2
+
+1 finding(s):
+
+  ● MEDIUM  S3 bucket allows public read
+         ↳ SOC2 CC6.1, ISO 27001 A.8.3
+
+Advisory. Analyzes declared infrastructure intent, not live production state. Trooth never applies changes.
+```
 
 ## Notes
 
 - `check` reads only the **public** witness directory. There is no key and no account, and
   it never sends anything about you. It is a read.
-- A "not listed" result is not a judgement. It means no witnessed standing has been
+- A "not listed" result is not a judgement. It means no witnessed record has been
   published for that domain yet. A company gets witnessed by listing at
   <https://trooth.co/get-started>.
 - `scan` sends only your **declared plan** to the Pre-Flight API; nothing is written back,
   and Trooth never touches live infrastructure.
 - Set `TROOTH_API` to point at a different base URL (defaults to `https://api.trooth.co`).
-- Requires Node 18+ (uses built-in `fetch`).
+- Set `NO_COLOR=1` to disable ANSI colour. Colour is already off when stdout is not a TTY.
 
 ## Use it from an AI assistant
 

package/bin/trooth.mjs

@@ -3,8 +3,8 @@
 // Copyright (c) 2026 Trooth, LLC. All rights reserved.
 //
 // Commands:
-//   trooth check <domain>  Read a company's witnessed trust standing from the
-//                          public Trooth Network (read-only, no key, no account).
+//   trooth check <domain>  Read a company's witnessed record from the public Trooth
+//                          Network (read-only, no key, no account).
 //   trooth scan <plan>     Send a Terraform plan to Trooth Pre-Flight (advisory, report-only).
 //                          <plan> may be a `terraform show -json` JSON file, OR a binary
 //                          .tfplan (the CLI will run `terraform show -json` for you).
@@ -15,48 +15,174 @@
 // `check` reads only PUBLIC, already-published witness records. `scan` is ADVISORY and
 // REPORT-ONLY: Trooth never applies changes to your infrastructure, and the scan posts
 // only your declared plan. Trooth automates. Trooth never signs for you.
+//
+// TROOTH DOES NOT SCORE COMPANIES. This binary prints no company score, no tier, no
+// grade, no rank, and no percentage of trust, in any mode. It prints facts: listed or
+// not, witnessed on what date, how many live probes and attestations were read, and
+// the ids and signature you can verify yourself. If an upstream feed still carries a
+// number of that kind, scrub() below drops it before anything reaches stdout.
+//
+// Exit codes (stable, for scripts):
+//   0  ok                      (listed; scan ran with no strict failure; help/version)
+//   1  finding                 (domain not listed; `scan --strict` with failing checks)
+//   2  usage error             (missing argument, unknown flag or command, unreadable file)
+//   3  network/upstream error  (Trooth unreachable, non-2xx, malformed response, missing linter)
+//
+// With --json, stdout carries exactly one JSON document and nothing else. Every
+// diagnostic goes to stderr.
 
 import { readFileSync, existsSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
 
 const API = process.env.TROOTH_API || 'https://api.trooth.co';
-const J='\x1b[32m', D='\x1b[2m', B='\x1b[1m', R='\x1b[31m', A='\x1b[33m', C='\x1b[36m', X='\x1b[0m';
 const require = createRequire(import.meta.url);
-let VERSION = '0.2.0';
+let VERSION = '0.3.0';
 try { VERSION = require('../package.json').version; } catch {}
 
+const EXIT = { OK: 0, FINDING: 1, USAGE: 2, UPSTREAM: 3 };
+
+// Colour only when stdout is a TTY and NO_COLOR is unset, so piped output is clean.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code) => (useColor ? code : '');
+const J = c('\x1b[32m'), D = c('\x1b[2m'), B = c('\x1b[1m'), R = c('\x1b[31m'), A = c('\x1b[33m'), C = c('\x1b[36m'), X = c('\x1b[0m');
+
 const argv = process.argv.slice(2);
 const cmd = argv[0];
+const asJson = argv.includes('--json');
+
+/* ------------------------------------------------------------- output ---- */
+
+function out(s) { process.stdout.write(s + '\n'); }
+function diag(s) { process.stderr.write(s + '\n'); }
+function emitJson(obj) { out(JSON.stringify(obj, null, 2)); }
+
+/** Print a diagnostic to stderr and, in --json mode, one machine-readable error
+ *  document to stdout, then exit with the given code. */
+function fail(code, message, extra = {}) {
+  diag(`${R}error${X} ${message}`);
+  if (asJson) emitJson({ ok: false, error: message, exit: code, ...extra });
+  process.exit(code);
+}
+
+/** Keys that would carry a company score, tier, grade, rank, rating or percentage
+ *  of trust. Nothing under these names is ever printed, in any mode, no matter
+ *  what an upstream feed sends. `rate` is matched only as a whole key so that
+ *  keys like generatedAt survive. */
+const BANNED_KEY = /score|tier|grade|rank|rating|level|percent|^rate$/i;
+
+/** Recursively drop banned keys from any JSON-ish value. */
+function scrub(value) {
+  if (Array.isArray(value)) return value.map(scrub);
+  if (value && typeof value === 'object') {
+    const clean = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (BANNED_KEY.test(k)) continue;
+      clean[k] = scrub(v);
+    }
+    return clean;
+  }
+  return value;
+}
+
+/* --------------------------------------------------------------- args ---- */
+
+const FLAGS = {
+  check: { bool: ['--json'], value: [] },
+  scan:  { bool: ['--json', '--strict'], value: [] },
+  eu:    { bool: ['--json'], value: ['--token', '--company', '--datasets', '--evals', '--drift'] },
+  lint:  { bool: [], value: [] },
+};
+
+/** Parse argv[1..] for one command. Unknown flags are a usage error (exit 2), so a
+ *  typo or a flag from an old README never silently becomes a filename. */
+function parseArgs(command) {
+  const spec = FLAGS[command];
+  const flags = {};
+  const positional = [];
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { positional.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const [name, inlineVal] = a.split('=', 2);
+      if (spec.bool.includes(name)) { flags[name] = true; continue; }
+      if (spec.value.includes(name)) {
+        const v = inlineVal !== undefined ? inlineVal : argv[++i];
+        if (v === undefined || v.startsWith('--')) fail(EXIT.USAGE, `${name} needs a value.`);
+        flags[name] = v; continue;
+      }
+      const known = [...spec.bool, ...spec.value];
+      fail(EXIT.USAGE, `unknown flag ${name} for \`trooth ${command}\`. ` +
+        (known.length ? `Known flags: ${known.join(', ')}.` : `\`trooth ${command}\` takes no flags.`) +
+        ` Run \`trooth --help\`.`);
+    } else if (a.startsWith('-') && a.length > 1) {
+      fail(EXIT.USAGE, `unknown flag ${a} for \`trooth ${command}\`. Run \`trooth --help\`.`);
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+/* --------------------------------------------------------------- help ---- */
 
-function help() {
-  console.log(`
+function helpText() {
+  return `
 ${J}${B}trooth${X} ${D}v${VERSION} · the trust network your terminal can check${X}
 
 ${B}Usage${X}
-  trooth check <domain>     Read a company's witnessed standing on the Trooth Network
+  trooth check <domain>     Read a company's witnessed record on the Trooth Network
   trooth scan <plan>        Scan a Terraform plan via Trooth Pre-Flight (advisory)
+  trooth eu ...             Push EU AI Act evidence from CI/CD (needs a token)
   trooth lint [path]        Local read-only IaC drift check
   trooth --help | --version
 
 ${B}Examples${X}
   trooth check stripe.com                ${D}# read a company's witnessed record${X}
-  trooth check trooth.co --json          ${D}# raw JSON, for scripting${X}
+  trooth check trooth.co --json          ${D}# one JSON document on stdout, for scripting${X}
   terraform show -json plan.tfplan > plan.json && trooth scan plan.json
+  trooth scan plan.json --strict         ${D}# exit 1 if any check fails${X}
 
 ${B}Flags${X}
-  --json                    Print raw JSON instead of the formatted view
-  --strict                  (scan) exit non-zero if findings exist (default: advisory, exit 0)
+  --json                    (check, scan, eu) machine-readable JSON on stdout; diagnostics on stderr
+  --strict                  (scan) exit 1 if failing checks exist (default: advisory, exit 0)
+
+${B}Exit codes${X}
+  0 ok   1 finding (not listed, or strict failures)   2 usage error   3 Trooth unreachable
 
 ${D}check reads only public, already-published witness records. No key, no account.
+Trooth publishes facts and counts about a company, never one number that sums it up.
 scan is advisory and report-only. Trooth automates. Trooth never signs for you.${X}
-`);
+`;
+}
+
+/* -------------------------------------------------------------- fetch ---- */
+
+/** GET/POST with the CLI user-agent. Any failure to reach Trooth, any non-2xx, and any
+ *  unparseable body is an upstream error (exit 3), never a finding. */
+async function callTrooth(path, init, what) {
+  let res;
+  try {
+    res = await fetch(`${API}${path}`, {
+      ...init,
+      headers: { accept: 'application/json', 'user-agent': `trooth-cli/${VERSION}`, ...(init && init.headers) },
+    });
+  } catch (e) {
+    fail(EXIT.UPSTREAM, `could not reach ${what} at ${API}: ${e && e.message ? e.message : e}`);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    fail(EXIT.UPSTREAM, `${what} returned HTTP ${res.status}.${body ? ' ' + body.slice(0, 300).replace(/\s+/g, ' ') : ''}`, { http_status: res.status });
+  }
+  try { return await res.json(); }
+  catch { fail(EXIT.UPSTREAM, `${what} returned a response that is not JSON.`); }
 }
 
 /* --------------------------------------------------------------- check ---- */
 
 /** Normalize a domain the way the Trooth Network does: strip scheme, path,
- *  leading www, case, and trailing slash. */
+ *  leading www, case, and trailing dot. */
 function normalizeDomain(input) {
   if (!input) return '';
   let s = String(input).trim().toLowerCase();
@@ -67,32 +193,6 @@ function normalizeDomain(input) {
   return s;
 }
 
-const CATEGORY_LABELS = {
-  legal: 'Legal',
-  security: 'Security',
-  ai: 'AI governance',
-  business: 'Business',
-  ip: 'IP',
-};
-
-/** Pull a 0..100 score out of the feed's score field (object or number). */
-function scorePct(score) {
-  if (score == null) return null;
-  if (typeof score === 'number') return Math.round(score);
-  if (typeof score === 'object') {
-    if (typeof score.rate === 'number') return Math.round(score.rate * 100);
-    if (typeof score.passed === 'number' && typeof score.total === 'number' && score.total > 0)
-      return Math.round((score.passed / score.total) * 100);
-  }
-  return null;
-}
-
-function bar(passed, total) {
-  if (!total) return '';
-  const filled = Math.round((passed / total) * 10);
-  return '█'.repeat(filled) + '░'.repeat(10 - filled);
-}
-
 function fmtDate(iso) {
   if (!iso) return '';
   const d = new Date(iso);
@@ -100,165 +200,177 @@ function fmtDate(iso) {
   return d.toISOString().slice(0, 10);
 }
 
+function count(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  if (typeof obj.passed !== 'number' || typeof obj.total !== 'number') return null;
+  return { passed: obj.passed, total: obj.total };
+}
+
+/** The public record, projected onto the fields this CLI vouches for. Unknown fields
+ *  from the feed are not carried, so a field added upstream later cannot reintroduce
+ *  a number Trooth does not publish. Then scrubbed anyway, belt and braces. */
+function projectRecord(v, domain) {
+  const events = Array.isArray(v.events)
+    ? v.events.filter((e) => e && e.type).map((e) => ({ type: String(e.type), at: e.at, detail: e.detail }))
+    : [];
+  const rec = {
+    domain,
+    listed: true,
+    company_name: v.company_name || domain,
+    witnessed_at: v.passed_at || null,
+    first_published_at: v.first_published_at || null,
+    badge_id: v.badge_id || null,
+    scan_id: v.scan_id || null,
+    probes: count(v.probes),
+    attested: count(v.attested),
+    events,
+    receipt_signature: v.receipt_signature || null,
+    authority_key_id: v.authority_key_id || null,
+    verify_keys: `${API}/public/keys`,
+    record_url: `https://trooth.co/network/${encodeURIComponent(domain)}`,
+  };
+  if (v.category) rec.category = String(v.category);
+  if (v.description) rec.description = String(v.description);
+  return scrub(rec);
+}
+
 async function check() {
-  const domainArg = argv.find((a, i) => i > 0 && !a.startsWith('--'));
-  const asJson = argv.includes('--json');
-  const domain = normalizeDomain(domainArg);
-  if (!domain) {
-    console.error(`${R}error${X} missing <domain>. Try: trooth check stripe.com`);
-    process.exit(2);
-  }
+  const { positional } = parseArgs('check');
+  if (positional.length > 1) fail(EXIT.USAGE, `check takes one <domain>, got: ${positional.join(' ')}`);
+  const domain = normalizeDomain(positional[0]);
+  if (!domain) fail(EXIT.USAGE, 'missing <domain>. Try: trooth check stripe.com');
 
-  let res;
-  try {
-    res = await fetch(`${API}/directory/api/vendors`, {
-      headers: { accept: 'application/json', 'user-agent': `trooth-cli/${VERSION}` },
-    });
-  } catch (e) {
-    console.error(`${R}error${X} could not reach the Trooth Network at ${API}: ${e.message}`);
-    process.exit(1);
-  }
-  if (!res.ok) {
-    console.error(`${R}error${X} the Trooth Network returned HTTP ${res.status}.`);
-    process.exit(1);
-  }
-  let data;
-  try { data = await res.json(); } catch { data = {}; }
+  const data = await callTrooth('/directory/api/vendors', { method: 'GET' }, 'the Trooth Network');
   const vendors = Array.isArray(data && data.vendors) ? data.vendors : [];
   const vendor = vendors.find((v) => v && normalizeDomain(v.domain) === domain) || null;
 
-  if (asJson) {
-    console.log(JSON.stringify(vendor || { domain, listed: false }, null, 2));
-    process.exit(vendor ? 0 : 1);
-  }
-
   if (!vendor) {
-    console.log(`\n${B}${domain}${X} ${D}//${X} ${A}not listed on the Trooth Network yet${X}`);
-    console.log(`\n${D}No witnessed standing has been published for this domain. That is not a`);
-    console.log(`judgement. It simply has not been witnessed. A company gets witnessed by`);
-    console.log(`listing at ${X}${C}https://trooth.co/get-started${X}${D}: the scan reads its public surface and`);
-    console.log(`publishes a signed, dated standing that anyone can check.${X}\n`);
-    process.exit(1);
-  }
-
-  const pct = scorePct(vendor.score);
-  const name = vendor.company_name || domain;
-  const tier = vendor.tier ? vendor.tier[0].toUpperCase() + vendor.tier.slice(1) : 'Listed';
-  const when = fmtDate(vendor.passed_at);
-
-  console.log(`\n${J}${B}Trooth Network${X} ${D}// witnessed · public · read-only //${X}`);
-  console.log(`${B}${name}${X}   ${C}${domain}${X}`);
-  const scoreStr = pct == null ? `${D}not yet scored${X}` : `${B}${pct}/100${X}`;
-  console.log(`Standing: ${scoreStr}   ${J}${tier}${X}${when ? `   ${D}witnessed ${when}${X}` : ''}`);
-
-  // Categories (object keyed by discipline).
-  const cats = vendor.categories;
-  if (cats && typeof cats === 'object' && !Array.isArray(cats)) {
-    console.log(`\n${B}By discipline${X}`);
-    for (const key of ['legal', 'security', 'ai', 'business', 'ip']) {
-      const c = cats[key];
-      if (!c || typeof c.total !== 'number') continue;
-      const label = (CATEGORY_LABELS[key] || key).padEnd(14);
-      const r = c.total > 0 ? c.passed / c.total : 0;
-      const col = r >= 0.9 ? J : r >= 0.5 ? A : R;
-      console.log(`  ${label} ${col}${bar(c.passed, c.total)}${X}  ${String(c.passed).padStart(2)}/${c.total}`);
+    if (asJson) {
+      emitJson({ domain, listed: false, record_url: `https://trooth.co/network/${encodeURIComponent(domain)}` });
+    } else {
+      out(`\n${B}${domain}${X} ${D}//${X} ${A}not listed on the Trooth Network yet${X}`);
+      out(`\n${D}No witnessed record has been published for this domain. That is not a`);
+      out(`judgement. It simply has not been witnessed. A company gets witnessed by`);
+      out(`listing at ${X}${C}https://trooth.co/get-started${X}${D}: the scan reads its public surface and`);
+      out(`publishes a signed, dated record that anyone can check.${X}\n`);
     }
+    process.exit(EXIT.FINDING);
   }
 
+  const rec = projectRecord(vendor, domain);
+  if (asJson) { emitJson(rec); process.exit(EXIT.OK); }
+
+  const when = fmtDate(rec.witnessed_at);
+  const since = fmtDate(rec.first_published_at);
+  out(`\n${J}${B}Trooth Network${X} ${D}// witnessed · public · read-only //${X}`);
+  out(`${B}${rec.company_name}${X}   ${C}${domain}${X}`);
+  out(`Standing: ${J}listed and witnessed${X}` +
+      (when ? `   ${D}witnessed ${when}${X}` : `   ${D}date not published${X}`) +
+      (since ? `   ${D}first published ${since}${X}` : ''));
+
   const line = [];
-  if (vendor.probes && typeof vendor.probes.total === 'number')
-    line.push(`${B}Live probes${X} ${vendor.probes.passed}/${vendor.probes.total}`);
-  if (vendor.attested && typeof vendor.attested.total === 'number')
-    line.push(`${B}Attestations${X} ${vendor.attested.passed}/${vendor.attested.total}`);
-  if (line.length) console.log(`\n${line.join('     ')}`);
+  if (rec.probes) line.push(`${B}Live probes${X} ${rec.probes.passed}/${rec.probes.total}`);
+  if (rec.attested) line.push(`${B}Attestations${X} ${rec.attested.passed}/${rec.attested.total}`);
+  if (line.length) {
+    out(`\n${line.join('     ')}`);
+    out(`${D}Probes are checks Trooth read for itself. Attestations are the company's own declarations.`);
+    out(`They are counts, reported apart on purpose. Trooth never adds them up into one number.${X}`);
+  }
 
   const ids = [];
-  if (vendor.badge_id) ids.push(`${D}Badge ${vendor.badge_id}${X}`);
-  if (vendor.scan_id) ids.push(`${D}Scan ${vendor.scan_id}${X}`);
-  if (ids.length) console.log(ids.join('   '));
-
-  const events = Array.isArray(vendor.events) ? vendor.events : [];
-  if (events.length) {
-    console.log(`\n${B}Recent witness events${X}`);
-    for (const e of events.slice(0, 3)) {
-      if (!e || !e.type) continue;
-      console.log(`  ${J}•${X} ${D}${fmtDate(e.at)}${X}  ${e.type.replace(/_/g, ' ')}${e.detail ? `${D}  ${e.detail}${X}` : ''}`);
+  if (rec.badge_id) ids.push(`${D}Badge ${rec.badge_id}${X}`);
+  if (rec.scan_id) ids.push(`${D}Scan ${rec.scan_id}${X}`);
+  if (rec.authority_key_id) ids.push(`${D}Key ${rec.authority_key_id}${X}`);
+  if (ids.length) out(ids.join('   '));
+
+  if (rec.events.length) {
+    out(`\n${B}Recent witness events${X}`);
+    for (const e of rec.events.slice(0, 3)) {
+      out(`  ${J}•${X} ${D}${fmtDate(e.at)}${X}  ${e.type.replace(/_/g, ' ')}${e.detail ? `${D}  ${e.detail}${X}` : ''}`);
     }
   }
 
-  console.log(`\n${D}A witnessed, point-in-time reading of public evidence. Not a certification.`);
-  console.log(`Full record and directory: ${X}${C}https://trooth.co/network${X}${D}   ·   Signing keys: ${API}/public/keys${X}\n`);
-  process.exit(0);
+  out(`\n${D}A witnessed, point-in-time reading of public evidence. Not a certification. Not one number.`);
+  out(`Full record: ${X}${C}${rec.record_url}${X}${D}   ·   Signing keys: ${rec.verify_keys}${X}\n`);
+  process.exit(EXIT.OK);
 }
 
 /* ---------------------------------------------------------------- scan ---- */
 
 function loadPlan(file) {
-  if (!file) { console.error(`${R}error${X} missing <plan> argument. Try: trooth scan ./plan.json`); process.exit(2); }
-  if (!existsSync(file)) { console.error(`${R}error${X} file not found: ${file}`); process.exit(2); }
-  // Try to read as JSON (a `terraform show -json` document).
+  if (!file) fail(EXIT.USAGE, 'missing <plan> argument. Try: trooth scan ./plan.json');
+  if (!existsSync(file)) fail(EXIT.USAGE, `file not found: ${file}`);
   let raw = '';
-  try { raw = readFileSync(file, 'utf8'); } catch (e) { console.error(`${R}error${X} cannot read ${file}: ${e.message}`); process.exit(2); }
+  try { raw = readFileSync(file, 'utf8'); } catch (e) { fail(EXIT.USAGE, `cannot read ${file}: ${e.message}`); }
   try { return JSON.parse(raw); } catch { /* not JSON, likely a binary .tfplan */ }
   // Fall back: ask Terraform to render the plan as JSON.
   try {
-    const out = execFileSync('terraform', ['show', '-json', file], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-    return JSON.parse(out);
-  } catch (e) {
-    console.error(`${R}error${X} ${file} is not JSON, and \`terraform show -json\` failed.`);
-    console.error(`${D}  Generate JSON first:  terraform show -json ${file} > plan.json  then  trooth scan plan.json${X}`);
-    process.exit(2);
+    const rendered = execFileSync('terraform', ['show', '-json', file], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    return JSON.parse(rendered);
+  } catch {
+    diag(`${D}  Generate JSON first:  terraform show -json ${file} > plan.json  then  trooth scan plan.json${X}`);
+    fail(EXIT.USAGE, `${file} is not JSON, and \`terraform show -json\` failed.`);
   }
 }
 
-async function scan() {
-  const file = argv.find((a, i) => i > 0 && !a.startsWith('--'));
-  const strict = argv.includes('--strict');
-  const asJson = argv.includes('--json');
-  const plan = loadPlan(file);
-
-  let res;
-  try {
-    res = await fetch(`${API}/v1/preflight`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', 'user-agent': `trooth-cli/${VERSION}` },
-      body: JSON.stringify({ plan }),
-    });
-  } catch (e) {
-    console.error(`${R}error${X} could not reach Trooth Pre-Flight at ${API}: ${e.message}`);
-    process.exit(1);
-  }
-  if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    console.error(`${R}error${X} Pre-Flight returned HTTP ${res.status}. ${body.slice(0, 300)}`);
-    process.exit(1);
-  }
-  const delta = await res.json();
-
-  if (asJson) { console.log(JSON.stringify(delta, null, 2)); process.exit(strict && (delta.summary?.fail > 0) ? 1 : 0); }
+/** Pre-Flight's response, minus anything that is not a finding, a count or a verdict.
+ *  The upstream still computes a 0..100 number for the plan; this CLI does not print it. */
+function projectPreflight(delta) {
+  const clean = scrub(delta || {});
+  const s = clean.summary || {};
+  return {
+    tool: clean.tool || 'trooth-preflight',
+    catalogVersion: clean.catalogVersion,
+    format: clean.format,
+    generatedAt: clean.generatedAt,
+    planResourceCount: clean.planResourceCount,
+    verdict: clean.verdict || 'reviewed',
+    summary: { pass: s.pass ?? 0, fail: s.fail ?? 0, notApplicable: s.notApplicable ?? 0, bySeverity: s.bySeverity },
+    findings: Array.isArray(clean.findings) ? clean.findings : [],
+    passedChecks: clean.passedChecks,
+    notApplicableChecks: clean.notApplicableChecks,
+    frameworkCoverage: clean.frameworkCoverage,
+    disclaimer: clean.disclaimer || 'Advisory. Analyzes declared infrastructure intent, not live production state. Trooth never applies changes.',
+  };
+}
 
-  const score = delta.score ?? '-';
-  const verdict = (delta.verdict || 'reviewed').toUpperCase();
-  const s = delta.summary || {};
-  console.log(`\n${J}${B}Trooth Pre-Flight${X} ${D}// advisory · report-only //${X}`);
-  console.log(`Verdict: ${B}${verdict}${X}   Score: ${B}${score}${typeof score === 'number' ? '/100' : ''}${X}   ` +
-              `${J}pass ${s.pass ?? 0}${X} · ${A}fail ${s.fail ?? 0}${X} · ${D}n/a ${s.notApplicable ?? 0}${X}`);
-  const findings = delta.findings || [];
+async function scan() {
+  const { flags, positional } = parseArgs('scan');
+  if (positional.length > 1) fail(EXIT.USAGE, `scan takes one <plan>, got: ${positional.join(' ')}`);
+  const strict = !!flags['--strict'];
+  const plan = loadPlan(positional[0]);
+
+  const delta = await callTrooth('/v1/preflight', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ plan }),
+  }, 'Trooth Pre-Flight');
+
+  const report = projectPreflight(delta);
+  const exitCode = strict && report.summary.fail > 0 ? EXIT.FINDING : EXIT.OK; // advisory by default
+
+  if (asJson) { emitJson(report); process.exit(exitCode); }
+
+  const s = report.summary;
+  out(`\n${J}${B}Trooth Pre-Flight${X} ${D}// advisory · report-only //${X}`);
+  out(`Verdict: ${B}${String(report.verdict).toUpperCase()}${X}   ` +
+      `${J}pass ${s.pass}${X} · ${A}fail ${s.fail}${X} · ${D}n/a ${s.notApplicable}${X}`);
+  const findings = report.findings;
   if (findings.length) {
-    console.log(`\n${B}${findings.length} finding(s):${X}\n`);
+    out(`\n${B}${findings.length} finding(s):${X}\n`);
     for (const f of findings.slice(0, 50)) {
-      const sev = (f.severity || '').toLowerCase();
+      const sev = String(f.severity || '').toLowerCase();
       const tag = sev === 'critical' || sev === 'high' ? `${R}● ${sev.toUpperCase()}${X}`
-                : sev === 'medium' ? `${A}● MEDIUM${X}` : `${D}● ${(sev||'LOW').toUpperCase()}${X}`;
-      console.log(`  ${tag}  ${B}${f.title || f.message || f.check || 'finding'}${X}`);
-      if (f.control || f.frameworks) console.log(`         ${J}↳${X} ${f.control || (Array.isArray(f.frameworks) ? f.frameworks.join(', ') : f.frameworks)}`);
+                : sev === 'medium' ? `${A}● MEDIUM${X}` : `${D}● ${(sev || 'LOW').toUpperCase()}${X}`;
+      out(`  ${tag}  ${B}${f.title || f.message || f.check || f.checkId || 'finding'}${X}`);
+      if (f.control || f.frameworks) out(`         ${J}↳${X} ${f.control || (Array.isArray(f.frameworks) ? f.frameworks.join(', ') : f.frameworks)}`);
     }
+    if (findings.length > 50) out(`  ${D}… ${findings.length - 50} more. Use --json for the full list.${X}`);
   } else {
-    console.log(`\n${J}✓ No findings in the declared plan.${X}`);
+    out(`\n${J}✓ No findings in the declared plan.${X}`);
   }
-  console.log(`\n${D}${delta.disclaimer || 'Advisory. Analyzes declared infrastructure intent, not live production state. Trooth never applies changes.'}${X}\n`);
-
-  process.exit(strict && (s.fail > 0) ? 1 : 0); // advisory by default: exit 0
+  out(`\n${D}${report.disclaimer}${X}\n`);
+  process.exit(exitCode);
 }
 
 /* ------------------------------------------------------------------ eu ---- */
@@ -266,42 +378,88 @@ async function scan() {
 //   trooth eu --token <t> --datasets ds.json --evals ev.json --drift dr.json
 // Each file is a JSON array. Auth: TROOTH_TOKEN env or --token (bearer or x-trooth-company).
 async function eu() {
-  const flag = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; };
-  const token = flag('--token') || process.env.TROOTH_TOKEN || '';
-  const company = flag('--company') || process.env.TROOTH_COMPANY || '';
-  if (!token && !company) { console.error(`${R}error${X} provide --token <session> or --company <id> (or TROOTH_TOKEN / TROOTH_COMPANY env).`); process.exit(2); }
-  const load = (f) => { if (!f) return undefined; try { return JSON.parse(readFileSync(f, 'utf8')); } catch (e) { console.error(`${R}error${X} cannot read ${f}: ${e.message}`); process.exit(2); } };
-  const body = { datasets: load(flag('--datasets')), evals: load(flag('--evals')), drift: load(flag('--drift')) };
-  if (!body.datasets && !body.evals && !body.drift) { console.error(`${R}error${X} provide at least one of --datasets/--evals/--drift <file.json>`); process.exit(2); }
-  const headers = { 'content-type': 'application/json', 'user-agent': `trooth-cli/${VERSION}` };
+  const { flags, positional } = parseArgs('eu');
+  if (positional.length) fail(EXIT.USAGE, `eu takes no positional arguments, got: ${positional.join(' ')}`);
+  const token = flags['--token'] || process.env.TROOTH_TOKEN || '';
+  const company = flags['--company'] || process.env.TROOTH_COMPANY || '';
+  if (!token && !company) fail(EXIT.USAGE, 'provide --token <session> or --company <id> (or TROOTH_TOKEN / TROOTH_COMPANY env).');
+  const load = (f) => {
+    if (!f) return undefined;
+    try { return JSON.parse(readFileSync(f, 'utf8')); } catch (e) { fail(EXIT.USAGE, `cannot read ${f}: ${e.message}`); }
+  };
+  const body = { datasets: load(flags['--datasets']), evals: load(flags['--evals']), drift: load(flags['--drift']) };
+  if (!body.datasets && !body.evals && !body.drift) fail(EXIT.USAGE, 'provide at least one of --datasets/--evals/--drift <file.json>');
+  const headers = { 'content-type': 'application/json' };
   if (token) headers['authorization'] = `Bearer ${token}`;
   if (company) headers['x-trooth-company'] = company;
-  let res;
-  try { res = await fetch(`${API}/v1/eu/ingest`, { method: 'POST', headers, body: JSON.stringify(body) }); }
-  catch (e) { console.error(`${R}error${X} could not reach Trooth at ${API}: ${e.message}`); process.exit(1); }
-  if (!res.ok) { console.error(`${R}error${X} HTTP ${res.status}. ${(await res.text().catch(()=> '')).slice(0,300)}`); process.exit(1); }
-  const out = await res.json();
-  console.log(`\n${J}${B}Trooth EU AI Act${X} ${D}// evidence ingested //${X}`);
-  console.log(`datasets ${B}${out.ingested?.datasets ?? 0}${X} · evals ${B}${out.ingested?.evals ?? 0}${X} · drift ${B}${out.ingested?.drift ?? 0}${X}`);
-  console.log(`\n${D}${out.disclaimer || 'Advisory. Trooth automates, computes, and documents; it never signs.'}${X}\n`);
-  process.exit(0);
+
+  const raw = await callTrooth('/v1/eu/ingest', { method: 'POST', headers, body: JSON.stringify(body) }, 'Trooth');
+  const result = scrub(raw || {});
+  const ingested = result.ingested || {};
+  const report = {
+    ingested: { datasets: ingested.datasets ?? 0, evals: ingested.evals ?? 0, drift: ingested.drift ?? 0 },
+    disclaimer: result.disclaimer || 'Advisory. Trooth automates, computes, and documents; it never signs.',
+  };
+  if (asJson) { emitJson(report); process.exit(EXIT.OK); }
+  out(`\n${J}${B}Trooth EU AI Act${X} ${D}// evidence ingested //${X}`);
+  out(`datasets ${B}${report.ingested.datasets}${X} · evals ${B}${report.ingested.evals}${X} · drift ${B}${report.ingested.drift}${X}`);
+  out(`\n${D}${report.disclaimer}${X}\n`);
+  process.exit(EXIT.OK);
+}
+
+/* ---------------------------------------------------------------- lint ---- */
+
+const LINTER_PKG = '@trooth/os';
+
+/** Find the linter package if it is installed next to this CLI or in the caller's
+ *  project. It is NOT fetched from the network: the previous release ran
+ *  `npx --yes @trooth/os`, and that name is not on the npm registry (404), so every
+ *  `trooth lint` ended in npx's raw error. */
+function resolveLinter() {
+  const roots = [import.meta.url, `file://${process.cwd()}/`];
+  for (const root of roots) {
+    try {
+      const pkgPath = createRequire(root).resolve(`${LINTER_PKG}/package.json`);
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin && Object.values(pkg.bin)[0];
+      if (!bin) continue;
+      return { dir: dirname(pkgPath), entry: `${dirname(pkgPath)}/${bin}`, version: pkg.version };
+    } catch { /* try the next root */ }
+  }
+  return null;
 }
 
 async function lint() {
-  // Local, read-only .tf drift check. Reuses the published @trooth/os linter if present,
-  // otherwise runs a built-in minimal ruleset. Never transmits your code.
-  const path = argv[1] && !argv[1].startsWith('--') ? argv[1] : '.';
-  const { spawnSync } = await import('node:child_process');
-  const r = spawnSync('npx', ['--yes', '@trooth/os', path], { stdio: 'inherit' });
-  process.exit(r.status ?? 0);
+  const { positional } = parseArgs('lint');
+  if (positional.length > 1) fail(EXIT.USAGE, `lint takes one optional [path], got: ${positional.join(' ')}`);
+  const target = positional[0] || '.';
+  if (!existsSync(target)) fail(EXIT.USAGE, `path not found: ${target}`);
+
+  const linter = resolveLinter();
+  if (!linter) {
+    diag(`${R}error${X} \`trooth lint\` needs the ${LINTER_PKG} linter, and it is not available.`);
+    diag(`${D}  ${LINTER_PKG} is not published on the npm registry and is not installed locally.`);
+    diag(`  Nothing was linted and nothing left this machine. This CLI does not download it for you.`);
+    diag(`  When it ships, install it (npm i -D ${LINTER_PKG}) and run \`trooth lint\` again.${X}`);
+    process.exit(EXIT.UPSTREAM);
+  }
+  const r = spawnSync(process.execPath, [linter.entry, target], { stdio: 'inherit' });
+  if (r.error) fail(EXIT.UPSTREAM, `could not start ${LINTER_PKG}@${linter.version}: ${r.error.message}`);
+  process.exit(r.status ?? EXIT.UPSTREAM);
 }
 
+/* ---------------------------------------------------------------- main ---- */
+
 (async () => {
-  if (cmd === '--version' || cmd === '-v') { console.log(VERSION); return; }
-  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { help(); return; }
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') { out(VERSION); return; }
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { out(helpText()); return; }
   if (cmd === 'check') return check();
   if (cmd === 'scan') return scan();
   if (cmd === 'eu') return eu();
   if (cmd === 'lint') return lint();
-  console.error(`${R}error${X} unknown command: ${cmd}\n`); help(); process.exit(2);
-})();
+  if (cmd.startsWith('-')) fail(EXIT.USAGE, `unknown flag ${cmd}. Run \`trooth --help\`.`);
+  diag(helpText());
+  fail(EXIT.USAGE, `unknown command: ${cmd}. Commands: check, scan, eu, lint.`);
+})().catch((e) => {
+  fail(EXIT.UPSTREAM, `unexpected failure: ${e && e.message ? e.message : e}`);
+});

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "trooth",
-  "version": "0.2.0",
-  "description": "Trooth CLI. Check any company's witnessed trust standing from your terminal (read-only, no key), and scan a Terraform plan against SOC 2 / ISO 27001 / GDPR / HIPAA / NIST AI RMF / EU AI Act. Advisory and report-only. Trooth never applies changes.",
+  "version": "0.3.0",
+  "description": "Trooth CLI. Read any company's witnessed record on the Trooth Network from your terminal (read-only, no key; facts and counts, never a number that sums a company up), and scan a Terraform plan against SOC 2 / ISO 27001 / GDPR / HIPAA / NIST AI RMF / EU AI Act. Advisory and report-only. Trooth never applies changes.",
   "type": "module",
-  "bin": "bin/trooth.mjs",
+  "bin": {
+    "trooth": "bin/trooth.mjs"
+  },
   "files": [
     "bin/",
     "README.md"
@@ -13,14 +15,15 @@
   },
   "scripts": {
     "check": "node ./bin/trooth.mjs check",
-    "scan": "node ./bin/trooth.mjs scan"
+    "scan": "node ./bin/trooth.mjs scan",
+    "test": "node tests/cli.test.mjs"
   },
   "license": "MIT",
   "author": "Trooth, LLC",
   "homepage": "https://trooth.co",
   "repository": {
     "type": "git",
-    "url": "https://github.com/trooth/trooth-cli.git"
+    "url": "git+https://github.com/trooth/trooth-cli.git"
   },
   "keywords": [
     "trust",