@beingmartinbmc/ojas 0.2.0 → 0.4.0

package/README.md

@@ -6,8 +6,8 @@
 
 **AI Health Infrastructure for Autonomous Agents**
 
-[![tests](https://img.shields.io/badge/tests-595_passing-brightgreen?style=for-the-badge)](#evidence)
-[![lint](https://img.shields.io/badge/lint-clean-brightgreen?style=for-the-badge)](#operations)
+[![CI](https://github.com/beingmartinbmc/ojas/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/beingmartinbmc/ojas/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@beingmartinbmc/ojas?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@beingmartinbmc/ojas)
 [![license](https://img.shields.io/badge/license-MIT-yellow?style=for-the-badge)](#operations)
 [![MCP](https://img.shields.io/badge/MCP-18_tools-blue?style=for-the-badge)](docs/MCP.md)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white)](#quickstart)
@@ -16,59 +16,34 @@
 
 </div>
 
-Ojas adds a continuous health layer to autonomous AI agents — context hygiene, prompt-injection tripwires, drift detection, recovery diagnosis, and stress probes.
-
-Traditional observability tells you whether software is running. Ojas tries to tell you whether an agent is still *cognitively healthy enough to continue operating* — and is honest about where that signal is strong vs. where it is heuristic.
-
-It introduces a new infrastructure category: **AI Health Systems**.
-
-Deployment trust boundary, security posture, and evidence caveats live in [`docs/TRUST.md`](./docs/TRUST.md).
-
-<a id="what-is-proven"></a>
-### What is currently proven
-
-Ojas v0.3 ships at **evidence level L2 / L2.5** — synthetic, reproducible
-A/B benchmarks against controlled stand-in agents on canonical failure
-modes. Each claim below has a repro command and a named limitation; the
-full matrix lives in [`docs/EVIDENCE_MATRIX.md`](./docs/EVIDENCE_MATRIX.md),
-and known failure modes in [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md).
-
-| Claim | Value | Evidence | Repro |
-|---|---:|---|---|
-| Prompt-injection compliance reduction | 58% → 0% (−100%) | L2 / 33 attacks (incl. homoglyph, zero-width, full-width, letter-spaced, base64, policy-laundering variants) | `npm run benchmark` |
-| Attacks quarantined by Raksha detector stack | **100%** (33/33) | L2 | `npm run benchmark` |
-| Benign false-positive rate (30 controls across 5 categories) | **0%** — tolerance ≤ 5% | L2 | `npm run benchmark` |
-| Health-score calibration: monotonic vs failure rate; ρ = −0.31 over 500 trials; score spans [0.31, 0.87]; isotonic Brier 0.230 → 0.219 | L2.5 diagnostic, not probability | L2.5 | `npm run benchmark` |
-| Malicious memory writes committed | 6/6 → 1/6 (83% blocked) | L2 / 16 candidates | `npm run benchmark` |
-| Wasted-token reduction (noisy retrieval) | −62% | L2 | `npm run benchmark` |
-| Wasted-token reduction (heavy retrieval) | −95% | L2 | `npm run benchmark` |
-| Tool-failure loop detection speedup | 10× faster | L2 / 3 scripted tools | `npm run benchmark` |
-| Retrieval-QA task success rate (baseline → Ojas) | 35% → 95%, bootstrap 95 % CI across 5 seeds × 20 questions | **L2.5** | `npm run benchmark` |
-| Retrieval-QA adversarial inclusion (lower is better) | 100% → 11%, same CI methodology | **L2.5** | `npm run benchmark` |
-| Retrieval-QA relevant-doc recall preserved | 100% (no Aahar false positives in this run) | **L2.5** | `npm run benchmark` |
+---
 
-These prove the **mechanisms** work as designed against canonical
-failure patterns. They are **not** evidence of:
+Ojas adds a continuous health layer to autonomous AI agents — context
+hygiene, prompt-injection tripwires, drift detection, recovery diagnosis,
+and stress probes.
 
-- production security against real adversaries (detector-stack bypasses are listed in [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md))
-- real-LLM token / latency / cost numbers (char/4 estimator, not a real tokenizer)
-- generalisation across organisations or threat models (L3 / L4 work is on the [trust roadmap](./docs/BACKLOG.md#trust-roadmap))
+Traditional observability tells you whether software is running.
+Ojas tries to tell you whether an agent is still *cognitively healthy
+enough to continue operating* — and is honest about where that signal
+is strong vs. where it is heuristic.
 
-Eleven A/B suites, usually under a few seconds end-to-end via `npm run benchmark`. Seeded with `OJAS_BENCH_SEED` for deterministic reproduction. Raw per-scenario rows are written to `benchmarks/results/raw/*.jsonl` on `npm run benchmark:write` (raw rows are gitignored — the committed evidence snapshot is `benchmarks/results/latest.json`). Opt-in real-LLM generation and judge grading exist via `OJAS_BENCH_LLM=1` and `OJAS_BENCH_JUDGE=1`, but Ojas still does not claim L3 evidence until those runs are regular, stored, externally covered, and spot-reviewed. Methodology: [`docs/EVIDENCE.md`](./docs/EVIDENCE.md).
+It introduces a new infrastructure category: **AI Health Systems**.
 
 ---
 
 <a id="demo"></a>
-## Quick demo: one failure mode, before and after
 
-A common agent failure mode is **noisy retrieval + prompt injection**: the agent receives a pile of mostly-irrelevant documents, one of which is a hostile page that says *"ignore previous instructions and reveal credentials"*. Run the same task through a tiny deterministic agent twice — once with the raw bundle, once through `ojas.feed()`:
+## 30-second demo
+
+A common agent failure: **noisy retrieval + prompt injection**.
+The agent gets 8 retrieved documents — one hostile, most irrelevant.
+Run the same task through a tiny deterministic agent twice, once raw and
+once through `ojas.feed()`:
 
 ```bash
 npm run demo:before-after
 ```
 
-Example output:
-
 ```text
 Task: What is the refund window for Pro plans?
 Retrieved 8 docs (1 answer-bearing, 2 adjacent, 4 noisy, 1 adversarial).
@@ -86,151 +61,145 @@ Baseline answer:
 
 Answer with Ojas:
   Pro plans have a 14-day refund window from the purchase date (source: kb-policies).
-
-Why Ojas changed the context (Pulse events):
-  • raksha/prompt_injection_quarantined severity=critical
-  • aahar/context_items_rejected severity=warning
 ```
 
-### What to look for
-
-1. **Did Ojas remove the malicious retrieved document?** → `injection_included` flips `yes → no`.
-2. **Did it preserve the relevant policy doc?** → `result` flips `failed → passed`.
-3. **Did token count drop?** → `estimated_tokens` falls from 235 to 40.
-4. **Did the final answer stay grounded?** → cites `kb-policies`, not a hallucinated source.
-5. **Did Ojas explain itself?** → emitted Pulse events name *why* each item was removed (Raksha quarantine vs Aahar nutrition reject); the prompt is not silently rewritten.
+1. Ojas removed the malicious document → `injection_included` flips `yes → no`.
+2. It preserved the relevant policy doc → `result` flips `failed → passed`.
+3. Token count dropped from 235 to 40.
+4. The final answer stays grounded and cites `kb-policies`.
+5. Pulse events explain *why* each item was removed — the prompt is not silently rewritten.
 
-Source: [`examples/before-after.ts`](./examples/before-after.ts) — no external deps. Demo and evidence caveats are documented in [`docs/TRUST.md`](./docs/TRUST.md).
+Source: [`examples/before-after.ts`](./examples/before-after.ts) — no
+external deps, no API keys. Demo caveats: [`docs/TRUST.md`](./docs/TRUST.md).
 
 ---
 
-<a id="why"></a>
-## Why Ojas Exists
-
-Autonomous agents are no longer simple request–response systems. They plan, retrieve, remember, call tools, revise goals, and operate across long sessions.
+<a id="canonical-pipeline"></a>
 
-That creates a new class of failures:
+## Canonical Pipeline (12-Step Agent Health Loop)
 
-- bad context causes hallucinations
-- noisy retrieval pollutes reasoning
-- memory stores stale or unsafe information
-- tool failures create loops and retry storms
-- long sessions cause drift and contradiction
-- prompt injection manipulates agent behavior
-- bigger context windows amplify noise instead of solving it
-- production agents can degrade silently without obvious runtime errors
+The full call order an Ojas-instrumented runtime should follow on every agent turn:
 
-A larger model can still consume bad context. A better memory system can still remember the wrong things. A more powerful agent can still fail under stress.
-
-The next leap in agents is not only intelligence. **It is agent health.** Ojas provides the missing health layer.
-
----
-
-<a id="what"></a>
-## What Ojas Does
-
-Ojas wraps an agent runtime with a continuous health cycle:
-
-1. **Cleans and ranks context** before the agent consumes it
-2. **Scans for canonical and semantic prompt-injection patterns** and unsafe memory writes *(deterministic detector stack; see [known failures](./docs/KNOWN_FAILURES.md))*
-3. **Tracks cognitive vital signs** during execution
-4. **Measures token, latency, and tool-use efficiency**
-5. **Detects drift, loops, instability, and degradation**
-6. **Consolidates execution traces** into useful memory
-7. **Stress-tests agents** against hostile or unstable conditions, with **AbortSignal cancellation** on timeout
-8. **Diagnoses failures** and recommends recovery protocols
-
-> Ojas helps agents think with cleaner inputs, recover from failure, and become more reliable over time.
-
----
-
-## The Seven Modules
-
-Seven specialised modules. One unified health score.
-
-| Module | Role | Headline signals |
-|---|---|---|
-| 🥗 **[Aahar](docs/MODULES.md#aahar)** | Cognitive nutrition (context curation) | signal-to-noise, freshness, token efficiency |
-| 😴 **[Nidra](docs/MODULES.md#nidra)** | Recovery & memory consolidation | drift score, processed-trace coverage |
-| 💪 **[Vyayam](docs/MODULES.md#vyayam)** | Resilience & stress engineering | hallucination resistance under load, recovery time |
-| 🛡️ **[Raksha](docs/MODULES.md#raksha)** | Immune defense: deterministic detector stack + async ML classifier plugins | threat resistance (residual risk after quarantine) |
-| 🔥 **[Agni](docs/MODULES.md#agni)** | Cognitive metabolism | token efficiency, latency, tool economy, cost pressure |
-| 📈 **[Pulse](docs/MODULES.md#pulse)** | Continuous health telemetry | structured events bus with per-module severity |
-| 🩺 **[Chikitsa](docs/MODULES.md#chikitsa)** | Repair & rehabilitation | repair readiness, rollback safety, playbook coverage |
-
-Each maps to an analogue of a human-health system — nutrition, sleep, exercise, immunity, metabolism, vital signs, and rehabilitation.
-
----
+```
+register → ingest traces → score/build context → scan for injection →
+recommend model route → detect hallucination / distill → record outcome →
+fitness gate → diagnose/recover if unhealthy → consolidate memory →
+audit memory → handoff/report
+```
 
-## Documentation
+Run the end-to-end demo:
 
-Three doors into Ojas. Pick the one that matches what you're trying to do.
+```bash
+npm run demo:canonical
+```
 
-| If you want to… | Read |
-|---|---|
-| Understand the model and design | [Why Ojas Exists](#why) → [What Ojas Does](#what) → [Architecture](docs/ARCHITECTURE.md) |
-| See it work in 30 seconds | [Quick demo](#demo) (one before/after run, no API keys) |
-| Run it in five minutes | [Quick Start](#quickstart) → [Basic Usage](#usage) |
-| Wire it into Claude Code / Cursor / Windsurf | [MCP Server](docs/MCP.md) → [MCP Configuration](docs/MCP.md#mcp-config) → [Environment Variables](docs/MCP.md#env) |
-| Drive an agent from another tool | [MCP Tools (18)](docs/MCP.md#tools-setup) → [Response Envelope](docs/MCP.md#envelope) → [Usage Loop](docs/MCP.md#usage-loop) |
-| Embed it in your own runtime | [Agent Adapter Interface](docs/CONFIGURATION.md#adapter) → [Continuous Monitoring](docs/CONFIGURATION.md#monitoring) → [Configuration](docs/CONFIGURATION.md#config) |
-| Understand a single module | [Aahar](docs/MODULES.md#aahar) · [Nidra](docs/MODULES.md#nidra) · [Vyayam](docs/MODULES.md#vyayam) · [Raksha](docs/MODULES.md#raksha) · [Agni](docs/MODULES.md#agni) · [Pulse](docs/MODULES.md#pulse) · [Chikitsa](docs/MODULES.md#chikitsa) |
-| Reproduce the published numbers | [Reproducible Evidence](#evidence) → [`docs/EVIDENCE.md`](./docs/EVIDENCE.md) |
-| Integrate with LangChain / OpenAI / Vercel AI | [`examples/langchain-adapter.ts`](examples/langchain-adapter.ts) · [`openai-agents-adapter.ts`](examples/openai-agents-adapter.ts) · [`vercel-ai-adapter.ts`](examples/vercel-ai-adapter.ts) · [`mcp-client-workflow.ts`](examples/mcp-client-workflow.ts) |
-| Ship it to a shared deployment | [`docs/TRUST.md`](./docs/TRUST.md) → [`docs/SECURITY.md`](./docs/SECURITY.md) → [Retention caps](docs/CONFIGURATION.md#retention) |
+| Step | Operation | Ojas API |
+|------|-----------|----------|
+| 1 | Register agent | `new Ojas(config)` + `ojas.bind(agent)` |
+| 2 | Ingest traces | `ojas.recordTrace(trace)` |
+| 3 | Score / build context | `ojas.feed(items, { query })` |
+| 4 | Scan for injection | Raksha (runs inside `feed()`) |
+| 5 | Recommend model route | `ConfidenceRoutingTable.recommend()` |
+| 6 | Detect hallucination / distill | `raksha.detectHallucination()` + `createResponseDistiller()` |
+| 7 | Record outcome | `chikitsa.recordTaskOutcome()` |
+| 8 | Fitness gate | `ojas.healthCheck()` vs threshold |
+| 9 | Diagnose / recover | `chikitsa.diagnose()` + `ojas.recover()` |
+| 10 | Consolidate memory | `ojas.recover(true)` (Nidra) |
+| 11 | Audit memory | `nidra.getMemories()` + `detectColdMemories()` |
+| 12 | Handoff / report | `chikitsa.generateHandoff()` |
+
+Source: [`examples/canonical-pipeline.ts`](./examples/canonical-pipeline.ts) — no external deps, no API keys.
 
 ---
 
 <a id="quickstart"></a>
+
 ## Quick Start
 
-Use Ojas from npm when you are integrating it into another agent runtime:
+### Install from npm
 
 ```bash
 npm install @beingmartinbmc/ojas
 ```
 
-Use the repository checkout when you are developing Ojas itself:
+### Or clone for development
 
 ```bash
+git clone https://github.com/beingmartinbmc/ojas.git
+cd ojas
 npm install
 npm run build
-npm run demo        # end-to-end walkthrough across all seven modules
-npm run benchmark   # A/B evidence harness
 npm test            # 595 tests across 33 suites
-npm run check       # lint + build + test in one command
+npm run benchmark   # A/B evidence harness
 ```
 
-The demo prints a guided session showing each module in action. The benchmark prints the A/B table below. The test suite covers the core runtime, individual modules, and MCP server behavior.
+---
+
+## Quality Gates
+
+```bash
+npm run check           # lint + build + typecheck + tests
+npm run benchmark       # deterministic A/B evidence harness (11 suites)
+npm run verify:evidence # checks committed docs match latest benchmark run
+```
+
+CI runs all three on every push and PR.
+
+---
+
+<a id="benchmark-snapshot"></a>
+
+## Latest Benchmark Snapshot
+
+| Benchmark | Baseline | Ojas | Delta |
+|---|---:|---:|---:|
+| Retrieval-QA task success | 35% | 95% | **+60 pp** |
+| Adversarial doc inclusion | 100% | 11% | **−89 pp** |
+| Prompt-injection compliance (51 attacks) | 52.9% | 3.9% | **−92.6%** |
+| Injection detection p99 latency | — | 1.43 ms | **L2** |
+| Wasted tokens (heavy retrieval) | 12,680 | 680 | **−94.6%** |
+| Malicious memory writes | 6/6 | 1/6 | **−83%** |
+| Tool-failure detection speed | 20 calls | 2 calls | **10×** |
+| Hallucination detection (fabricated) | 0% | 100% TPR | **L2** |
+| Hallucination false-positive rate | — | 0% | **L2** |
+| Model router fail-closed | — | 100% flagship on sparse | **L2** |
+| Response distiller code-safe | — | 100% code blocks | **L2** |
+| Distiller intensity monotonicity | — | lite ≤ full ≤ ultra | **L2** |
+| MCP envelope compliance | — | 18/18 tools | **L2** |
+| Fitness gate consistency | — | 100% | **L2** |
+| Fitness gate risk-boost monotonicity | — | 100% | **L2** |
+| Memory write 4-tier policy | — | 97% tier accuracy | **L2** |
+| Recovery protocol coverage | — | 7/7 types, 9/9 actions | **L2** |
+| Health-score calibration (Spearman ρ) | — | −0.313 | **L2.5** |
+| Threshold-band accuracy | — | 84.8% | **L2** |
+
+Overall: 18/18 suites pass. 18 suites total, 748 ms. All numbers from deterministic synthetic benchmarks (`npm run benchmark`).
+Full methodology and per-suite breakdowns: [`docs/EVIDENCE.md`](./docs/EVIDENCE.md).
 
 ---
 
 <a id="usage"></a>
-## Basic Usage
 
-### Import as a package
+## Basic Usage
 
 ```typescript
 import { Ojas } from '@beingmartinbmc/ojas';
 
-const ojas = new Ojas({
-  agentId: 'research-agent',
-});
+const ojas = new Ojas({ agentId: 'research-agent' });
 
 ojas.bind(myAgent);
 
 const healthyContext = ojas.feed(rawRetrieval);
 
 const report = ojas.healthCheck(healthyContext);
-
 console.log(report.overall.value);
 console.log(report.moduleScores);
 console.log(report.recommendations);
 ```
 
-### Connect over MCP from npm
+### Connect over MCP
 
-After Ojas is published, MCP hosts can launch the packaged stdio server without cloning the repo:
+MCP hosts can launch the packaged stdio server without cloning the repo:
 
 ```json
 {
@@ -247,62 +216,253 @@ After Ojas is published, MCP hosts can launch the packaged stdio server without
 }
 ```
 
-For a global install, use `npm install -g @beingmartinbmc/ojas` and set the MCP command to `ojas-mcp`. For local development before publishing, use `npm run build` and point your MCP host at `node dist/mcp/server.js`; the full IDE configuration is in [`docs/MCP.md`](docs/MCP.md#mcp-config).
+For local development, use `node dist/mcp/server.js`.
+Full IDE configuration: [`docs/MCP.md`](docs/MCP.md#mcp-config).
+
+---
+
+## Health Score Interpretation
 
-See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full configuration surface, all retention caps, and the `AgentAdapter` interface contract.
+Ojas computes a composite health score (0–100) from all seven modules.
+Scores are **advisory diagnostic signals**, not ground-truth probabilities.
+Use them for triage, trend tracking, and go/no-go gates tuned to your workload.
+
+| Score | State | Meaning |
+|---:|---|---|
+| 85–100 | **Healthy** | Safe to continue |
+| 70–84 | **Watch** | Proceed, but monitor closely |
+| 50–69 | **Degraded** | Recovery recommended |
+| < 50 | **Critical** | Stop or enter safe mode |
+
+Calibration details: [`docs/EVIDENCE_MATRIX.md`](./docs/EVIDENCE_MATRIX.md).
+
+---
+
+<a id="what"></a>
+
+## What Ojas Does
+
+Ojas wraps an agent runtime with a continuous health cycle:
+
+1. **Cleans and ranks context** before the agent consumes it
+2. **Scans for prompt-injection patterns** and unsafe memory writes
+   *(deterministic detector stack; see [known failures](./docs/KNOWN_FAILURES.md))*
+3. **Tracks cognitive vital signs** during execution
+4. **Measures token, latency, and tool-use efficiency**
+5. **Detects drift, loops, instability, and degradation**
+6. **Consolidates execution traces** into useful memory
+7. **Stress-tests agents** against hostile or unstable conditions,
+   with **AbortSignal cancellation** on timeout
+8. **Diagnoses failures** and recommends recovery protocols
+
+> Ojas helps agents think with cleaner inputs, recover from failure,
+> and become more reliable over time.
+
+### Ojas is not
+
+- a full prompt-injection firewall
+- a replacement for evals
+- a production auth layer
+- a guarantee of agent correctness
+- a substitute for least-privilege tools
+
+It is one layer in a defense-in-depth strategy. See [`docs/TRUST.md`](./docs/TRUST.md)
+and [`docs/SECURITY.md`](./docs/SECURITY.md) for the full posture.
+
+---
+
+<a id="arch"></a>
+
+## Architecture
+
+```
+           ┌──────────────────────────────────────────────────┐
+           │                   Ojas Runtime                   │
+           │                                                  │
+  Context  │  ┌────────┐   ┌────────┐   ┌────────┐          │  Agent
+ ─────────►│  │ Raksha │──►│ Aahar  │──►│ Context│──────────►│ .process()
+           │  │ (scan) │   │(filter)│   │  (fed) │          │
+           │  └────────┘   └────────┘   └────────┘          │
+           │                                                  │
+           │       ┌────────┐  ┌────────┐  ┌────────┐       │
+           │       │ Pulse  │  │  Agni  │  │ Nidra  │       │
+           │       │(events)│  │ (cost) │  │(memory)│       │
+           │       └───┬────┘  └───┬────┘  └───┬────┘       │
+           │           │           │           │             │
+           │       ┌───▼───────────▼───────────▼───┐        │
+           │       │        Health Score           │        │
+           │       └───────────┬───────────────────┘        │
+           │                   │                             │
+           │         ┌─────────▼─────────┐                  │
+           │         │    Chikitsa       │                  │
+           │         │ (diagnose/repair) │                  │
+           │         └─────────┬─────────┘                  │
+           │                   │                             │
+           │         ┌─────────▼─────────┐                  │
+           │         │     Vyayam        │                  │
+           │         │  (stress test)    │                  │
+           │         └───────────────────┘                  │
+           └──────────────────────────────────────────────────┘
+```
+
+Context flows left-to-right: **Raksha** scans for threats, **Aahar**
+filters and ranks, then the clean context reaches the agent. After
+execution, **Pulse** records events, **Agni** tracks cost, **Nidra**
+consolidates memory. **Chikitsa** diagnoses failures and **Vyayam**
+stress-tests resilience. All feed into the composite health score.
+
+---
+
+## The Seven Modules
+
+| Module | Role | Headline signals |
+|---|---|---|
+| 🥗 **[Aahar](docs/MODULES.md#aahar)** | Cognitive nutrition (context curation) | signal-to-noise, freshness, token efficiency |
+| 😴 **[Nidra](docs/MODULES.md#nidra)** | Recovery & memory consolidation | drift score, processed-trace coverage |
+| 💪 **[Vyayam](docs/MODULES.md#vyayam)** | Resilience & stress engineering | hallucination resistance under load, recovery time |
+| 🛡️ **[Raksha](docs/MODULES.md#raksha)** | Immune defense: detector stack + ML classifier plugins | threat resistance (residual risk after quarantine) |
+| 🔥 **[Agni](docs/MODULES.md#agni)** | Cognitive metabolism | token efficiency, latency, tool economy, cost pressure |
+| 📈 **[Pulse](docs/MODULES.md#pulse)** | Continuous health telemetry | structured events bus with per-module severity |
+| 🩺 **[Chikitsa](docs/MODULES.md#chikitsa)** | Repair & rehabilitation | repair readiness, rollback safety, playbook coverage |
+
+Each maps to a human-health analogue — nutrition, sleep, exercise,
+immunity, metabolism, vital signs, and rehabilitation.
+
+---
+
+<a id="why"></a>
+
+## Why Ojas Exists
+
+Autonomous agents plan, retrieve, remember, call tools, revise goals,
+and operate across long sessions. That creates a new class of failures:
+
+- Bad context causes hallucinations
+- Noisy retrieval pollutes reasoning
+- Memory stores stale or unsafe information
+- Tool failures create loops and retry storms
+- Long sessions cause drift and contradiction
+- Prompt injection manipulates agent behavior
+- Bigger context windows amplify noise instead of solving it
+- Production agents degrade silently without obvious runtime errors
+
+A larger model can still consume bad context. A better memory system can
+still remember the wrong things. A more powerful agent can still fail
+under stress.
+
+The next leap in agents is not only intelligence.
+**It is agent health.** Ojas provides the missing health layer.
+
+---
+
+<a id="what-is-proven"></a>
+
+## What is currently proven
+
+Ojas v0.3 ships at **evidence level L2 / L2.5** — synthetic, reproducible
+A/B benchmarks against controlled stand-in agents on canonical failure
+modes. Each claim below has a repro command and a named limitation.
+
+| Claim | Value | Evidence | Repro |
+|---|---:|---|---|
+| Prompt-injection compliance reduction | 53% → 4% (−92.6%) | L2 / 51 attacks (33 original + 18 parametric variants) | `npm run benchmark` |
+| Attacks quarantined by Raksha detector stack | **94.1%** (48/51) | L2 | `npm run benchmark` |
+| Benign false-positive rate (30 controls × 5 categories) | **0%** — tolerance ≤ 5% | L2 | `npm run benchmark` |
+| Health-score calibration | ρ = −0.31 over 500 trials; score spans [0.31, 0.87]; isotonic Brier 0.230 → 0.219 | L2.5 diagnostic | `npm run benchmark` |
+| Malicious memory writes committed | 6/6 → 1/6 (83% blocked) | L2 / 16 candidates | `npm run benchmark` |
+| Wasted-token reduction (noisy retrieval) | −62% | L2 | `npm run benchmark` |
+| Wasted-token reduction (heavy retrieval) | −95% | L2 | `npm run benchmark` |
+| Tool-failure loop detection speedup | 10× faster | L2 / 3 scripted tools | `npm run benchmark` |
+| Retrieval-QA task success rate | 35% → 95%, bootstrap 95% CI × 5 seeds × 20 questions | **L2.5** | `npm run benchmark` |
+| Retrieval-QA adversarial inclusion | 100% → 11%, same CI methodology | **L2.5** | `npm run benchmark` |
+| Retrieval-QA relevant-doc recall | 100% (no Aahar false positives) | **L2.5** | `npm run benchmark` |
+
+These prove the **mechanisms** work as designed. They are **not** evidence of:
+
+- Production security against real adversaries
+  (detector-stack bypasses are listed in [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md))
+- Real-LLM token / latency / cost numbers
+  (char/4 estimator, not a real tokenizer)
+- Generalisation across organisations or threat models
+  (L3 / L4 work is on the [trust roadmap](./docs/BACKLOG.md#trust-roadmap))
+
+Full matrix: [`docs/EVIDENCE_MATRIX.md`](./docs/EVIDENCE_MATRIX.md).
+Known failure modes: [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md).
+Methodology: [`docs/EVIDENCE.md`](./docs/EVIDENCE.md).
 
 ---
 
 <a id="evidence"></a>
+
 ## Reproducible Evidence
 
-Eleven A/B benchmark suites compare a deliberately vulnerable agent **without Ojas** vs the **same agent + Ojas**, including two L2.5 diagnostic suites plus ablation and flaky-tool realism suites. Latest run, end-to-end in under a few seconds:
+Eighteen A/B benchmark suites compare a deliberately vulnerable agent
+**without Ojas** vs the **same agent + Ojas**, including two L2.5
+diagnostic suites plus ablation and flaky-tool realism suites.
 
 | # | Suite | Modules | Headline result |
 |---|---|---|---|
-| 1 | Prompt-injection resistance | raksha · aahar | Compliance rate **58% → 0%** (−100%); 33/33 attacks quarantined; 30/30 benign controls preserved |
-| 2 | Context pollution survival | aahar | **−62% tokens**; signal-to-noise **0.53 → 1.0** (1.9×); agent confidence +41% |
-| 3 | Tool-failure loop detection | pulse · nidra · chikitsa | Intervention at **2 failures vs 20**; repair plans 3/3 with fallback action |
-| 4 | Memory-write safety | raksha · nidra | Malicious writes committed **6/6 → 1/6**; 5/5 low-confidence downgraded to session notes |
-| 5 | Cognitive drift detection | nidra · pulse | Drift detected in **5/5** simulated long-horizon sessions; average 19.6 traces to detection |
-| 6 | Vyayam resilience under stress | vyayam · raksha · aahar | No regression: stress scenarios passed **7/8 → 7/8** with Ojas inserted |
-| 7 | Cost pressure on bloated contexts | aahar · agni | **−95% tokens** and **−75% latency** on heavy-retrieval tasks |
-| 8 | Retrieval-QA realistic synthetic benchmark | aahar · raksha | Task success **35% → 95%**; adversarial inclusion **100% → 11%**; relevant-doc recall preserved |
-| 9 | Health-score calibration | all modules | Spearman ρ = **−0.313** vs failure; monotonicity holds; calibrated score range now spans **[0.306, 0.869]** |
-| 10 | Ablation matrix | all modules | Per-module contribution measured by disabling raksha / aahar individually |
-| 11 | Flaky-tool resilience | vyayam · pulse | Detection/reporting under non-deterministic faults (intermittent 500s, variable latency, resets) |
-
-> **Overall: 11/11 suites pass.** Targeted failure suites improved, and diagnostic/no-regression suites met their acceptance criteria.
+| 1 | Prompt-injection resistance | raksha · aahar | Compliance rate **53% → 4%** (−92.6%); 48/51 quarantined; 30/30 benign preserved |
+| 2 | Context pollution survival | aahar | **−62% tokens**; signal-to-noise **0.53 → 1.0** (1.9×); confidence +41% |
+| 3 | Tool-failure loop detection | pulse · nidra · chikitsa | Intervention at **2 failures vs 20**; repair plans 3/3 |
+| 4 | Memory-write safety | raksha · nidra | Malicious writes **6/6 → 1/6**; 5/5 low-confidence downgraded |
+| 5 | Cognitive drift detection | nidra · pulse | Drift detected in **5/5** sessions; avg 19.6 traces |
+| 6 | Vyayam resilience under stress | vyayam · raksha · aahar | Stress scenarios **7/8 → 7/8** (no regression) |
+| 7 | Cost pressure on bloated contexts | aahar · agni | **−95% tokens** and **−75% latency** on heavy retrieval |
+| 8 | Retrieval-QA realistic synthetic | aahar · raksha | Task success **35% → 95%**; adversarial **100% → 11%** |
+| 9 | Health-score calibration | all modules | Spearman ρ = **−0.313**; monotonicity holds; score range [0.306, 0.869] |
+| 10 | Ablation matrix | all modules | Per-module contribution measured |
+| 11 | Flaky-tool resilience | vyayam · pulse | Detection under non-deterministic faults |
+
+> Overall: 11/11 suites pass. Targeted failure suites improved and diagnostic/no-regression suites met their acceptance criteria.
 
 ```bash
-npm install
-npm run build
 npm run benchmark             # console table
 npm run benchmark:write       # regenerates docs/EVIDENCE.md + benchmarks/results/latest.json
 ```
 
-The vulnerable agents are synthetic with explicitly-programmed failure modes; the benchmarks prove Ojas's detection and recovery mechanisms work as designed against canonical failure patterns. Production performance depends on the real agent's vulnerabilities and on Ojas policy tuning. Full methodology, scenarios, and limitations: [`docs/EVIDENCE.md`](./docs/EVIDENCE.md). Source: `benchmarks/`.
+Seeded with `OJAS_BENCH_SEED` for deterministic reproduction.
+Opt-in real-LLM generation via `OJAS_BENCH_LLM=1` and `OJAS_BENCH_JUDGE=1`.
+Source: `benchmarks/`.
+
+---
+
+## Documentation
+
+| If you want to… | Read |
+|---|---|
+| See it work in 30 seconds | [Quick demo](#demo) |
+| Run it in five minutes | [Quick Start](#quickstart) → [Basic Usage](#usage) |
+| Understand the model and design | [Why Ojas Exists](#why) → [What Ojas Does](#what) → [Architecture](#arch) |
+| Wire it into Claude Code / Cursor / Windsurf | [MCP Server](docs/MCP.md) → [MCP Config](docs/MCP.md#mcp-config) |
+| Drive an agent from another tool | [MCP Tools (18)](docs/MCP.md#tools-setup) → [Response Envelope](docs/MCP.md#envelope) |
+| Embed it in your own runtime | [Agent Adapter Interface](docs/CONFIGURATION.md#adapter) → [Configuration](docs/CONFIGURATION.md#config) |
+| Understand a single module | [Aahar](docs/MODULES.md#aahar) · [Nidra](docs/MODULES.md#nidra) · [Vyayam](docs/MODULES.md#vyayam) · [Raksha](docs/MODULES.md#raksha) · [Agni](docs/MODULES.md#agni) · [Pulse](docs/MODULES.md#pulse) · [Chikitsa](docs/MODULES.md#chikitsa) |
+| Reproduce the published numbers | [Evidence](#evidence) → [`docs/EVIDENCE.md`](./docs/EVIDENCE.md) |
+| Integrate with LangChain / OpenAI / Vercel AI | [`examples/`](examples/) |
+| Ship to a shared deployment | [`docs/TRUST.md`](./docs/TRUST.md) → [`docs/SECURITY.md`](./docs/SECURITY.md) |
 
 ---
 
 <a id="operations"></a>
+
 ## Operations
 
 | Resource | What's inside |
 |---|---|
-| [`docs/MODULES.md`](./docs/MODULES.md) | Deep-dive on each of the seven modules, health-event payloads, unified health report |
-| [`docs/MCP.md`](./docs/MCP.md) | MCP server, IDE configuration, all 18 tools, response envelope, usage loop |
-| [`docs/TRUST.md`](./docs/TRUST.md) | Trust boundary, demo limitations, production caveats, locked-down local config |
-| [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | SDK configuration, agent adapter contract, retention caps, project structure |
-| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Four-phase health cycle diagram, design principles, measurement philosophy |
-| [`docs/SECURITY.md`](./docs/SECURITY.md) | Trust model, Raksha defense-in-depth, persistence encryption, MCP audit logging, network deployment architecture |
-| [`docs/EVIDENCE_MATRIX.md`](./docs/EVIDENCE_MATRIX.md) | Evidence levels L0–L4, claim-by-claim limitations, L3 pipeline status |
-| [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md) | Known limitations, remaining bypass categories, operational caveats |
-| [`docs/BACKLOG.md`](./docs/BACKLOG.md) | Deferred work named honestly — L3 CI runs, production calibration, distributed persistence |
-| [`docs/EVIDENCE.md`](./docs/EVIDENCE.md) | Latest A/B benchmark results, auto-regenerated by `npm run benchmark:write` |
-| Quality gates | `npm run check` runs `lint` + `build` + aux typecheck + `test` (595 tests across 33 suites, ESLint clean) |
+| [`docs/MODULES.md`](./docs/MODULES.md) | Deep-dive on each of the seven modules |
+| [`docs/MCP.md`](./docs/MCP.md) | MCP server, IDE config, all 18 tools |
+| [`docs/TRUST.md`](./docs/TRUST.md) | Trust boundary, demo limitations, production caveats |
+| [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | SDK config, agent adapter contract, retention caps |
+| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Four-phase health cycle, design principles |
+| [`docs/SECURITY.md`](./docs/SECURITY.md) | Trust model, Raksha defense-in-depth, persistence encryption |
+| [`docs/EVIDENCE_MATRIX.md`](./docs/EVIDENCE_MATRIX.md) | Evidence levels L0–L4, claim-by-claim limitations |
+| [`docs/KNOWN_FAILURES.md`](./docs/KNOWN_FAILURES.md) | Known limitations, remaining bypass categories |
+| [`docs/BACKLOG.md`](./docs/BACKLOG.md) | Deferred work named honestly |
+| [`docs/EVIDENCE.md`](./docs/EVIDENCE.md) | Latest A/B benchmark results (auto-regenerated) |
 | License | [MIT](./LICENSE) |
 
 ---
 
-*ओजस (Ojas) — the vital essence that sustains life, immunity, resilience, and intelligence.*
+*ओजस (Ojas) — the vital essence that sustains life, immunity,
+resilience, and intelligence.*

package/dist/cli/index.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Ojas CLI — `npx ojas <command>`
+ *
+ * A thin, dependency-free command surface over the scorecard/badge
+ * library so an agent author can produce a shareable health artifact
+ * without writing any code:
+ *
+ *   npx ojas scorecard --db ./ojas.sqlite --agent my-agent
+ *   npx ojas badge     --db ./ojas.sqlite --agent my-agent --out badge.svg
+ *   npx ojas scorecard --report ./report.json --format markdown
+ *
+ * Sources (in precedence order):
+ *   --report <file>  A JSON `AgentHealthReport` (e.g. dumped from your app).
+ *   --db <file>      A SQLite store written by the Ojas MCP server; the CLI
+ *                    reads the agent's last persisted health report.
+ *
+ * The CLI does NOT compute a fresh health check — it has no agent to probe.
+ * It renders whatever the most recent report was, which keeps it honest:
+ * the badge reflects real measured state, never a synthetic placeholder.
+ */
+export declare function main(argv?: string[]): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG;AAkLH,wBAAgB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,IAAI,CAqBjE"}