@veraxhq/verax 0.1.0 → 0.2.0

package/README.md

@@ -1,19 +1,21 @@
-🛡️ VERAX
+# 🛡️ VERAX
 
-VERAX detects silent user failures by comparing what your code promises with what users actually experience.
+A forensic observation engine for real user outcomes
 
-Silent failures don’t crash your site.
-They don’t show errors.
+VERAX observes and reports gaps between what your code explicitly promises and what users can actually observe.
+
+Silent user failures don’t crash your site.
+They don’t throw errors.
 They simply lose users quietly.
 
-VERAX exists to surface those failures — with evidence, not guesses.
+VERAX exists to surface those gaps — with evidence, not guesses.
 
 🤔 What is VERAX?
 
 A silent user failure happens when your code clearly implies that something should happen —
 but from the user’s point of view, nothing meaningful does.
 
-Examples:
+Concrete examples:
 
 A button click that should navigate… but doesn’t.
 
@@ -21,17 +23,31 @@ A form submission that triggers an API call… but shows no feedback.
 
 A state update that runs in code… but never reaches the UI.
 
-These issues are frustrating for users and difficult for teams to catch.
+These issues are frustrating for users and notoriously hard for teams to notice.
 
-VERAX reads your source code to understand what should happen, then opens your website in a real browser and experiences it like a human user.
-When code expectations and user reality don’t match, VERAX reports the gap — clearly and honestly.
+VERAX reads your source code to understand what is promised, then opens your site in a real browser and experiences it like a user.
+When expectations and reality don’t align, VERAX reports the gap clearly and honestly.
 
 VERAX does not guess intent.
-It only reports failures that your code explicitly promises.
+It only reports observations backed by explicit code promises.
+
+🧠 Clarification: “Silent failure”
+
+In VERAX, a silent failure is not a judgment about correctness.
+
+It means:
+
+For a promised interaction (for example, a click expected to navigate or save),
+no observable, user-visible effect could be verified
+(no URL change, no network request, no feedback).
+
+This does not mean your code is wrong.
+It means the observation produced no verifiable effect for the promise being evaluated.
 
 ✅ What VERAX does (today)
 
-🔍 Detects silent user failures by comparing code-derived expectations with real browser behavior
+🔍 Observes and reports gaps between code promises and user-visible outcomes
+(by comparing code-derived expectations with real browser behavior)
 
 🧠 Extracts expectations from source code using static analysis:
 
@@ -39,23 +55,24 @@ Navigation from HTML links and React Router / Next.js routes
 
 Network actions from fetch / axios calls with static URLs
 
-State mutations from React useState, Redux dispatch, and Zustand set
+State mutations from React useState, Redux dispatch, Zustand set
 
-🖱️ Observes websites like a real user using Playwright (clicks, forms, navigation, scrolling)
+🖱️ Observes websites like a real user using Playwright
+(clicks, forms, navigation, scrolling)
 
-📊 Assigns confidence levels (HIGH / MEDIUM / LOW) based on evidence strength
+📊 Assigns confidence levels (HIGH / MEDIUM / LOW) based on evidence strength and coverage
 
-🧾 Provides clear evidence for every finding:
+🧾 Provides concrete evidence for every reported discrepancy:
 
 Screenshots
 
 Network activity
 
-Console errors
+Console logs
 
 DOM and state changes
 
-💻 Runs as a CLI tool with verax scan and verax flow
+💻 Runs as a CLI tool via `verax run` (and inspects results with `verax inspect`)
 
 🧱 Supports real-world projects:
 
@@ -71,7 +88,7 @@ Next.js (App Router & Pages Router)
 
 ❌ Does not guess intent — no heuristics, no assumptions
 
-❌ Does not support dynamic routes (/user/${id} is intentionally skipped)
+❌ Does not support dynamic routes (e.g. /user/${id} is intentionally skipped)
 
 ❌ Does not replace QA or tests — it complements them
 
@@ -79,7 +96,7 @@ Next.js (App Router & Pages Router)
 
 ❌ Does not work for every framework
 
-❌ Does not detect every bug — only silent failures backed by code promises
+❌ Does not detect every bug — only gaps backed by explicit code promises
 
 ❌ Does not use AI — all results are deterministic and explainable
 
@@ -87,128 +104,138 @@ Next.js (App Router & Pages Router)
 
 VERAX runs three phases automatically:
 
-1️⃣ Learn
-
-Analyzes your source code to understand:
-
-Project structure
-
-Routes
-
-What interactions promise to do
-Creates a manifest of expectations derived directly from code.
-
-2️⃣ Observe
-
-Opens your site in a real browser and interacts naturally:
+1) **Learn**
+Analyze source code to derive explicit, proven expectations
+(routes, static network actions, state changes).
 
-Clicks buttons
+2) **Observe**
+Open the site in a real browser and execute user interactions safely,
+recording what actually happens.
 
-Fills forms
+3) **Detect**
+Compare code-derived expectations with observed outcomes and report:
+- Discrepancies
+- Coverage gaps
+- Unknowns
+- Safety blocks
 
-Follows links
-Records what actually happens.
-
-3️⃣ Detect
-
-Compares code expectations with real behavior.
-Reports a finding only when code promised an outcome that did not occur — with evidence and confidence.
-
-You run one command. VERAX handles the rest.
+All with evidence.
 
 📦 Installation
 
 Requirements: Node.js 18+
 
-From npm (when published):
-npm install -g @verax/verax
+From npm:
+
+npm install -g @veraxhq/verax
 
 From source:
+
 git clone <repository-url>
-cd odavlguardian
+cd verax
 npm install
 npm link
 
-🚀 Basic usage
-Scan a website:
-verax scan --url <http://localhost:3000>
+## Commands
 
-JSON output (CI-friendly):
-verax scan --url <http://localhost:3000> --json
+VERAX provides these CLI commands:
 
-Scan a specific project directory:
-verax scan --url <http://localhost:3000> --projectRoot ./my-website
+- `verax` — Interactive mode (detects URL or prompts for it)
+- `verax run --url <url> [--src <path>] [--out <path>]` — Non-interactive CI mode (strict, explicit)
+- `verax inspect <runPath>` — Inspect results from a previous run
+- `verax doctor [--json]` — Verify environment (Node, Playwright, Chromium binary)
+- `verax --version` — Show CLI version
+- `verax --help` — Show help text
 
-Execute a user flow:
-verax flow --flow ./flows/login.json --url <http://localhost:3000>
+## Examples
 
-Outputs
+Run a non-interactive scan (ideal for CI):
 
-Artifacts are written to:
+```bash
+verax run --url http://localhost:3000 --src . --out .verax
+```
 
-.verax/runs/<runId>/
+Run interactive mode (default auto-detection):
 
-Includes:
+```bash
+verax
+```
 
-summary.json — overall results
+Check environment readiness:
 
-findings.json — detected issues with evidence
+```bash
+verax doctor --json
+```
 
-traces.jsonl — interaction traces
+Inspect a previous run:
 
-evidence/ — screenshots and logs
+```bash
+verax inspect .verax/runs/2026-01-11T12-34-56Z_abc123
+```
 
-Exit codes
+📁 Output (CI-friendly)
 
-0 — No HIGH confidence findings
+Run a scan:
 
-1 — MEDIUM / LOW findings only
+```bash
+verax run --url http://localhost:3000 --src . --out .verax
+```
 
-2 — At least one HIGH confidence finding
+Artifacts are written to:
+
+`.verax/runs/<runId>/`
+
+Including:
 
-3 — Fatal error
+- `summary.json` — overall observation summary with digest counts
+- `findings.json` — reported discrepancies with evidence
+- `learn.json` — code-derived expectations
+- `observe.json` — browser observations and outcomes
+- `evidence/` — screenshots and logs
 
-📊 Understanding results
+🚦 Exit codes (tool-only semantics)
 
-Each finding includes:
+Exit codes reflect tool execution status only.
+They do not represent site quality or correctness and must not be used as a pass/fail gate without explicit user logic.
 
-Type — what kind of failure occurred
+0 — VERAX executed successfully (regardless of findings, gaps, or confidence)
 
-Reason — plain English explanation
+2 — Tool crashed or failed internally
 
-Confidence — score (0–100) + level
+64 — Invalid CLI usage (missing args, invalid flags)
 
-Evidence — screenshots, network data, console logs
+65 — Invalid input data (e.g. malformed JSON, unreadable manifest)
 
-Confidence levels:
+📊 Reading results (observer-first)
 
-HIGH (80–100) — strong, unambiguous evidence
+Each reported discrepancy includes:
 
-MEDIUM (60–79) — likely failure with some ambiguity
+Promise context: navigation, network action, state change, feedback
 
-LOW (<60) — weak or partial evidence
+Outcome classification: silent failure, coverage gap, unproven interaction, safety block, informational
 
-VERAX prefers missing an issue over reporting a false one.
+Evidence: screenshots, network artifacts, console logs, trace references
 
-🔐 Safety and privacy
+Confidence: coverage ratio and silence impact
 
-🔒 No guessing
+Confidence (observer truth)
 
-🧹 Automatic redaction of secrets and personal data
+Confidence reflects the quality and completeness of observation,
+not the quality or correctness of the site.
 
-🛑 Safe by default — blocks destructive actions unless explicitly allowed
+HIGH (≥80) — strong evidence and coverage; observations are reliable
 
-🧭 Flows are opt-in only — nothing runs without your definition
+MEDIUM (60–79) — likely discrepancy with some ambiguity
 
-🎯 When VERAX is a good fit
+LOW (<60) — weak or partial evidence; interpret cautiously
 
-Marketing and public-facing websites
+🧭 When VERAX is a good fit
 
 SaaS signup and pricing flows
 
 React and Next.js projects
 
-CI pipelines that need UX validation
+CI pipelines that need UX reality checks
 
 Teams that value evidence over assumptions
 
@@ -232,6 +259,14 @@ It is designed for early adopters and technical teams.
 VERAX is not a SaaS product.
 It runs locally or in CI. There is no hosted service.
 
+⚠ Important
+
+VERAX does not certify correctness.
+Zero findings do not mean a site is safe.
+
+VERAX exists to prevent false certainty, not to grant confidence.
+Use the Decision Snapshot and evidence to make a human judgment.
+
 📄 License
 
 MIT