@vitronai/alethia 0.3.11 → 0.3.12

package/README.md

@@ -1,7 +1,6 @@
 # @vitronai/alethia
 
-> **The MIT-licensed MCP bridge to Alethia** — the patent-pending zero-IPC E2E test runtime built for AI agents.
-> **45× faster than Playwright** on the localhost test loop. Fail-closed by default. Cryptographically chained audit packs. **Local-first. Zero telemetry by default. Opt-in cloud.**
+**The MCP bridge to Alethia** — AI agents test your app with plain English. ~13 ms per step, 45x faster than Playwright. Safe by default. Local-first. Zero telemetry.
 
 [![npm version](https://img.shields.io/npm/v/@vitronai/alethia.svg?logo=npm&logoColor=white)](https://www.npmjs.com/package/@vitronai/alethia)
 [![License: MIT](https://img.shields.io/badge/bridge-MIT-green.svg?logo=opensourceinitiative&logoColor=white)](./LICENSE)
@@ -11,42 +10,11 @@
 
 ---
 
-## ⚠️ This is the MCP bridge — the runtime is separate
+## What this package does
 
-**This npm package is the open-source MCP bridge — a thin (~22 KB) stdio→HTTP relay**, MIT-licensed and freely usable. It does not contain the runtime. By itself it cannot drive a browser, run a test, or do anything except forward MCP requests to a local HTTP endpoint.
+This npm package is the **MIT-licensed MCP bridge** (~22 KB) — a thin stdio-to-HTTP relay. It auto-downloads the signed Alethia headless runtime on first use. No signup, no manual steps.
 
-**The Alethia desktop runtime** — the part that actually contains the patent-pending in-process zero-IPC executor, the VITRON-EA1 policy gate, and the NLP compiler — is **closed-source and patent-pending**. As of v0.3, the bridge **auto-downloads the signed runtime on first use** — no manual steps, no signup required.
-
-| Component | License | How to get it |
-|---|---|---|
-| `@vitronai/alethia` (this npm package — the MCP bridge) | **MIT, open source** | `npm install -g @vitronai/alethia` |
-| Bridge source mirror | **MIT, open source** | [github.com/vitron-ai/alethia-mcp](https://github.com/vitron-ai/alethia-mcp) |
-| **Alethia desktop runtime** (the patented in-process executor) | **Closed-source, Patent Pending — U.S. App. 19/571,437** | Auto-installed by the bridge on first use. Ed25519 verified. |
-
-**The MIT license on this bridge does not, under any circumstances, grant any patent license under U.S. Application No. 19/571,437 or any other vitron.ai patent rights.** The runtime is a separate licensable artifact.
-
-**Bottom line for developers:** `npm install -g @vitronai/alethia` gets you everything you need. The bridge auto-downloads the signed headless runtime on first use. Commercial and production use of the runtime may require a patent license once the patent grants. For licensing inquiries: **gatekeeper@vitron.ai**.
-
----
-
-## Why Alethia?
-
-Your agent generates a Next.js app on `localhost:3000` and your users want it verified. Playwright adds **600ms of CDP marshalling tax** to every assertion — and worse, it's async-by-construction, so the agent's decide-act-verify loop is racing against stale DOM snapshots between every `await`.
-
-Alethia is a different shape entirely. The driver and the DOM live in **the same V8 isolate**:
-
-| | Playwright (CDP) | Alethia (zero-IPC) |
-|---|---|---|
-| Avg latency per step | 580 ms | **13 ms** |
-| p95 latency per step | 654 ms | **24 ms** |
-| Process boundary | 3 (test ↔ driver ↔ browser) | **0** between driver and DOM |
-| DOM access | async, marshalled, race-prone | **synchronous, in-process** |
-| Per-step safety policy | none | **VITRON-EA1 fail-closed gate** |
-| Audit trail | trace viewer (debugging) | **SHA-256 chained, Ed25519 signable** |
-| Telemetry | on by default in cloud product | **off by default; opt-in only** |
-| Patent moat | none | **U.S. App 19/571,437** |
-
-Benchmarks: `click-assert-wait` scenario, 20 iterations.
+> **Note:** The MIT license on this bridge does **not** grant a patent license to the Alethia runtime (U.S. App. 19/571,437). Commercial use of the runtime may require a separate license. Contact **gatekeeper@vitron.ai**.
 
 ---
 
@@ -56,17 +24,12 @@ Benchmarks: `click-assert-wait` scenario, 20 iterations.
 npm install -g @vitronai/alethia
 ```
 
-That's it. The bridge auto-downloads the signed headless runtime on first use — Ed25519 verified, SHA-256 checked, no signup required.
-
-### Verify the install
+Verify:
 
 ```bash
-alethia-mcp --version
 alethia-mcp --health-check
 ```
 
-Expected:
-
 ```
 ✓ Connected. MCP tools available.
   runtime version:  0.1.0-alpha.4
@@ -102,7 +65,7 @@ Cursor → Settings → MCP → Add server:
 
 ### Cline / Continue / any MCP client
 
-Same shape. Any MCP-compatible client speaks the standard stdio protocol — point it at the `alethia-mcp` command.
+Same shape — point any MCP-compatible client at the `alethia-mcp` command.
 
 ### Claude Desktop
 
@@ -119,141 +82,56 @@ Same shape. Any MCP-compatible client speaks the standard stdio protocol — poi
 }
 ```
 
-After saving the config, restart your MCP client.
-
 ---
 
 ## Usage
 
-Once configured, your agent has the full Alethia tool suite available. The most common one:
+Once configured, ask your agent to test something:
 
 > *"Use alethia_tell to navigate to the incident response page, assert the critical alert is visible, click Acknowledge, and assert it changed to Acknowledged."*
 
-The agent calls `alethia_tell` with plain English. Alethia compiles it to Action IR, runs each step through the VITRON-EA1 policy gate, and returns per-step results, DOM diffs (what changed), a semantic page snapshot, policy audit records, and a SHA-256 integrity hash.
+Alethia compiles plain English to Action IR, runs each step through the safety gate, and returns per-step results, a semantic page snapshot (~200 tokens), DOM diffs, policy audit records, and a SHA-256 integrity hash.
 
 ---
 
-## Demos
-
-This package ships with ready-to-use demo pages in the `demo/` folder. Each page showcases different Alethia capabilities — copy the prompt into Claude Code, Cursor, or any MCP client:
+## Tools
 
-| Demo | What it shows |
+| Tool | Purpose |
 |---|---|
-| `incident-response.html` | Defense / SOC — triage active cyber incident, EA1 blocks network isolation |
-| `threat-intel.html` | Intelligence / CTI — APT tracking, IOC blocking, MITRE ATT&CK correlation |
-| `crypto-readiness.html` | Cybersecurity / PQC — post-quantum migration, certificate revocation |
-| `agent-oversight.html` | AI Safety — autonomous agent monitoring, kill switch, policy violations |
-| `admin-panel.html` | Defense / Classified — TS/SCI admin, EA1 blocks user deletion |
-| `financial-dashboard.html` | Finance / Trading — risk monitor, compliance checks, EA1 blocks liquidation |
-
-Find the demos at:
-```bash
-# Global install
-ls $(npm root -g)/@vitronai/alethia/demo/
-
-# Or clone the source
-git clone https://github.com/vitron-ai/alethia-mcp.git
-ls alethia-mcp/demo/
-```
-
-Full prompts for each demo: [`demo/README.md`](./demo/README.md)
+| `alethia_tell` | Run plain-English test steps. The main tool. ~13 ms/step. |
+| `alethia_tell_parallel` | Run multiple test flows concurrently against different URLs. |
+| `alethia_screenshot` | Capture a PNG of the current page. |
+| `alethia_compile` | Preview what `tell` will run, without executing. |
+| `alethia_eval` | Run raw JavaScript in the page under test. |
+| `alethia_status` | Health check — version, config, kill switch state. |
+| `alethia_audit_wcag` | WCAG 2.1 AA accessibility audit (14 criteria, Section 508). |
+| `alethia_audit_nist` | NIST SP 800-53 security controls audit (8 controls). |
+| `alethia_export_session` | Export a signed evidence pack of the entire session. |
+| `alethia_activate_kill_switch` | Emergency halt — stops all automation immediately. |
+| `alethia_reset_kill_switch` | Resume after a kill switch activation. |
+
+Destructive actions (delete, purchase, transfer) are **blocked by default** under the `controlled-web` profile. Sensitive input (passwords, credit cards) is **always blocked** unless `allowSensitiveInput: true` is explicitly passed.
 
 ---
 
-## Tools
-
-### `alethia_tell`
-Execute natural-language test instructions. The headline tool.
-
-```
-nlp: "navigate to file:///path/to/demo/incident-response.html
-      assert CRITICAL INCIDENT ACTIVE is visible
-      click Acknowledge
-      assert Acknowledged is visible"
-```
-
-Returns a `PlanRun`:
-```json
-{
-  "ok": true,
-  "elapsedMs": 87,
-  "stepRuns": [ /* per-step results */ ],
-  "policyAudits": [ /* per-step EA1 decisions */ ],
-  "integrity": {
-    "algorithm": "sha256",
-    "schemaVersion": "plan-run-v1",
-    "payloadHash": "..."
-  }
-}
-```
-
-By default, **destructive actions are blocked** (`controlled-web` profile). The runtime catches verbs like *delete, purchase, transfer, submit payment* via NLP intent inference and prepends `!://write-high` markers in the IR. Sensitive input (passwords, credit cards, SSN) is **always blocked** unless the caller explicitly opts in via `allowSensitiveInput: true`.
-
-### `alethia_compile`
-Compile NL to Action IR **without executing**. Use this to preview what `alethia_tell` will run, debug NLP coverage gaps, or generate reproducible IR scripts for CI.
-
-### `alethia_status`
-Liveness probe + identity. Returns runtime version, default policy profile, kill switch state, driver stats, current page domain, and capabilities. Call this before sending `tell()` calls to verify the runtime is in a known-good state.
-
-### `alethia_activate_kill_switch`
-**Halt all current and queued automation immediately.** Per-step policy gate stays armed; subsequent `tell()` calls will be blocked with `KILL_SWITCH_ACTIVE` until reset. Optional `reason` argument lands in the audit trail.
-
-### `alethia_reset_kill_switch`
-Clear an active kill switch and reset the shared executor state. Re-enables `tell()` calls. The reset itself is logged.
-
-### `alethia_screenshot`
-Capture a PNG screenshot of the current page and return it as a base64-encoded image. Use this to visually verify what the browser is showing after running test steps with `alethia_tell`.
-
-### `alethia_eval`
-Evaluate a JavaScript expression in the page under test and return the result. Runs in the context of the navigated page, not the Alethia host UI. Use this for queries the NLP compiler cannot express — counting elements, reading computed styles, checking localStorage, or any DOM inspection that needs raw JS.
-
-### `alethia_audit_wcag`
-Run a WCAG 2.1 AA accessibility audit on the current page. Checks 14 criteria including alt text, form labels, keyboard access, page title, lang attribute, link purpose, heading structure, and duplicate IDs. Returns findings with WCAG criterion numbers, severity levels (A/AA), and issue counts. Designed for Section 508 compliance workflows.
-
-### `alethia_audit_nist`
-Run a NIST SP 800-53 Rev. 5 web application security controls audit on the current page. Checks 8 controls across 3 families: AC (login lockout, security banners, session timeout), IA (unmasked passwords, weak password constraints, MFA indicators), SI (input validation, error information leakage). Returns findings with control IDs, severity levels (CRITICAL/HIGH/MEDIUM/LOW), and metadata.
-
-### `alethia_export_session`
-Export the full session recording as a signed evidence pack. Contains every tool call made during this session with timestamps, inputs, outputs, policy decisions, runtime info, and a SHA-256 integrity hash over the entire record. Use at the end of an agent loop to produce cryptographic proof of everything the agent did. Designed for compliance review, audit trails, and chain-of-custody documentation.
-
-### `alethia_tell_parallel`
-Run multiple test flows concurrently — each against a different URL. Takes an array of test specs (url + nlp steps), spawns a browser instance per spec, runs them in parallel, and returns all results together. 3 pages in ~260ms vs ~700ms sequential. Scales linearly.
+## Demos
 
----
+Ready-to-use demo pages ship in the `demo/` folder:
 
-## Architecture
+| Demo | Scenario |
+|---|---|
+| `incident-response.html` | Defense / SOC — triage active cyber incident |
+| `threat-intel.html` | Intelligence / CTI — APT tracking, IOC blocking |
+| `crypto-readiness.html` | Cybersecurity / PQC — post-quantum migration |
+| `agent-oversight.html` | AI Safety — autonomous agent monitoring, kill switch |
+| `admin-panel.html` | Defense / Classified — TS/SCI admin panel |
+| `financial-dashboard.html` | Finance / Trading — risk monitor, compliance checks |
 
-```
-┌────────────────────────┐
-│  Your AI agent         │  Claude Code / Cursor / Cline / Continue / ...
-│  speaks MCP stdio      │
-└──────────┬─────────────┘
-           │ stdio (JSON-RPC over newline-delimited JSON)
-           ↓
-┌────────────────────────┐
-│  @vitronai/alethia     │  This npm package — ~22 KB
-│  stdio → HTTP shim     │  - speaks MCP stdio inbound
-└──────────┬─────────────┘  - wraps results in MCP content envelope
-           │ HTTP POST 127.0.0.1:47432 (loopback only, never networked)
-           ↓
-┌────────────────────────┐
-│  Alethia runtime       │  Main process — proprietary, patent pending
-│  local JSON-RPC server │  - tools/list, tools/call
-└──────────┬─────────────┘  - loopback bind, never reachable from network
-           │ in-process JS bridge
-           ↓
-┌────────────────────────┐
-│  Alethia renderer      │  Embedded browser — IS the browser
-│  zero-IPC runtime      │  - tell() → NLP compiler → Action IR
-└──────────┬─────────────┘  - VITRON-EA1 policy gate (per-step, fail-closed)
-           │ direct DOM access (no protocol, no marshalling)
-           ↓
-┌────────────────────────┐
-│  The page under test   │
-└────────────────────────┘
+```bash
+ls $(npm root -g)/@vitronai/alethia/demo/
 ```
 
-**Two process boundaries** between your agent and the runtime (agent ↔ shim, shim ↔ runtime). Then **zero** boundaries between the runtime and the DOM. That's the architectural difference that makes Alethia 45× faster than Playwright.
+Full prompts for each demo: [`demo/README.md`](./demo/README.md)
 
 ---
 
@@ -274,7 +152,7 @@ alethia-mcp --debug          Run with debug logging on stderr
 | `ALETHIA_HOST` | `127.0.0.1` | Host of the Alethia runtime |
 | `ALETHIA_PORT` | `47432` | Port of the Alethia runtime |
 | `ALETHIA_TIMEOUT_MS` | `60000` | Per-request timeout in milliseconds |
-| `ALETHIA_DEBUG` | (unset) | Set to `1` to enable debug logging on stderr |
+| `ALETHIA_DEBUG` | (unset) | Set to `1` for debug logging on stderr |
 
 ---
 
@@ -282,86 +160,41 @@ alethia-mcp --debug          Run with debug logging on stderr
 
 ### "Alethia desktop runtime is not running on 127.0.0.1:47432"
 
-The bridge auto-installs the headless runtime on first use. If you're seeing this error:
-
-1. Run `alethia-mcp --health-check` — this will trigger auto-install if the runtime isn't present yet
-2. Check that the runtime process is running (it binds to `127.0.0.1:47432`)
-3. If auto-install failed, check your network connection and try again
-
-Once the runtime is running, you should see:
-
-```
-[alethia] local RPC server listening on 127.0.0.1:47432
-```
-
-Then re-run your MCP client and `alethia-mcp --health-check` should print `✓ Connected`.
+1. Run `alethia-mcp --health-check` — triggers auto-install if the runtime isn't present
+2. Check that the runtime process is running on `127.0.0.1:47432`
+3. If auto-install failed, check your network and try again
 
 ### "DENY_WRITE_HIGH" in the audit log
 
-The runtime blocked a destructive action under the default fail-closed policy. **This is correct behaviour** for an AI-agent-facing test runtime — destructive actions need explicit consent.
-
-To allow them, pass `{ profile: 'open-web' }` in the `alethia_tell` arguments. But understand: you're opting out of the safety gate.
+A destructive action was blocked by the default safety policy. **This is correct behavior.** To allow it, pass `{ profile: 'open-web' }` — but understand you're opting out of the safety gate.
 
 ### "SENSITIVE_INPUT_DENIED"
 
-The runtime blocked typing into what looks like a sensitive field (matches `password`, `token`, `secret`, `credit card`, `ssn`, etc.). To override for a legitimate auth-flow test:
-
-```json
-{ "nlp": "...", "allowSensitiveInput": true }
-```
-
-Only do this when you are knowingly testing a real auth or payment flow.
+A sensitive field was detected (password, token, credit card, etc.). Override with `{ "allowSensitiveInput": true }` only for legitimate auth/payment flow testing.
 
 ### MCP client doesn't see the tools
 
-1. Verify the runtime is running: `alethia-mcp --health-check`
-2. Verify your MCP config points at the correct command
-3. Restart your MCP client (some clients cache server lists)
-4. Run with debug logging: set `ALETHIA_DEBUG=1` in your MCP config's `env` section
-
-### `Script failed to execute`
-
-The runtime hasn't loaded `window.__alethia` yet (or crashed). Restart the runtime. If it persists, file an issue.
+1. Verify: `alethia-mcp --health-check`
+2. Check your MCP config
+3. Restart your MCP client
+4. Debug: set `ALETHIA_DEBUG=1`
 
 ---
 
-## Privacy & data flow
-
-Alethia is **local-first with zero telemetry by default.**
+## Go deeper
 
-- **The MCP bridge** (this npm package) only speaks to `127.0.0.1` (loopback). It cannot reach any other host. No data leaves your machine through the bridge — verify yourself by reading [`src/index.ts`](./src/index.ts), it's ~590 lines, single file.
-- **The desktop runtime** has a production request filter that blocks all non-`file://`, non-`app://`, non-`localhost` requests. The runtime is **architecturally loopback-only** in production builds.
-- **Zero telemetry collection** in v0.2 — the runtime does not phone home, does not collect usage metrics, does not report crashes anywhere by default.
-- **Future cloud features** (signed evidence as a service, team dashboards, agent observability) will be **opt-in only**, clearly labeled, with disclosed data flow. They are separate paid products you explicitly enroll in — not defaults that turn on silently.
-
-The bottom line: **what you install today does nothing on the network beyond your machine.** When the cloud product ships, it's a separate, opt-in choice you make explicitly.
+- [Architecture & how it works](https://vitron.ai/why)
+- [VITRON-EA1 safety standard](https://vitron.ai/safety)
+- [FAQ](https://vitron.ai/faq)
+- [Releases](https://github.com/vitron-ai/alethia/releases)
+- [Homepage](https://github.com/vitron-ai/alethia)
 
 ---
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
-
-The MIT license covers **this MCP bridge package only**. The underlying The Alethia runtime runtime is proprietary and closed-source.
+MIT — see [LICENSE](./LICENSE). Covers **this MCP bridge only.**
 
 ## Patent Notice
 
-The Alethia runtime practices a method that is the subject of:
-
-- **U.S. Patent Application No. 19/571,437** (non-provisional)
-- Claiming priority to **U.S. Provisional Application No. 63/785,814** (filed April 9, 2025)
-- **Title:** *"Deterministic Local Automation Runtime with Zero-IPC Execution, Offline Operation, and Per-Step Policy Enforcement"*
-- **Status:** Patent Pending — U.S. Patent and Trademark Office
-
-The MIT license on this MCP bridge does **not** grant any patent license under U.S. Application No. 19/571,437 or any other vitron.ai patent rights.
-
-For licensing inquiries: **gatekeeper@vitron.ai**
-
----
-
-## Links
-
-- 🏠 Homepage: [github.com/vitron-ai/alethia](https://github.com/vitron-ai/alethia)
-- 📦 Source: [github.com/vitron-ai/alethia-mcp](https://github.com/vitron-ai/alethia-mcp)
-- 📥 Releases: [github.com/vitron-ai/alethia/releases](https://github.com/vitron-ai/alethia/releases)
-- 📧 Licensing: gatekeeper@vitron.ai
+The Alethia runtime is patent pending (U.S. Application No. 19/571,437). The MIT license on this bridge does **not** grant any patent license. For licensing: **gatekeeper@vitron.ai**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/alethia",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "MIT-licensed MCP bridge to the Alethia runtime — the patent-pending zero-IPC E2E test runtime built for AI agents. 45x faster than Playwright. Local-first, zero telemetry. WCAG + NIST 800-53 compliance audits built in. Auto-installs on first use.",
   "type": "module",
   "main": "dist/index.js",