opmsec 0.1.3 → 0.1.5

package/docs/cli/push.mdx

@@ -1,37 +1,11 @@
 ---
 title: 'opm push'
-description: 'Sign, scan, publish, and register a package on-chain.'
+description: 'Sign, scan, publish, register on-chain, write ENS records.'
 ---
 
 # opm push
 
-Sign, scan, publish, and register a package on-chain. The full verification pipeline runs before publishing to npm and registering on the OPMRegistry.
-
-## What It Does
-
-<Steps>
-  <Step title="Pack tarball">
-    Creates an npm tarball via <code>npm pack</code> and computes SHA-256 checksum over the packed file.
-  </Step>
-  <Step title="Sign checksum">
-    Signs the checksum with ECDSA (secp256k1) using your <code>OPM_SIGNING_KEY</code>.
-  </Step>
-  <Step title="Resolve ENS">
-    Resolves your wallet address to an ENS name (Base Sepolia, then Ethereum Mainnet fallback).
-  </Step>
-  <Step title="Security scan">
-    Runs 3 AI agents in parallel (Claude, Gemini, DeepSeek) to analyze the package. Each agent submits a risk score (0–100) and reasoning on-chain.
-  </Step>
-  <Step title="Risk check">
-    If aggregate score ≥ 80 or risk level is CRITICAL, publishing is blocked.
-  </Step>
-  <Step title="Publish to npm">
-    Publishes the tarball to the npm registry (uses <code>--token</code> or <code>NPM_TOKEN</code> for automation).
-  </Step>
-  <Step title="Register on-chain">
-    Calls <code>OPMRegistry.registerPackage()</code> with package name, version, checksum, signature, and ENS name.
-  </Step>
-</Steps>
+The full publish pipeline: sign your package, scan with 3 AI agents, publish to npm, register on-chain, upload audit report, and write ENS text records.
 
 ## Usage
 
@@ -51,49 +25,58 @@ opm push --otp <code>
 
 </CodeGroup>
 
+## What Happens
+
+<Steps>
+  <Step title="Pack & sign">
+    Creates tarball via `npm pack`, computes SHA-256 checksum, signs with ECDSA using `OPM_SIGNING_KEY`.
+  </Step>
+  <Step title="Resolve ENS">
+    Resolves your wallet to an ENS name (Sepolia → Mainnet fallback).
+  </Step>
+  <Step title="AI scan">
+    3 agents (Claude, Gemini, DeepSeek) analyze in parallel. Each submits a risk score on-chain.
+  </Step>
+  <Step title="Risk gate">
+    Aggregate score ≥ 80 or CRITICAL → **publish blocked**.
+  </Step>
+  <Step title="Publish to npm">
+    Publishes tarball to the npm registry.
+  </Step>
+  <Step title="Register on-chain">
+    Calls `OPMRegistry.registerPackage()` with checksum, signature, ENS name.
+  </Step>
+  <Step title="Upload report">
+    Formatted markdown report uploaded to Fileverse (IPFS-backed, encrypted).
+  </Step>
+  <Step title="Write ENS records">
+    Sets `opm.version`, `opm.checksum`, `opm.fileverse`, `opm.risk_score`, and more on your ENS name. Creates package subname (e.g. `express.djpai.eth`) if you own the parent. Sets contenthash to Fileverse IPFS CID.
+  </Step>
+</Steps>
+
 ## Required Environment Variables
 
 | Variable | Purpose |
 |----------|---------|
-| `OPM_SIGNING_KEY` | Ethereum private key for package signing (ECDSA) |
-| `OPENROUTER_API_KEY` or `OPENAI_API_KEY` | At least one required for AI agent scanning |
-| `AGENT_PRIVATE_KEY` | Agent wallet for submitting scores on-chain (must hold Base Sepolia ETH for gas) |
+| `OPM_SIGNING_KEY` | Ethereum private key for ECDSA signing |
+| `OPENROUTER_API_KEY` or `OPENAI_API_KEY` | AI agent scanning |
+| `AGENT_PRIVATE_KEY` | Agent wallet for on-chain score submission (needs Base Sepolia ETH) |
 
-## Optional Environment Variables
+## Optional
 
 | Variable | Purpose |
 |----------|---------|
-| `NPM_TOKEN` | npm automation token (alternative to <code>--token</code> flag) |
-| `FILEVERSE_API_KEY` | Upload audit report to IPFS via Fileverse |
-
-## Risk Blocking
+| `NPM_TOKEN` | npm automation token (alternative to `--token` flag) |
+| `FILEVERSE_API_KEY` | Audit report uploads |
 
 <Warning>
-Packages with **risk score ≥ 80** or **CRITICAL** level are blocked from publishing. The scan step fails, npm publish is skipped, and on-chain registration does not occur.
+Packages with **risk score ≥ 80** are blocked. The scan fails, npm publish is skipped, and no on-chain registration occurs.
 </Warning>
 
-When blocked, the CLI shows which agents scored the package and the aggregate risk. Fix the issues and run <code>opm push</code> again.
-
-## What Gets Stored On-Chain
-
-After a successful push, the following data is recorded on the OPMRegistry:
-
-| Data | Description |
-|------|-------------|
-| Package name | From <code>package.json</code> |
-| Version | Semantic version |
-| Checksum | SHA-256 hash of the tarball |
-| Signature | ECDSA signature of the checksum |
-| ENS name | Author identity (e.g. <code>vitalik.eth</code>) |
-| Agent scores | Per-agent risk scores and reasoning |
-| Report URI | Fileverse/IPFS link to the full audit report |
-
 ## Output
 
-- **Etherscan links** for every transaction: score submissions (one per agent) and package registration
-- **Report URI** link when uploaded to Fileverse
-- **npm package URL** on successful publish
+Every transaction shows a clickable BaseScan link: score submissions, package registration, ENS record writes. Plus the Fileverse report URI and npm package URL.
 
 <Note>
-If 2FA is enabled on your npm account, use <code>opm push --otp &lt;code&gt;</code> or an npm automation token with "bypass 2FA" enabled.
+See [ENS Text Records](/concepts/ens-records) for the full list of records written during push.
 </Note>

package/docs/cli/register-agent.mdx

@@ -1,11 +1,11 @@
 ---
 title: 'opm register-agent'
-description: 'Register a new security agent with ZK-verified benchmarks.'
+description: 'Register a new AI security agent with ZK-verified benchmarks.'
 ---
 
 # opm register-agent
 
-Register a new security agent with ZK-verified benchmarks. Agents must pass 10 benchmark cases with 100% accuracy and produce a valid ZK proof before they can submit scores on-chain.
+Register your own security agent. Must pass 10 benchmark cases with 100% accuracy and produce a valid ZK proof.
 
 ## Usage
 
@@ -15,66 +15,34 @@ opm register-agent --name <name> --model <model> [--system-prompt <prompt>]
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| <code>--name</code> | Yes | Agent identifier (e.g. <code>my-security-agent</code>) |
-| <code>--model</code> | Yes | LLM model (e.g. <code>anthropic/claude-sonnet-4-20250514</code>) |
-| <code>--system-prompt</code> | No | Custom system prompt (defaults to OPM security auditor prompt) |
+| `--name` | Yes | Agent identifier |
+| `--model` | Yes | LLM model (e.g. `anthropic/claude-sonnet-4-20250514`) |
+| `--system-prompt` | No | Custom system prompt (defaults to OPM security auditor) |
+
+## Process
+
+1. **Validate** — Checks agent name, model, env vars
+2. **Benchmark** — Sends 10 labeled cases in a single LLM call (3 clean, 7 malicious)
+3. **ZK proof** — Generates proof of 100% accuracy without revealing test data
+4. **Register** — Calls `OPMRegistry.registerAgent()` with name, model, system prompt hash, proof hash
 
 ## Required Environment Variables
 
 | Variable | Purpose |
 |----------|---------|
-| <code>AGENT_PRIVATE_KEY</code> | Wallet that becomes the agent identity; must hold Base Sepolia ETH for gas |
-| <code>OPENROUTER_API_KEY</code> or <code>OPENAI_API_KEY</code> | Required to run benchmark LLM calls |
-
-## Process
+| `AGENT_PRIVATE_KEY` | Wallet that becomes the agent identity (needs Base Sepolia ETH) |
+| `OPENROUTER_API_KEY` or `OPENAI_API_KEY` | LLM access for benchmark calls |
 
-<Steps>
-  <Step title="Validate configuration">
-    Checks agent name, model, and required env vars.
-  </Step>
-  <Step title="Run benchmark suite">
-    Executes 10 labeled test cases across categories: clean, typosquat, malicious, cve, obfuscated, exfiltration, dependency_confusion.
-  </Step>
-  <Step title="Generate ZK proof">
-    Produces a zero-knowledge proof that the agent achieved 100% accuracy without revealing test data or expected outputs.
-  </Step>
-  <Step title="Register on-chain">
-    Calls <code>OPMRegistry.registerAgent()</code> with name, model, system prompt hash, and proof hash.
-  </Step>
-</Steps>
+## On Success
 
-## Benchmark Categories
+- BaseScan transaction link shown
+- Agent authorized to submit scores
+- Participates in all future package scans
 
-| Category | Count | Description |
-|----------|-------|-------------|
-| clean | 3 | Legitimate packages (string utils, math, validator) |
-| typosquat | 1 | Typosquat with credential exfiltration |
-| malicious | 2 | Postinstall shell, SSH key exfiltration |
-| cve | 1 | Known prototype pollution CVE |
-| obfuscated | 1 | Obfuscated reverse shell |
-| exfiltration | 1 | Env var exfiltration on import |
-| dependency_confusion | 1 | Internal scope shadowing + exfiltration |
+## On Failure
 
-## Requirements
+Shows which cases were misclassified, expected vs actual verdict, and rejection reason.
 
 <Warning>
-**100% accuracy** is required. The agent must pass all 10 benchmark cases. Each case is evaluated by score range and risk level ordinal.
+**100% accuracy required.** No partial passes. The ZK proof hides test data and individual results — only the commitment hash and proof hash go on-chain.
 </Warning>
-
-<Note>
-The ZK proof hides test data and individual results. Only the commitment hash and proof hash are stored on-chain.
-</Note>
-
-## Success
-
-On success:
-- Etherscan transaction link is shown
-- Agent is authorized to submit scores
-- Agent participates in the next package scan alongside existing agents
-
-## Failure
-
-On failure, the CLI shows:
-- Which benchmark cases failed and why
-- Expected vs actual risk level and score
-- Rejection reason (e.g. "Agent achieved 90% accuracy (100% required)")

package/docs/cli/view.mdx

@@ -1,52 +1,35 @@
 ---
 title: 'opm view / opm whois'
-description: 'Author profile and published packages.'
+description: 'Author profile, reputation, and published packages.'
 ---
 
 # opm view / opm whois
 
-Show author profile and published packages. Resolves ENS identity and displays on-chain reputation.
+Look up an author's ENS profile, OPM reputation, and published packages.
 
 ## Usage
 
 <CodeGroup>
 
-```bash View by ENS name
-opm view vitalik.eth
+```bash By ENS name
+opm view djpai.eth
 ```
 
 ```bash Whois (auto-appends .eth)
-opm whois vitalik
+opm whois djpai
 ```
 
 </CodeGroup>
 
 <Note>
-<code>opm view &lt;name.eth&gt;</code> shows author profile. <code>opm view &lt;pkg&gt;</code> (without <code>.eth</code>) delegates to <code>opm info</code>.
+`opm view <name.eth>` shows author profile. `opm view <pkg>` (without `.eth`) delegates to `opm info`.
 </Note>
 
-## Output
+## What It Shows
 
-### Identity
+- **Identity** — ENS name, wallet address, bio, URL, GitHub, Twitter, email, avatar
+- **Author stats** — Packages published, average reputation score
+- **OPM ENS records** — `opm.version`, `opm.fileverse`, `opm.risk_score`, `opm.packages`, contenthash
+- **Published packages** — Name, version, risk score, checksum, signature status, report link
 
-- **ENS name** — Resolved identity
-- **Address** — Wallet address
-- **Bio** — ENS description text record
-- **URL** — ENS url record
-- **GitHub** — <code>com.github</code> text record
-- **Twitter** — <code>com.twitter</code> text record
-- **Email** — ENS email record
-- **Avatar** — Rendered from ENS avatar record
-
-### Author Stats
-
-- **Packages published** — Count from OPMRegistry
-- **Avg reputation** — Risk badge (lower = better)
-
-### Published Packages
-
-For each package: name, version, risk score, checksum, signature status, and report URI link.
-
-<Note>
-No environment variables are required. ENS resolution uses public resolvers.
-</Note>
+No environment variables required. Uses public ENS resolvers.

package/docs/concepts/ens-records.mdx

@@ -0,0 +1,44 @@
+---
+title: 'ENS Text Records'
+description: 'Package metadata stored on ENS for decentralized discovery.'
+---
+
+# ENS Text Records
+
+When you publish via `opm push`, package metadata is written to your ENS name as text records — creating a decentralized discovery layer independent of the smart contract.
+
+## Record Keys
+
+### Author-Level (on `djpai.eth`)
+
+| Key | Example |
+|-----|---------|
+| `opm.version` | `1.2.3` |
+| `opm.checksum` | `0x8a3f...` |
+| `opm.fileverse` | Fileverse report URI |
+| `opm.risk_score` | `12` |
+| `opm.signature` | ECDSA signature |
+| `opm.contract` | Registry contract address |
+| `opm.packages` | `express,lodash` |
+
+### Per-Package (namespaced)
+
+`opm.pkg.<name>.version`, `opm.pkg.<name>.checksum`, `opm.pkg.<name>.fileverse`, etc.
+
+## Subnames
+
+OPM creates ENS subnames like `express.djpai.eth` during `opm push` if you own the parent name. Each subname gets its own text records for per-package resolution.
+
+## Contenthash
+
+The ENS `contenthash` is set to the Fileverse IPFS CID — read directly from the Fileverse Portal smart contract. This makes audit reports discoverable via standard ENS contenthash resolution.
+
+## When Records Are Used
+
+- **`opm push`** — Writes all records after on-chain registration
+- **`opm info`** / **`opm view`** — Reads and displays records alongside on-chain data
+- **`opm install express@djpai.eth`** — Resolves the ENS author, reads metadata
+
+<Note>
+Writing records requires the signer (`OPM_SIGNING_KEY`) to own/manage the ENS name. Reading is permissionless.
+</Note>

package/docs/concepts/multi-agent-consensus.mdx

@@ -1,58 +1,40 @@
 ---
 title: 'Multi-Agent Consensus'
-description: 'Three LLMs run in parallel, submit scores on-chain, and aggregate via intelligence-weighted averaging.'
+description: 'Three LLMs scan in parallel, submit scores on-chain, aggregate via intelligence-weighted averaging.'
 ---
 
 # Multi-Agent Consensus
 
-OPM uses **three heterogeneous AI agents** that run in parallel to analyze packages. Each agent independently evaluates source code, version history, and CVE data, then submits its risk score and reasoning on-chain. Scores are aggregated using **intelligence-weighted averaging** to produce a final risk assessment.
+Three different AI models analyze every package in parallel. Each submits an independent risk score on-chain. Scores are aggregated using intelligence-weighted averaging.
 
-## Agent Configuration
+## Agent Lineup
 
-| Agent | OpenRouter (preferred) | OpenAI (fallback) |
-|-------|------------------------|--------------------|
+| Agent | OpenRouter | OpenAI fallback |
+|-------|-----------|----------------|
 | agent-1 | Claude Sonnet 4 | GPT-4.1 |
 | agent-2 | Gemini 2.5 Flash | GPT-4.1 Mini |
 | agent-3 | DeepSeek Chat | GPT-4.1 Nano |
 
-Model diversity reduces single-model blind spots and improves consensus reliability. Override models via `AGENT1_MODEL`, `AGENT2_MODEL`, and `AGENT3_MODEL`.
+Model diversity reduces single-model blind spots. Override via `AGENT1_MODEL`, `AGENT2_MODEL`, `AGENT3_MODEL`.
 
-## Analysis Pipeline
+## What Each Agent Does
 
-Each agent receives:
+1. Receives package source, `package.json`, version history, and any known CVEs
+2. Produces structured JSON: risk score (0-100), risk level, reasoning, vulnerability list, supply chain indicators
+3. Submits score on-chain via `OPMRegistry.submitScore()`
 
-- Packed tarball contents (scannable extensions: `.js`, `.ts`, `.mjs`, `.cjs`, `.json`)
-- `package.json` and dependency metadata
-- Version history and changelog context
-- CVE/OSV advisory data when available
+Each agent scores a version only once.
 
-Each agent produces structured JSON:
+## Intelligence-Weighted Scoring
 
-- **Risk score** (0–100) with categorical classification (LOW, MEDIUM, HIGH, CRITICAL)
-- **Vulnerability enumeration** with severity, category, file path, and evidence
-- **Supply chain indicators**: install scripts, native bindings, obfuscated code, network calls, filesystem access, process spawning, `eval` usage, environment variable access
-- **Version history analysis**: changelog risk, maintainer changes, dependency graph mutations
-- **Recommendation**: SAFE, CAUTION, WARN, or BLOCK
-
-## On-Chain Submission
-
-Agent wallets call `OPMRegistry.submitScore(name, version, riskScore, reasoning)` for each package version. Each agent may submit only once per version. Scores are stored in the contract's `versionData` mapping.
-
-## Intelligence-Weighted Aggregation
-
-Scores are aggregated using model weights from the **Artificial Analysis API**:
-
-- **Intelligence Index**: General reasoning and knowledge
-- **Coding Index**: Code generation and analysis capability
-
-Weights are applied to each agent's score before computing the mean. This favors higher-capability models when consensus is ambiguous.
+When `ARTIFICIAL_ANALYSIS_API_KEY` is set, scores are weighted by each model's Intelligence Index and Coding Index from the Artificial Analysis API. Higher-capability models carry more weight in the final score.
 
 <Note>
-If `ARTIFICIAL_ANALYSIS_API_KEY` is unset or the API is unavailable, OPM falls back to **equal weighting** (simple arithmetic mean).
+Without the API key, agents are weighted equally (simple mean).
 </Note>
 
-## Fallback Behavior
+## Provider Routing
 
-- **Provider**: When `OPENROUTER_API_KEY` is set, OPM routes through OpenRouter. Otherwise it uses `OPENAI_API_KEY` with the GPT-4.1 family.
-- **Force provider**: Set `LLM_PROVIDER=openrouter` or `LLM_PROVIDER=openai` to override auto-detection.
-- **OpenAI models**: `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano` for agent-1, agent-2, agent-3 respectively.
+- `OPENROUTER_API_KEY` set → routes through OpenRouter (multi-model)
+- Only `OPENAI_API_KEY` → falls back to GPT-4.1 family
+- Force a provider: `LLM_PROVIDER=openrouter` or `LLM_PROVIDER=openai`

package/docs/concepts/on-chain-registry.mdx

@@ -1,72 +1,45 @@
 ---
 title: 'On-chain Registry'
-description: 'OPMRegistry.sol stores packages, versions, author profiles, agent scores, and report URIs on Base Sepolia.'
+description: 'OPMRegistry.sol on Base Sepolia — packages, scores, authors, agents.'
 ---
 
 # On-chain Registry
 
-The **OPMRegistry** smart contract is the canonical on-chain store for package metadata, author profiles, agent scores, and report URIs. It implements a domain-specific form of the [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004) three-registry architecture.
+The **OPMRegistry** smart contract is the source of truth for package metadata, agent scores, author reputation, and registered agents.
 
 ## Deployment
 
 | Property | Value |
 |----------|-------|
-| **Chain** | Base Sepolia |
-| **Chain ID** | 84532 |
-| **Contract Address** | `0x16684391fc9bf48246B08Afe16d1a57BFa181d48` |
-| **Explorer** | [BaseScan](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48) |
+| **Chain** | Base Sepolia (84532) |
+| **Address** | [`0x16684391fc9bf48246B08Afe16d1a57BFa181d48`](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48) |
+| **Solidity** | 0.8.20 |
 
-Override via `CONTRACT_ADDRESS` in your environment.
+## What It Stores
 
-## Data Structures
+| Data | Description |
+|------|-------------|
+| **Packages** | Name → version → checksum, signature, author, ENS name, report URI |
+| **Agent scores** | Per-version risk scores (0-100) with reasoning from each agent |
+| **Authors** | Wallet → ENS name, cumulative reputation, package count |
+| **Agents** | Authorized agents (owner-set or ZK-verified) with name, model, proof hash |
 
-| Struct | Fields |
-|--------|--------|
-| `AuthorProfile` | `addr`, `ensName`, `reputationTotal`, `reputationCount`, `packagesPublished` |
-| `AgentScore` | `agent`, `riskScore`, `reasoning` |
-| `VersionData` | `author`, `checksum`, `signature`, `reportURI`, `scores[]`, `exists` |
-| `Package` | `name`, `versions[]`, `exists` |
-| `RegisteredAgent` | `agentAddress`, `name`, `model`, `systemPromptHash`, `proofHash`, `registeredAt`, `active` |
+## Key Operations
 
-## Key Functions
+- **`registerPackage`** — Store a new version with checksum, signature, and ENS binding
+- **`submitScore`** — Agent submits risk score + reasoning (authorized agents only)
+- **`setReportURI`** — Attach Fileverse/IPFS report link to a version
+- **`registerAgent`** — Permissionless agent registration with ZK proof hash
+- **`getSafestVersion`** — Get the lowest-risk version in a lookback window
+- **`getPackageInfo`** — Full metadata + aggregate score for a version
 
-| Function | Access | Description |
-|----------|--------|-------------|
-| `registerPackage(name, version, checksum, sig, ensName)` | Public | Register a new package version with checksum, signature, and ENS binding |
-| `submitScore(name, version, riskScore, reasoning)` | Authorized agents | Submit a risk score (0–100) and reasoning for a package version |
-| `setReportURI(name, version, uri)` | Authorized agents | Attach a Fileverse report URI to a package version |
-| `getPackageInfo(name, version)` | View | Retrieve full metadata and aggregate score for a package version |
-| `getScores(name, version)` | View | Return all individual agent scores for a version |
-| `getAggregateScore(name, version)` | View | Compute mean risk score across all agent submissions |
-| `getSafestVersion(name, lookback)` | View | Return the lowest-risk version within a configurable lookback window |
-| `getVersions(name)` | View | List all registered versions of a package |
-| `getAuthorByAddress(addr)` | View | Retrieve author profile by Ethereum address |
-| `getAuthorByENS(ensName)` | View | Resolve author profile by ENS name |
-| `getAuthorReputation(addr)` | View | Compute author's mean risk score across all packages |
-| `registerAgent(name, model, systemPromptHash, proofHash)` | Public | Permissionless agent registration (requires valid ZK proof) |
-
-## Events
-
-| Event | Parameters |
-|-------|------------|
-| `PackageRegistered` | `name`, `version`, `author`, `ensName` |
-| `ScoreSubmitted` | `name`, `version`, `agent`, `riskScore`, `reasoning` |
-| `ReportURISet` | `name`, `version`, `uri` |
-| `AuthorRegistered` | `addr`, `ensName` |
-| `AgentAuthorized` | `agent`, `status` |
-| `AgentRegistered` | `agent`, `name`, `model`, `systemPromptHash`, `proofHash`, `timestamp` |
+See [Contract Functions](/contract/functions) for the complete API reference.
 
 ## Author Reputation
 
-Author reputation is computed as:
-
-```
-reputation = reputationTotal / reputationCount
-```
-
-Where `reputationTotal` accumulates each agent's score for every version of every package authored by that address. This provides a cumulative risk score average across all published packages.
+Computed as `reputationTotal / reputationCount` — the average of all agent scores received across all packages published by an author. Lower is better.
 
-## Risk Thresholds (Contract)
+## Risk Thresholds
 
 | Constant | Value |
 |----------|-------|

package/docs/concepts/security-model.mdx

@@ -1,76 +1,44 @@
 ---
 title: 'Security Model'
-description: 'OPM defense-in-depth: cryptographic attestation, multi-agent AI, CVE integration, supply chain checks, and ENS-based trust.'
+description: 'Five layers of defense: crypto, AI, CVEs, supply chain checks, and ENS trust.'
 ---
 
 # Security Model
 
-OPM employs a **defense-in-depth** architecture across five layers. No single layer is sufficient; together they mitigate supply chain injection, typosquatting, dependency confusion, maintainer takeover, and known vulnerability exploitation.
+OPM layers five independent defenses. No single layer is sufficient — together they catch supply chain injection, typosquatting, dependency confusion, maintainer takeover, and known CVEs.
 
-## 1. Cryptographic Layer
+## 1. Cryptographic Signing
 
-- **SHA-256 checksum**: Computed over the packed tarball; stored on-chain and verified at install time
-- **ECDSA signature**: secp256k1 signature over the checksum, derived from the author's Ethereum private key
-- **On-chain registration**: Checksum, signature, and author binding stored in `OPMRegistry` on Base Sepolia
+Every package gets a SHA-256 checksum and ECDSA signature (secp256k1) from the author's Ethereum wallet. Both are stored on-chain and verified at install time. Tampered tarballs are rejected.
 
-Installation is blocked if the tarball checksum does not match the on-chain value or if the signature verification fails.
+## 2. Multi-Agent AI Scanning
 
-## 2. AI Layer
+Three LLMs (Claude, Gemini, DeepSeek) analyze source code, dependency metadata, and version history in parallel. Each submits a risk score (0-100) on-chain. Scores are aggregated using intelligence-weighted averaging via the Artificial Analysis API.
 
-Three heterogeneous LLMs analyze packages in parallel:
+Agents flag: install scripts, native bindings, obfuscated code, network calls, filesystem access, process spawning, `eval` usage, and env var access.
 
-- Static analysis of source code, dependency metadata, and version history
-- Each agent submits a risk score (0–100) and reasoning on-chain
-- **Intelligence-weighted aggregation** via the Artificial Analysis API (Intelligence Index, Coding Index)
-- Fallback to equal weighting if the API is unavailable
+## 3. CVE Detection
 
-<CardGroup cols={2}>
-  <Card title="Agent 1" icon="robot">
-    Claude Sonnet 4 (OpenRouter) / GPT-4.1 (OpenAI fallback)
-  </Card>
-  <Card title="Agent 2" icon="robot">
-    Gemini 2.5 Flash (OpenRouter) / GPT-4.1 Mini (OpenAI fallback)
-  </Card>
-  <Card title="Agent 3" icon="robot">
-    DeepSeek Chat (OpenRouter) / GPT-4.1 Nano (OpenAI fallback)
-  </Card>
-</CardGroup>
+Real-time lookup against the OSV database (CVE + GHSA advisories) with CVSS v3 severity scoring. CRITICAL CVEs block installation. HIGH CVEs trigger warnings with suggested fix versions.
 
-## 3. CVE Layer
+## 4. Supply Chain Checks
 
-- **OSV (Open Source Vulnerabilities)**: Real-time CVE and GHSA advisory data
-- **GitHub Advisory Database**: Integrated via OSV API
-- **CVSS v3** base score computation for severity classification
-- **CRITICAL** severity: installation blocked
-- **HIGH** severity: warning with suggested fix version
+| Check | How |
+|-------|-----|
+| Typosquatting | Levenshtein distance against top npm packages + AI name similarity assessment |
+| Dependency confusion | Scoped vs unscoped name conflicts surfaced during `opm check` |
+| ChainPatrol blocklist | Fallback for packages not in the on-chain registry |
 
-## 4. Supply Chain Layer
+## 5. ENS Trust Layer
 
-| Check | Description |
-|-------|-------------|
-| **Typosquat detection** | Package names compared against npm search results and download-count differentials; AI agents assess name similarity |
-| **Dependency confusion** | Scoped vs unscoped name conflicts and internal package shadowing surfaced during `opm check` |
-| **ChainPatrol blocklist** | Fallback blocklist for packages absent from the on-chain registry (requires `CHAINPATROL_API_KEY`) |
-
-AI agents also flag: install scripts, native bindings, obfuscated code, network calls, filesystem access, process spawning, `eval` usage, and environment variable access.
-
-## 5. Trust Layer
-
-- **ENS identity resolution**: Author addresses resolved to ENS names (Sepolia, Mainnet fallback)
-- **On-chain author reputation**: Cumulative risk score average across all published packages
-- **Author profiles**: ENS text records (avatar, description, URL, GitHub, Twitter, email) for human verification
+Author addresses resolve to ENS names. Reputation is computed as the average risk score across all published packages. ENS text records (avatar, GitHub, Twitter) provide human-verifiable identity signals.
 
 ## Risk Thresholds
 
-| Range | Level | Effect |
-|-------|-------|--------|
+| Score | Level | What happens |
+|-------|-------|-------------|
 | 0–20 | LOW | Safe to install |
 | 21–40 | MEDIUM | Flagged for caution |
 | 41–70 | HIGH | Warnings triggered |
 | 71–100 | CRITICAL | High risk |
-
-| Threshold | Value | Behavior |
-|-----------|-------|----------|
-| Block threshold (CLI) | 80 | `opm push` blocks publication; `opm install` blocks installation |
-| `HIGH_RISK_THRESHOLD` (contract) | 70 | Packages above trigger warnings |
-| `MEDIUM_RISK_THRESHOLD` (contract) | 40 | Packages above flagged for caution |
+| **≥ 80** | — | **Blocks `opm push` and `opm install`** |