opstruth 0.1.1 → 0.1.3

package/README.md

@@ -6,13 +6,15 @@ Read-only operational truth checks for AI-assisted engineering workflows.
 
 ## Install
 
-After npm publication:
+Current published package:
 
 ```bash
 npm install -g opstruth
 opstruth
 ```
 
+The public npm package is `opstruth@0.1.2`.
+
 One-off usage:
 
 ```bash
@@ -24,18 +26,37 @@ npx opstruth
 ```bash
 opstruth
 opstruth welcome
+opstruth init --yes
 opstruth probes
 opstruth secrets
 opstruth routes --base-url https://example.com
 opstruth local --port 3000 --health /health
+opstruth --json
+opstruth --no-color
 ```
 
+## Terminal Output
+
+Human output uses a restrained colour theme for status, warnings, proof gaps, evidence, and next safe steps when the terminal supports ANSI colour.
+
+Use `--no-color` or `NO_COLOR=1` to disable colour. Use `--color` to force colour for demos. JSON output remains machine-readable and does not include ANSI codes. Evidence markdown output remains ANSI-free.
+
 ## Safety Model
 
 opstruth is read-only by default. CLI checks do not deploy, mutate databases, trigger queues or jobs, call OpenAI, restart services, publish content, or print raw secrets.
 
 Skipped checks and not-verified areas are reported as proof gaps instead of being treated as safe.
 
+## Configuration
+
+`opstruth.config.json` can provide route paths, local ports/health paths, and secret allowlists. Generate a starter config:
+
+```bash
+opstruth init --yes
+```
+
+CLI flags remain the clearest way to provide runtime inputs.
+
 ## Repository
 
 Source, docs, and release evidence live at:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opstruth",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Read-only operational truth checks for AI-assisted engineering workflows.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -12,6 +12,7 @@ import { runLocal } from './commands/local.js';
 import { runEvidence } from './commands/evidence.js';
 import { runProbes } from './commands/probes.js';
 import { resultToMarkdown } from './lib/markdown.js';
+import { formatTerminalOutput } from './lib/terminal.js';
 import { writeFileSafe } from './lib/fs.js';
 import { redactObject } from './lib/redact.js';
 import { exitCodeFor } from './lib/result.js';
@@ -26,6 +27,8 @@ export function parseArgs(argv) {
     if (!arg.startsWith('-') && !command && COMMANDS.has(arg)) { command = arg; continue; }
     if (arg === '--help' || arg === '-h') options.help = true;
     if (arg === '--json') options.json = true;
+    else if (arg === '--color') options.color = true;
+    else if (arg === '--no-color') options.noColor = true;
     else if (arg === '--out') options.out = take(argv, i++);
     else if (arg === '--base-url') options.baseUrl = take(argv, i++);
     else if (arg === '--routes') options.routesFile = take(argv, i++);
@@ -108,32 +111,47 @@ function helpText(command) {
     '  --out <file>        Write command output/evidence',
     '  --skip <area|id>    Skip a command or probe area',
     '  --only <area|id>    Select a probe area or id',
+    '  --color             Force colour for human terminal output',
+    '  --no-color          Disable colour for human terminal output',
     '  -h, --help          Print help and exit 0'
   ];
-  const route = [
-    ASCII_HEADER,
-    'Usage: opstruth routes --base-url <url> [--routes file] [--strict]',
-    '',
-    'Read-only route probes collect URL, method, status, latency, redirects, and security-header evidence.',
-    '',
-    'Options:',
-    '  --base-url <url>    Base URL to probe',
-    '  --routes <file>     JSON route config',
-    '  --json              Print JSON output',
-    '  -h, --help          Print help and exit 0'
-  ];
-  const repo = [
-    ASCII_HEADER,
-    'Usage: opstruth repo [--json] [--strict]',
-    '',
-    'Read-only repository inspection reports cwd, git root, branch, latest commit, dirty files, and detected stack.',
-    '',
-    'Options:',
-    '  --json              Print JSON output',
-    '  -h, --help          Print help and exit 0'
-  ];
-  if (command === 'routes') return route.join('\n') + '\n';
-  if (command === 'repo') return repo.join('\n') + '\n';
+  const commandHelp = {
+    repo: ['Usage: opstruth repo [--json] [--strict]', 'Inspect cwd, git root, branch, latest commit, dirty files, and detected stack.'],
+    quality: ['Usage: opstruth quality [--script name] [--continue] [--json]', 'Run only existing safe package scripts; missing scripts and npm placeholder tests are skipped.'],
+    routes: ['Usage: opstruth routes --base-url <url> [--routes file] [--json]', 'Collect read-only URL, method, status, latency, redirect, and header evidence.'],
+    secrets: ['Usage: opstruth secrets [--json]', 'Scan source text for risky secret/auth references with redacted previews; .env contents are skipped.'],
+    supabase: ['Usage: opstruth supabase [--protected-table name] [--frontend-dir dir] [--migrations-dir dir]', 'Run a static Supabase migration/frontend exposure audit without credentials or database calls.'],
+    cloudflare: ['Usage: opstruth cloudflare [--url https://example.com] [--json]', 'Inspect Wrangler config, deploy scripts, and optional read-only route status; no deploy is run.'],
+    local: ['Usage: opstruth local --port 3000 [--health /health] [--process name] [--service name]', 'Check explicit local runtime inputs without starting, stopping, or killing services.'],
+    probes: ['Usage: opstruth probes [--json] [--only area|id] [--skip area|id]', 'Inspect probe catalogue metadata, eligible probes, skipped probes, required inputs, and proof gaps.'],
+    evidence: ['Usage: opstruth evidence [--title text] [--out evidence/opstruth.md] [--include file]', 'Write a markdown evidence pack with verified facts, proof gaps, boundaries, and next safe step.'],
+    init: ['Usage: opstruth init [--yes]', 'Create a safe starter opstruth.config.json after confirmation.']
+  };
+  if (commandHelp[command]) {
+    const [usage, description] = commandHelp[command];
+    return [
+      ASCII_HEADER,
+      usage,
+      '',
+      description,
+      '',
+      'Examples:',
+      '  opstruth',
+      '  opstruth --base-url https://example.com',
+      '  opstruth routes --base-url https://example.com',
+      '  opstruth local --port 3000 --health /health',
+      '  opstruth --json',
+      '  opstruth --no-color',
+      '  opstruth --color',
+      '',
+      'Options:',
+      '  --json              Print JSON output',
+      '  --strict            Treat warnings/skips as failing confidence',
+      '  --color             Force colour for human terminal output',
+      '  --no-color          Disable colour for human terminal output',
+      '  -h, --help          Print help and exit 0'
+    ].join('\n') + '\n';
+  }
   return common.join('\n') + '\n';
 }
 
@@ -156,8 +174,17 @@ function welcomeText() {
     '- opstruth --strict',
     '- opstruth routes --base-url https://example.com',
     '- opstruth local --port 3000 --health /health',
+    '- opstruth --json',
+    '- opstruth --no-color',
+    '- opstruth --color',
     '- opstruth evidence --title "Release proof"',
     '',
+    'Improving confidence:',
+    '- provide --base-url or route config when route proof matters',
+    '- provide --port and --health when local runtime proof matters',
+    '- run inside a git repo for stronger change evidence',
+    '- attach evidence/opstruth-report.md to reviews or CI artifacts',
+    '',
     'Safety philosophy:',
     'opstruth prefers skipped or not verified over pretending something is safe. Dangerous actions require explicit approval and are not part of the default run.',
     ''
@@ -165,27 +192,34 @@ function welcomeText() {
 }
 
 const INIT_CONFIG = {
-  routes: {
-    baseUrl: '',
-    paths: ['/', '/login', '/healthz'],
-    requiredHeaders: [
-      'content-security-policy',
-      'strict-transport-security',
-      'x-frame-options',
-      'referrer-policy'
-    ]
-  },
+  projectName: 'example',
+  routes: [
+    { path: '/', expectedStatus: 200 },
+    { path: '/health', expectedStatus: 200 }
+  ],
   local: {
     ports: [],
-    healthPath: '/health'
+    healthPaths: ['/health']
+  },
+  quality: {
+    skipScripts: [],
+    requiredScripts: []
+  },
+  secrets: {
+    allowlistPaths: [],
+    allowlistPatterns: []
   },
   supabase: {
+    enabled: true,
     protectedTables: [
       'agent_jobs',
       'platform_credentials',
       'worker_logs'
     ]
   },
+  cloudflare: {
+    enabled: true
+  },
   ignore: [
     '.cache',
     '.agents',
@@ -234,13 +268,13 @@ export async function runCli(argv, cwd = process.cwd()) {
   const { command, options } = parseArgs(argv);
   options.cwd = cwd;
   if (options.help) {
-    await writeStdout(helpText(command));
+    await writeStdout(formatTerminalOutput(helpText(command), options));
     process.exitCode = 0;
     return;
   }
   const result = await dispatch(command, options);
   if (typeof result === 'string') {
-    await writeStdout(result);
+    await writeStdout(formatTerminalOutput(result, options));
     process.exitCode = 0;
     return;
   }
@@ -249,6 +283,6 @@ export async function runCli(argv, cwd = process.cwd()) {
     const outPath = path.isAbsolute(options.out) ? options.out : path.join(cwd, options.out);
     await writeFileSafe(outPath, output);
   }
-  await writeStdout(output);
+  await writeStdout(options.json ? output : formatTerminalOutput(output, options));
   process.exitCode = exitCodeFor(result, { strict: options.strict });
 }

package/src/commands/local.js

@@ -1,9 +1,15 @@
 import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
 import { runCommand } from '../lib/exec.js';
 import { probeUrl } from '../lib/http.js';
+import { loadOpstruthConfig } from '../lib/config.js';
 
 export async function runLocal({ cwd = process.cwd(), port = [], health = '/', process: processName, service, strict = false } = {}) {
-  const ports = Array.isArray(port) ? port : [port].filter(Boolean);
+  const loaded = await loadOpstruthConfig(cwd);
+  const configLocal = loaded.config?.local || {};
+  const ports = (Array.isArray(port) && port.length ? port : Array.isArray(configLocal.ports) ? configLocal.ports : [port].filter(Boolean));
+  const healthPaths = Array.isArray(configLocal.healthPaths) ? configLocal.healthPaths : [configLocal.healthPath].filter(Boolean);
+  if ((!health || health === '/') && healthPaths.length) health = healthPaths[0];
+  if (loaded.warning && !ports.length && !processName && !service) return createResult('local', 'warn', { warnings: [loaded.warning], notVerified: ['Local runtime liveness'], nextSafeStep: 'Fix opstruth.config.json or pass --port and --health explicitly.' });
   if (!ports.length && !processName && !service) return createResult('local', 'skipped', { skipped: ['Local runtime checks skipped because no --port, --process, or --service was provided'], notVerified: ['Local runtime liveness'], nextSafeStep: 'Run opstruth local --port 3000 --health /health when the app is running.' });
   const checks = [];
   const warnings = [];

package/src/commands/probes.js

@@ -13,6 +13,29 @@ function summarizeCounts(label, counts) {
   return `${label}: ${Object.entries(counts).map(([name, count]) => `${name}=${count}`).join(', ')}`;
 }
 
+function probeJson(probe) {
+  return {
+    id: probe.id,
+    name: probe.name,
+    area: probe.area,
+    stack: probe.stack,
+    mode: probe.mode,
+    safetyLevel: probe.safetyLevel,
+    defaultMode: probe.defaultMode,
+    mutability: probe.mutability,
+    inputsRequired: probe.inputsRequired,
+    evidenceCollected: probe.evidenceCollected,
+    evidenceExpectation: probe.evidenceExpectation,
+    proves: probe.proves,
+    doesNotProve: probe.doesNotProve,
+    proofLimitation: probe.proofLimitation,
+    skipReason: probe.skipReason,
+    nextSafeStep: probe.nextSafeStep,
+    supportedStacks: probe.supportedStacks,
+    notVerified: probe.notVerified
+  };
+}
+
 export async function runProbes({ cwd = process.cwd(), strict = false, skip = [], only = [] } = {}) {
   const boundary = await resolveProjectBoundary(cwd);
   const stack = await detectStack(boundary.root);
@@ -20,6 +43,7 @@ export async function runProbes({ cwd = process.cwd(), strict = false, skip = []
   const byArea = countBy(PROBE_CATALOGUE, 'area');
   const byMode = countBy(PROBE_CATALOGUE, 'defaultMode');
   const bySafety = countBy(PROBE_CATALOGUE, 'safetyLevel');
+  const explicitInputProbes = PROBE_CATALOGUE.filter((probe) => probe.inputsRequired?.length);
   const result = createResult('probes', 'pass', {
     summary: 'Probe catalogue inspected for the current project without running mutating actions.',
     verified: [
@@ -28,19 +52,20 @@ export async function runProbes({ cwd = process.cwd(), strict = false, skip = []
       summarizeCounts('Probes by default mode', byMode),
       summarizeCounts('Probes by safety level', bySafety),
       'Detected safe automatic probes for this project: ' + selection.selected.length,
+      'Explicit input probes: ' + explicitInputProbes.map((probe) => `${probe.id} (${probe.inputsRequired.join(' + ')})`).join('; '),
       'Project boundary: ' + boundary.root,
       'Detected platforms: ' + (stack.platforms.length ? stack.platforms.join(', ') : 'none')
     ],
     skipped: [
       ...(boundary.message ? [boundary.message] : []),
-      ...selection.skipped.slice(0, 20).map((probe) => `${probe.id}: ${probe.reason}`)
+      ...selection.skipped.slice(0, 20).map((probe) => `${probe.id}: ${probe.reason}; next: ${probe.nextSafeStep}`)
     ],
     checks: selection.selected.map((probe) => ({
       name: probe.id,
       status: 'pass',
       message: `${probe.area}/${probe.stack}: ${probe.name}`
     })),
-    notVerified: ['Probe catalogue inspection does not run route, local runtime, deploy, or external service checks by itself.'],
+    notVerified: ['Probe catalogue inspection does not run route, local runtime, deploy, or external service checks by itself.', 'Skipped probes are proof gaps, not failures.'],
     data: {
       boundary,
       stack,
@@ -48,19 +73,12 @@ export async function runProbes({ cwd = process.cwd(), strict = false, skip = []
       byArea,
       byMode,
       bySafety,
-      detected: selection.selected.map((probe) => ({
-        id: probe.id,
-        name: probe.name,
-        area: probe.area,
-        stack: probe.stack,
-        safetyLevel: probe.safetyLevel,
-        defaultMode: probe.defaultMode,
-        evidenceCollected: probe.evidenceCollected,
-        proves: probe.proves,
-        doesNotProve: probe.doesNotProve,
-        nextSafeStep: probe.nextSafeStep
-      })),
-      skipped: selection.skipped.map((probe) => ({ id: probe.id, area: probe.area, stack: probe.stack, reason: probe.reason }))
+      catalogue: PROBE_CATALOGUE.map(probeJson),
+      detected: selection.selected.map(probeJson),
+      skipped: selection.skipped.map((probe) => ({
+        ...probeJson(probe),
+        reason: probe.reason
+      }))
     },
     nextSafeStep: 'Run opstruth for selected safe probes, or add explicit route/local inputs for stronger runtime evidence.'
   });

package/src/commands/routes.js

@@ -8,12 +8,12 @@ export async function runRoutes({ cwd = process.cwd(), baseUrl, routesFile, stri
   const boundary = await resolveProjectBoundary(cwd);
   cwd = boundary.root;
   let config = routesFile ? await loadRoutesConfig(cwd, routesFile) : null;
-  if (config?.routes?.baseUrl !== undefined || config?.routes?.paths) config = config.routes;
-  if (!config) config = (await findDefaultRoutesConfig(cwd))?.config;
+  const defaultConfig = config ? null : await findDefaultRoutesConfig(cwd);
+  if (!config) config = defaultConfig?.config;
+  if (defaultConfig?.warning) return createResult('routes', 'warn', { warnings: [defaultConfig.warning], notVerified: ['Public route availability'], nextSafeStep: 'Fix opstruth.config.json or pass --routes with valid JSON.' });
   const finalBase = baseUrl || config?.baseUrl;
   if (!finalBase) return createResult('routes', 'skipped', { skipped: ['Route checks skipped because no --base-url or route config was provided'], notVerified: ['Public route availability'], nextSafeStep: 'Run opstruth routes --base-url https://example.com or provide --routes.' });
-  const paths = config?.paths?.length ? config.paths.map((routePath) => ({ path: routePath, method: routePath.includes('health') ? 'GET' : 'HEAD', expectStatus: [200, 301, 302] })) : [];
-  const routes = config?.routes?.length ? config.routes : paths.length ? paths : [{ path: '/', method: 'HEAD', expectStatus: [200, 301, 302] }];
+  const routes = config?.routes?.length ? config.routes : [{ path: '/', method: 'HEAD', expectStatus: [200, 301, 302] }];
   const requiredHeaders = config?.requiredHeaders || DEFAULT_HEADERS;
   const checks = [];
   const warnings = [];

package/src/commands/secrets.js

@@ -1,10 +1,16 @@
 import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
 import { scanRiskyReferences } from '../lib/scan.js';
 import { resolveProjectBoundary } from '../lib/boundary.js';
+import { loadOpstruthConfig } from '../lib/config.js';
 
 export async function runSecrets({ cwd = process.cwd(), strict = false } = {}) {
   const boundary = await resolveProjectBoundary(cwd);
-  const findings = await scanRiskyReferences(boundary.root);
+  const loaded = await loadOpstruthConfig(boundary.root);
+  const secretConfig = loaded.config?.secrets || {};
+  const findings = await scanRiskyReferences(boundary.root, {
+    allowlistPaths: secretConfig.allowlistPaths || [],
+    allowlistPatterns: secretConfig.allowlistPatterns || []
+  });
   const findingObjects = findings.map((item) => createFinding({
     status: 'warn',
     area: 'secrets',
@@ -14,19 +20,21 @@ export async function runSecrets({ cwd = process.cwd(), strict = false } = {}) {
       'file: ' + item.file,
       'line: ' + item.line,
       'pattern: ' + item.pattern,
+      'kind: ' + item.kind,
+      'context: ' + item.context,
       'redacted preview: ' + item.preview
     ],
     whyItMatters: 'Secret-like values and service-role references can create account, data, or infrastructure exposure if committed or exposed to browsers.',
     nextSafeStep: 'Confirm whether this is a harmless reference. Move real secrets to secret storage and keep only names/placeholders in source.'
   }));
-  const result = createResult('secrets', findings.length ? 'warn' : 'pass', {
+  const result = createResult('secrets', loaded.warning || findings.length ? 'warn' : 'pass', {
     summary: 'Redacted risky secret/reference scan completed. .env file contents are skipped.',
     verified: ['Project boundary scanned: ' + boundary.root, 'Source files scanned with redaction', '.env contents were not printed'],
-    warnings: findingObjects.map((finding) => finding.finding),
+    warnings: [...(loaded.warning ? [loaded.warning] : []), ...findingObjects.map((finding) => finding.finding)],
     findings: findingObjects,
     skipped: boundary.message ? [boundary.message] : [],
     checks: [{ name: 'secret reference scan', status: findings.length ? 'warn' : 'pass', message: findings.length + ' finding(s)' }],
-    data: { boundary, findings },
+    data: { boundary, configFile: loaded.file, allowlistPaths: secretConfig.allowlistPaths || [], allowlistPatterns: secretConfig.allowlistPatterns || [], findings },
     nextSafeStep: findings.length ? 'Review whether each reference is expected and move real secrets to safe storage.' : 'Keep secrets out of source and rerun before publishing.'
   });
   return finalizeStatus(result, { strict });

package/src/lib/config.js

@@ -1,18 +1,56 @@
 import path from 'node:path';
 import { pathExists, readJson, readText } from './fs.js';
 
+export async function loadOpstruthConfig(root) {
+  const full = path.join(root, 'opstruth.config.json');
+  if (!(await pathExists(full))) return { config: null, warning: null, file: null };
+  try {
+    return { config: await readJson(full), warning: null, file: 'opstruth.config.json' };
+  } catch (error) {
+    return { config: null, warning: 'Invalid opstruth.config.json: ' + error.message, file: 'opstruth.config.json' };
+  }
+}
+
+export function normalizeRoutesConfig(config) {
+  if (!config) return null;
+  const routesConfig = config.routes?.baseUrl !== undefined || config.routes?.paths || Array.isArray(config.routes)
+    ? config.routes
+    : config;
+  const normalizeRoute = (route) => ({
+    ...route,
+    expectStatus: route.expectStatus || (Number.isFinite(route.expectedStatus) ? [route.expectedStatus] : route.expectedStatus)
+  });
+  if (Array.isArray(routesConfig)) return { routes: routesConfig.map(normalizeRoute) };
+  if (Array.isArray(routesConfig?.routes)) return { ...routesConfig, routes: routesConfig.routes.map(normalizeRoute) };
+  if (Array.isArray(routesConfig?.paths)) {
+    return {
+      ...routesConfig,
+      routes: routesConfig.paths.map((routePath) => ({
+        path: routePath,
+        method: String(routePath).includes('health') ? 'GET' : 'HEAD',
+        expectStatus: [200, 301, 302]
+      }))
+    };
+  }
+  return routesConfig;
+}
+
 export async function loadRoutesConfig(root, file) {
   if (!file) return null;
   const full = path.isAbsolute(file) ? file : path.join(root, file);
   if (!(await pathExists(full))) return null;
-  return readJson(full);
+  return normalizeRoutesConfig(await readJson(full));
 }
 export async function findDefaultRoutesConfig(root) {
   for (const file of ['opstruth.config.json', 'opstruth.routes.json', 'routes.json']) {
     const full = path.join(root, file);
     if (await pathExists(full)) {
-      const config = await readJson(full);
-      return { file, config: config.routes?.baseUrl !== undefined || config.routes?.paths ? config.routes : config };
+      try {
+        const config = await readJson(full);
+        return { file, config: normalizeRoutesConfig(config) };
+      } catch (error) {
+        return { file, config: null, warning: 'Invalid route config ' + file + ': ' + error.message };
+      }
     }
   }
   return null;

package/src/lib/markdown.js

@@ -9,7 +9,7 @@ const ASCII_HEADER = `   ____        _______          __  __
 
 Operational truth checks for AI-assisted engineering.`;
 
-function statusLabel(status) {
+export function statusLabel(status) {
   if (status === 'pass') return 'Pass';
   if (status === 'warn') return 'Partial pass';
   if (status === 'fail') return 'Fail';
@@ -178,9 +178,24 @@ export function evidenceMarkdown({ title = 'opstruth Evidence Pack', status = 'n
     '## Check Results',
     list(checks, '- No checks attached', 25),
     '',
+    '## Probe Results',
+    list(checks, '- No probe results attached', 25),
+    '',
     '## Verified Facts',
     list(liveVerification, '- No live verification evidence attached', 20),
     '',
+    '## Warnings',
+    list(risks.filter((risk) => /warn|warning|review/i.test(risk)), '- None recorded', 20),
+    '',
+    '## Failures',
+    list(risks.filter((risk) => /fail|failure|blocked/i.test(risk)), '- None recorded', 20),
+    '',
+    '## Skipped / Not Configured',
+    'Skipped checks are proof gaps, not failures. See command output for skipped probe IDs and reasons.',
+    '',
+    '## Not Verified',
+    'Production, local runtime, database state, queues, publishing, and external AI usage are not verified unless explicit read-only inputs or external evidence are attached.',
+    '',
     '## Risks And Gaps',
     table(['Severity', 'Finding'], riskRows.slice(0, 25)),
     '',
@@ -196,6 +211,12 @@ export function evidenceMarkdown({ title = 'opstruth Evidence Pack', status = 'n
     '## Safety Boundaries',
     list(safetyBoundaries, '- Read-only checks only'),
     '',
+    '## Evidence Files / Paths',
+    list(scope.concat(filesChanged).filter(Boolean), '- No evidence paths attached', 30),
+    '',
+    '## Confidence',
+    confidenceFor({ status, failures: risks.filter((risk) => /fail|failure|blocked/i.test(risk)), warnings: risks, skipped: [], notVerified: [] }),
+    '',
     '## Next Safe Step',
     nextSafeStep || 'Run the narrowest missing read-only verification and attach the result.'
   ].join('\n') + '\n';

package/src/lib/probes.js

@@ -10,7 +10,7 @@ function nodeDependencyDetector(name) {
   return async (_root, stack) => stack.dependencies?.includes(name);
 }
 
-export const PROBE_CATALOGUE = [
+const RAW_PROBE_CATALOGUE = [
   {
     id: 'git.status',
     name: 'Git status',
@@ -463,6 +463,48 @@ export const PROBE_CATALOGUE = [
   }
 ];
 
+function inputsRequiredFor(probe) {
+  if (probe.id.startsWith('routes.')) return ['--base-url or route config'];
+  if (probe.id === 'local.ports') return ['--port or local config'];
+  if (probe.id === 'local.health') return ['--port and --health or local config'];
+  if (probe.id === 'supabase.migrations') return ['supabase/migrations directory'];
+  if (probe.id === 'cloudflare.wrangler') return ['wrangler.toml, wrangler.json, or wrangler.jsonc'];
+  if (probe.id.startsWith('quality.')) return ['matching package.json script'];
+  if (probe.id.startsWith('node.')) return ['matching package metadata/config/source'];
+  if (probe.id.startsWith('git.')) return ['git repository'];
+  return [];
+}
+
+function skipReasonFor(probe) {
+  if (probe.id.startsWith('routes.')) return 'Requires --base-url, --routes, or opstruth.config.json route entries';
+  if (probe.id === 'local.ports') return 'Requires --port or opstruth.config.json local ports';
+  if (probe.id === 'local.health') return 'Requires --port with --health or opstruth.config.json local health paths';
+  if (probe.id === 'supabase.migrations') return 'Requires a Supabase migrations directory';
+  if (probe.id === 'cloudflare.wrangler') return 'Requires Wrangler configuration';
+  if (probe.id.startsWith('quality.')) return 'Requires a matching non-placeholder package.json script';
+  if (probe.id.startsWith('git.')) return 'Requires a git repository';
+  return 'Not relevant to detected stack or missing configuration';
+}
+
+function normalizeProbe(probe) {
+  const inputsRequired = probe.inputsRequired || inputsRequiredFor(probe);
+  return {
+    ...probe,
+    mode: probe.mode || probe.defaultMode,
+    mutability: probe.mutability || 'none',
+    inputsRequired,
+    evidenceExpectation: probe.evidenceExpectation || probe.evidenceCollected || [],
+    skipReason: probe.skipReason || skipReasonFor(probe),
+    proofLimitation: probe.proofLimitation || probe.doesNotProve,
+    supportedStacks: probe.supportedStacks || [probe.stack],
+    notVerified: probe.notVerified || [probe.doesNotProve],
+    falsePositiveRisk: probe.falsePositiveRisk || 'Low to medium; depends on project conventions and fixture/demo content.',
+    falseNegativeRisk: probe.falseNegativeRisk || 'Does not prove absence outside scanned files, configured inputs, or supported stack heuristics.'
+  };
+}
+
+export const PROBE_CATALOGUE = RAW_PROBE_CATALOGUE.map(normalizeProbe);
+
 export async function selectProbes({ root, stack, boundary, options = {} }) {
   const only = new Set(options.only || []);
   const skip = new Set(options.skip || []);
@@ -483,7 +525,7 @@ export async function selectProbes({ root, stack, boundary, options = {} }) {
     }
     const relevant = await probe.detector(root, stack, boundary, options);
     if (relevant) selected.push(probe);
-    else skipped.push({ ...probe, reason: 'Not relevant to detected stack or missing configuration' });
+    else skipped.push({ ...probe, reason: probe.skipReason || 'Not relevant to detected stack or missing configuration' });
   }
   return { selected, skipped, catalogueSize: PROBE_CATALOGUE.length };
 }

package/src/lib/scan.js

@@ -10,21 +10,79 @@ const OPSTRUTH_SCANNER_FILES = new Set([
   'src/lib/scan.js',
   'src/lib/probes.js',
   'test/typescript-compatibility.test.js',
+  'cli/src/lib/redact.js',
+  'cli/src/lib/scan.js',
+  'cli/src/lib/probes.js',
+  'cli/test/typescript-compatibility.test.js',
   'fixtures/risky-secret-app/src/config.js'
 ]);
+const FIXTURE_PACKAGE_NAMES = new Set([
+  'plain-node-app',
+  'vite-react-app',
+  'next-app',
+  'tanstack-app',
+  'cloudflare-worker-app',
+  'supabase-app',
+  'default-npm-placeholder-test',
+  'failing-real-test-script',
+  'risky-secret-app',
+  'missing-build-script',
+  'route-config-app'
+]);
 
 export function isLikelyText(file) { return /\.(js|mjs|cjs|ts|tsx|jsx|json|jsonc|toml|yml|yaml|md|txt|env|sql|html|css)$/i.test(file) || !path.extname(file); }
 
+function matchesAllowlist(file, line, { allowlistPaths = [], allowlistPatterns = [] } = {}) {
+  if (allowlistPaths.some((item) => file === item || file.startsWith(item.replace(/\/$/, '') + '/'))) return true;
+  return allowlistPatterns.some((pattern) => {
+    try { return new RegExp(pattern).test(line) || new RegExp(pattern).test(file); } catch { return false; }
+  });
+}
+
+function classifySecretLine(line) {
+  if (/[=:]\s*["']?[^"'\s;]+/.test(line)) return 'secret-like value';
+  return 'secret reference';
+}
+
+function classifySourceContext(file, rootContext = 'source file') {
+  if (file.startsWith('fixtures/') || file.startsWith('cli/fixtures/')) return 'fixture/demo file';
+  if (file.startsWith('docs/') || file.startsWith('cli/docs/')) return 'documentation reference';
+  return rootContext;
+}
+
+async function classifyRootContext(root) {
+  const packageFile = path.join(root, 'package.json');
+  if (!(await pathExists(packageFile))) return 'source file';
+  try {
+    const name = (await readJson(packageFile)).name;
+    return FIXTURE_PACKAGE_NAMES.has(name) ? 'fixture/demo file' : 'source file';
+  } catch {
+    return 'source file';
+  }
+}
+
 async function isOpstruthRoot(root) {
   const packageFile = path.join(root, 'package.json');
-  if (!(await pathExists(packageFile))) return false;
-  try { return (await readJson(packageFile)).name === 'opstruth'; } catch { return false; }
+  const cliPackageFile = path.join(root, 'cli/package.json');
+  try {
+    if (await pathExists(packageFile)) {
+      const name = (await readJson(packageFile)).name;
+      if (name === 'opstruth' || name === 'opstruth-monorepo') return true;
+    }
+    if (await pathExists(cliPackageFile)) {
+      return (await readJson(cliPackageFile)).name === 'opstruth';
+    }
+  } catch {
+    return false;
+  }
+  return false;
 }
 
-export async function scanRiskyReferences(root, { skipDirs = DEFAULT_SKIP_DIRS } = {}) {
+export async function scanRiskyReferences(root, { skipDirs = DEFAULT_SKIP_DIRS, allowlistPaths = [], allowlistPatterns = [] } = {}) {
   const files = await walkFiles(root, { skipDirs: mergeIgnores(skipDirs) });
   const findings = [];
   const suppressInternalScannerDefinitions = await isOpstruthRoot(root);
+  const rootContext = await classifyRootContext(root);
   for (const file of files) {
     if (suppressInternalScannerDefinitions && OPSTRUTH_SCANNER_FILES.has(file.rel)) continue;
     if (!isLikelyText(file.rel)) continue;
@@ -33,6 +91,7 @@ export async function scanRiskyReferences(root, { skipDirs = DEFAULT_SKIP_DIRS }
     try { text = await readText(file.full); } catch { continue; }
     const lines = text.split(/\r?\n/);
     lines.forEach((line, index) => {
+      if (matchesAllowlist(file.rel, line, { allowlistPaths, allowlistPatterns })) return;
       for (const pattern of RISK_PATTERNS) {
         if (pattern.test(line)) {
           findings.push({
@@ -40,6 +99,8 @@ export async function scanRiskyReferences(root, { skipDirs = DEFAULT_SKIP_DIRS }
             line: index + 1,
             pattern: pattern.source.replaceAll('\\', ''),
             match: pattern.source.replaceAll('\\', ''),
+            kind: classifySecretLine(line),
+            context: classifySourceContext(file.rel, rootContext),
             preview: redact(line.trim()).slice(0, 160),
             excerpt: redact(line.trim()).slice(0, 160),
             severity: 'review'

package/src/lib/terminal.js

@@ -0,0 +1,119 @@
+const ANSI_PATTERN = /\x1B\[[0-?]*[ -/]*[@-~]/g;
+
+const RESET = '\x1b[0m';
+
+// Website-derived terminal approximations from website/src/styles.css.
+// The website tokens are OKLCH; these RGB values keep the same calm dark,
+// muted, evidence-first feel in common ANSI terminals.
+export const THEME = {
+  heading: ['\x1b[1m', '\x1b[38;2;235;237;240m'],
+  muted: ['\x1b[38;2;150;154;163m'],
+  accent: ['\x1b[38;2;126;190;164m'],
+  success: ['\x1b[38;2;104;194;142m'],
+  warning: ['\x1b[38;2;219;178;80m'],
+  failure: ['\x1b[38;2;221;105;92m'],
+  code: ['\x1b[38;2;226;229;232m'],
+  border: ['\x1b[38;2;82;87;96m']
+};
+
+function hasAnsi(text) {
+  return ANSI_PATTERN.test(text);
+}
+
+export function stripAnsi(text) {
+  return String(text).replace(ANSI_PATTERN, '');
+}
+
+export function supportsColor(options = {}, stream = process.stdout, env = process.env) {
+  if (options.json || options.noColor) return false;
+  if (options.color) return true;
+  if ('NO_COLOR' in env) return false;
+  if (env.TERM === 'dumb') return false;
+  return Boolean(stream?.isTTY);
+}
+
+export function style(text, token, options = {}) {
+  if (!options.colorEnabled) return String(text);
+  const open = THEME[token] || THEME.heading;
+  return open.join('') + text + RESET;
+}
+
+function statusToken(label = '') {
+  const normalized = label.toLowerCase();
+  if (normalized === 'pass' || normalized === 'verified') return 'success';
+  if (normalized === 'partial pass' || normalized === 'warn' || normalized === 'warning') return 'warning';
+  if (normalized === 'fail' || normalized === 'failure') return 'failure';
+  if (normalized === 'skipped' || normalized === 'not verified' || normalized === 'not_verified') return 'muted';
+  return 'heading';
+}
+
+function sectionToken(line) {
+  if (/^## Verified\b/.test(line)) return 'success';
+  if (/^## Warnings\b/.test(line)) return 'warning';
+  if (/^## Failures\b/.test(line)) return 'failure';
+  if (/^## Skipped\b/.test(line)) return 'muted';
+  if (/^## Not Verified\b/.test(line)) return 'warning';
+  if (/^## Evidence\b/.test(line)) return 'accent';
+  if (/^## Next Safe Step\b/.test(line)) return 'accent';
+  if (/^## Overall Confidence\b/.test(line)) return 'accent';
+  if (/^## Checks\b|^## Check Summary\b|^## What Matters Most\b/.test(line)) return 'heading';
+  return 'heading';
+}
+
+function colorStatusWords(line, options) {
+  return line.replace(/\b(Partial pass|Not verified|Pass|Fail|Skipped|pass|warn|fail|skipped|not_verified)\b/g, (label) => {
+    return style(label, statusToken(label), options);
+  });
+}
+
+function colorTableLine(line, options) {
+  if (/^\| [-| ]+\|$/.test(line) || /^\| Status \|/.test(line) || /^\| Area \|/.test(line)) {
+    return style(line, 'border', options);
+  }
+  return line.replace(/\| (Partial pass|Not verified|Pass|Fail|Skipped|pass|warn|fail|skipped|not_verified) \|/g, (_, label) => {
+    return '| ' + style(label, statusToken(label), options) + ' |';
+  });
+}
+
+function colorEvidenceLine(line, options) {
+  const fileMatch = line.match(/^(\s*evidence: )(file:)(\s+)(.+)$/);
+  if (fileMatch) {
+    return style(fileMatch[1], 'muted', options) + style(fileMatch[2], 'accent', options) + fileMatch[3] + style(fileMatch[4], 'code', options);
+  }
+  const writtenMatch = line.match(/^(.*Evidence written to:\s+)(.+)$/);
+  if (writtenMatch) {
+    return style(writtenMatch[1], 'accent', options) + style(writtenMatch[2], 'code', options);
+  }
+  let formatted = line.replace(/^(\s*evidence: )([^:]+:)/, (_, prefix, key) => {
+    return style(prefix, 'muted', options) + style(key, 'accent', options);
+  });
+  formatted = formatted.replace(/^(\s*(why it matters|next safe step):)/, (match) => style(match, 'accent', options));
+  return colorStatusWords(formatted, options);
+}
+
+function colorLine(line, options) {
+  if (!line || hasAnsi(line)) return line;
+  if (/^   ____|^  \/|^ \/ |^\/ \/_|^\\____|^    \/_/.test(line)) return style(line, 'accent', options);
+  if (/^Operational truth checks/.test(line)) return style(line, 'muted', options);
+  if (/^# /.test(line)) return style(line.replace(/^# /, ''), 'heading', options);
+  if (/^## /.test(line)) return style(line.replace(/^## /, ''), sectionToken(line), options);
+  if (/^STATUS: /.test(line)) {
+    const label = line.slice('STATUS: '.length);
+    return style('STATUS:', 'muted', options) + ' ' + style(label, statusToken(label), options);
+  }
+  if (/^\|/.test(line)) return colorTableLine(line, options);
+  if (/^- \[(pass|warn|fail|skipped|not_verified)\]/.test(line)) return colorStatusWords(line, options);
+  if (/^\s*(evidence|why it matters|next safe step):/.test(line)) return colorEvidenceLine(line, options);
+  if (/Evidence written to:|Evidence file was not written/.test(line)) return colorEvidenceLine(line, options);
+  if (/^Usage:|^Commands:|^Global options:|^Options:|^Common workflows:|^Safety philosophy:/.test(line)) return style(line, 'heading', options);
+  if (/^\s{2}(opstruth|--|-h|npm|npx)\b/.test(line) || /^- opstruth\b/.test(line)) return style(line, 'code', options);
+  if (/^- None$|^- No failures$/.test(line)) return style(line, 'muted', options);
+  return line;
+}
+
+export function formatTerminalOutput(text, options = {}) {
+  const colorEnabled = supportsColor(options);
+  if (!colorEnabled) return String(text);
+  const styleOptions = { ...options, colorEnabled };
+  return String(text).split('\n').map((line) => colorLine(line, styleOptions)).join('\n');
+}

package/src/orchestrator.js

@@ -25,6 +25,29 @@ function nextStepFor(aggregate) {
   return 'Attach the evidence pack to the change or handoff.';
 }
 
+function probeJson(probe) {
+  return {
+    id: probe.id,
+    name: probe.name,
+    area: probe.area,
+    stack: probe.stack,
+    mode: probe.mode,
+    safetyLevel: probe.safetyLevel,
+    defaultMode: probe.defaultMode,
+    mutability: probe.mutability,
+    inputsRequired: probe.inputsRequired,
+    evidenceCollected: probe.evidenceCollected,
+    evidenceExpectation: probe.evidenceExpectation,
+    proves: probe.proves,
+    doesNotProve: probe.doesNotProve,
+    proofLimitation: probe.proofLimitation,
+    skipReason: probe.skipReason,
+    nextSafeStep: probe.nextSafeStep,
+    supportedStacks: probe.supportedStacks,
+    notVerified: probe.notVerified
+  };
+}
+
 export async function runOrchestrator(options = {}) {
   const startCwd = options.cwd || process.cwd();
   const boundary = await resolveProjectBoundary(startCwd);
@@ -75,18 +98,8 @@ export async function runOrchestrator(options = {}) {
       stack,
       probes: {
         catalogueSize: probeSelection.catalogueSize,
-        selected: probeSelection.selected.map((probe) => ({
-          id: probe.id,
-          name: probe.name,
-          area: probe.area,
-          stack: probe.stack,
-          safetyLevel: probe.safetyLevel,
-          defaultMode: probe.defaultMode,
-          proves: probe.proves,
-          doesNotProve: probe.doesNotProve,
-          evidenceCollected: probe.evidenceCollected
-        })),
-        skipped: probeSelection.skipped.map((probe) => ({ id: probe.id, area: probe.area, stack: probe.stack, reason: probe.reason }))
+        selected: probeSelection.selected.map(probeJson),
+        skipped: probeSelection.skipped.map((probe) => ({ ...probeJson(probe), reason: probe.reason }))
       },
       childResults
     },