opmsec 0.1.0 → 0.1.3

package/.env.example

@@ -1,14 +1,24 @@
-OPM_PRIVATE_KEY=
-AGENT_PRIVATE_KEY=
-# Set ONE of these (OPENAI_API_KEY auto-uses gpt-4.1 variants, OPENROUTER_API_KEY uses multi-model)
+# ── CLIENT ──
+# opm install/audit/info/view work out of the box with ZERO config.
+# All RPCs, contract address, and API defaults are hardcoded.
+
+# ── AUTHOR (required only for opm push) ──
+OPM_SIGNING_KEY=                    # Ethereum private key for package signing
+AGENT_PRIVATE_KEY=                  # Agent wallet key for on-chain score submission
+NPM_TOKEN=                         # npm automation token (bypasses 2FA)
+
+# AI scanning — set at least ONE:
 OPENAI_API_KEY=
-# OPENROUTER_API_KEY=
-CHAINPATROL_API_KEY=
-BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
-ETH_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
-ETH_MAINNET_RPC_URL=https://eth.llamarpc.com
-CONTRACT_ADDRESS=
-FILEVERSE_API_KEY=
-FILEVERSE_API_URL=http://localhost:8001
-# npm automation token (bypasses 2FA for opm push)
-# NPM_TOKEN=
+# OPENROUTER_API_KEY=              # enables diverse models (Claude, Gemini, DeepSeek)
+
+# Fileverse dDocs — report storage
+FILEVERSE_API_KEY=                  # from ddocs.new → Settings → Developer Mode
+
+# ── OPTIONAL (sensible defaults baked in) ──
+# CONTRACT_ADDRESS=0x16684391fc9bf48246B08Afe16d1a57BFa181d48
+# BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+# ETH_MAINNET_RPC_URL=https://eth.llamarpc.com
+# ETH_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+# FILEVERSE_API_URL=http://localhost:8001
+# CHAINPATROL_API_KEY=             # optional, for blocklist checks
+# ARTIFICIAL_ANALYSIS_API_KEY=     # optional, for model-weighted scoring

package/README.md

@@ -1,266 +1,349 @@
-# OPM — On-chain Package Manager
+# OPM: On-chain Package Manager
 
-A security-first CLI wrapper around npm that brings on-chain verification, multi-agent AI scanning, and decentralized audit trails to the JavaScript package ecosystem.
+[![npm](https://img.shields.io/npm/v/opmsec)](https://www.npmjs.com/package/opmsec)
+[![GitHub](https://img.shields.io/github/stars/dhananjaypai08/opm)](https://github.com/dhananjaypai08/opm)
+[![Contract](https://img.shields.io/badge/Base%20Sepolia-0x8A6a...1E85-blue)](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48)
 
-Authors sign packages with Ethereum keys. Three AI agents scan every publish in parallel and submit structured risk scores to a smart contract on Base Sepolia. Scan reports are stored as encrypted documents on Fileverse dDocs. Consumers verify signatures, check CVE databases, and consult on-chain scores before installing.
+OPM is a security-hardened CLI wrapper around npm that introduces cryptographic package signing, multi-agent AI threat analysis, on-chain audit registries, and decentralized report storage to the JavaScript dependency supply chain. The CLI is built on Bun and uses Ink (React for terminals) for its interface, while all underlying package operations (install, publish, pack) delegate to npm via subprocess invocation. Its on-chain registry architecture implements a domain-specific instantiation of the [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004) pattern, where autonomous AI agents submit structured reputation signals and validation evidence to chain-resident registries, enabling trust establishment across organizational boundaries without prior coordination.
 
-## Setup
+OPM supports **permissionless agent registration** — anyone can onboard their own security agent by proving 100% accuracy on a labeled benchmark suite via zero-knowledge proofs, with the proof hash stored immutably on-chain. Every on-chain transaction (agent score submissions, package registrations, agent registrations) surfaces as a clickable [BaseScan](https://sepolia.basescan.org) link directly in the terminal UI.
 
-### Prerequisites
+## System Overview
+
+OPM interposes a verification pipeline between the developer and the npm registry. Package authors sign tarballs with ECDSA keys derived from Ethereum wallets. Upon publish, three heterogeneous AI models conduct parallel static analysis of source code, dependency metadata, and version history. Each agent submits a structured risk assessment to the `OPMRegistry` smart contract deployed on Base Sepolia, following the same identity-reputation-validation triad defined by ERC-8004: agents hold on-chain identities (authorized wallets with ENS binding), submit structured reputation signals (`riskScore` + `reasoning` per package version, analogous to ERC-8004's `giveFeedback`), and attach off-chain validation evidence as Fileverse report URIs (analogous to ERC-8004's `feedbackURI`/`responseURI`). The formatted audit report is encrypted and persisted to Fileverse dDocs. Consumers invoking `opm install` query this on-chain registry, verify signatures against checksums, cross-reference the OSV vulnerability database, and enforce configurable risk thresholds before permitting installation.
+
+### Threat Model
+
+OPM addresses the following attack surfaces:
+
+- **Supply chain injection**: Malicious postinstall scripts, obfuscated payloads, environment variable exfiltration, and runtime code generation detected by AI agents.
+- **Typosquatting**: Package names are compared against npm registry search results and download-count differentials. AI agents independently assess name similarity to known packages.
+- **Dependency confusion**: Scoped versus unscoped name conflicts and internal package shadowing are surfaced during `opm check`.
+- **Silent maintainer takeover**: Version history analysis detects sudden dependency graph mutations, new maintainer additions, and anomalous size deltas between releases.
+- **Known vulnerability exploitation**: Real-time CVE and GHSA data from the Open Source Vulnerabilities (OSV) API is integrated into install-time blocking and upgrade recommendations, with CVSS v3 base score computation for severity classification.
+- **Malicious / spamming agents**: Permissionless agent registration requires passing a 10-case benchmark suite with 100% accuracy, verified via zero-knowledge proofs, preventing unqualified agents from polluting the on-chain risk registry.
+
+### Data Flow
+
+```
+opm push
+  |
+  +-- Compute SHA-256 checksum over packed tarball
+  +-- Sign checksum with author's Ethereum private key (ECDSA secp256k1)
+  +-- Resolve author ENS identity (Sepolia, Mainnet fallback)
+  +-- Dispatch 3+ AI agents in parallel (permissionless agents included)
+  |     +-- Each agent: static analysis, risk scoring (0-100), structured JSON output
+  |     +-- Agent wallets submit scores to OPMRegistry.submitScore()
+  |     +-- Aggregate risk computed; publish blocked if score >= 80
+  |     +-- BaseScan tx links shown for every score submission
+  +-- Upload formatted markdown report to Fileverse dDocs (encrypted, on-chain synced)
+  +-- Publish tarball to npm (automation token or OTP for 2FA)
+  +-- Register package metadata on OPMRegistry.registerPackage()
+  |     +-- Stores: checksum, signature, ENS name, report URI
+  |     +-- BaseScan tx link + contract link shown in terminal
+  +-- Set report URI on-chain via OPMRegistry.setReportURI()
+
+opm register-agent --name <name> --model <model>
+  |
+  +-- Validate agent configuration and environment
+  +-- Generate ZK commitment over expected benchmark outputs
+  +-- Run candidate agent against 10 labeled security test cases
+  |     +-- Categories: clean, typosquat, malicious, CVE, obfuscated, exfiltration, dependency confusion
+  |     +-- Each case evaluated against expected risk level and score range
+  +-- Generate zero-knowledge proof of accuracy
+  |     +-- Hash commitment scheme: hash(salt, expected) → commitment
+  |     +-- Proof: hash(commitment, result_hash, accuracy_flag, salt)
+  |     +-- Proves 100% accuracy without revealing test data or individual results
+  +-- Verify ZK proof integrity
+  +-- Register agent on OPMRegistry.registerAgent() if 100% accuracy
+  |     +-- Stores: name, model, systemPromptHash, proofHash on-chain
+  |     +-- Auto-authorizes agent for submitScore and setReportURI
+  +-- Show BaseScan tx link and contract link
+```
+
+## Prerequisites
 
 - [Bun](https://bun.sh) >= 1.2
 - Node.js >= 20
-- An Ethereum wallet with Base Sepolia ETH (for gas)
+- Ethereum wallet funded with Base Sepolia ETH (required for gas during `opm push`)
 
-### Install Dependencies
+## Installation
 
 ```bash
-git clone <repo> && cd opm
+git clone https://github.com/dhananjaypai08/opm.git && cd opm
 cp .env.example .env
-# Fill in your keys (see Environment Variables below)
 bun install
+bun link
 ```
 
-### Link CLI Globally
+Or install from npm:
 
 ```bash
-bun link
+npm i -g opmsec
 ```
 
-This registers `opm` as a global command.
+The `bun link` command registers `opm` as a globally available CLI binary.
 
-### Deploy Contract
+## Smart Contract Deployment
 
 ```bash
 cd packages/contracts
 npm install
 npx hardhat compile
 npx hardhat run scripts/deploy.ts --network baseSepolia
-# Copy the deployed address to .env as CONTRACT_ADDRESS
 ```
 
-### Fileverse Setup
+Record the deployed contract address and set it as `CONTRACT_ADDRESS` in `.env`, or rely on the default address hardcoded in `packages/core/src/constants.ts`.
 
-OPM stores formatted security reports on Fileverse dDocs (encrypted, on-chain synced).
+The contract is live on Base Sepolia: [`0x16684391fc9bf48246B08Afe16d1a57BFa181d48`](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48)
 
-1. Go to [ddocs.new](https://ddocs.new) → Settings → Developer Mode → Generate API key
-2. Add the key to `.env` as `FILEVERSE_API_KEY`
+## Fileverse dDocs Configuration
+
+OPM persists AI scan reports as encrypted, on-chain-synced documents via the Fileverse dDocs protocol.
+
+1. Navigate to [ddocs.new](https://ddocs.new), open Settings, enable Developer Mode, and generate an API key.
+2. Set `FILEVERSE_API_KEY` in `.env`.
 3. Start the local Fileverse API server:
 
 ```bash
-npx @fileverse/api --apiKey YOUR_API_KEY
+npx @fileverse/api --apiKey <YOUR_API_KEY>
 ```
 
-The server runs on `http://localhost:8001` by default.
+The server binds to `http://localhost:8001` by default. This is configurable via `FILEVERSE_API_URL`.
 
-## Architecture
+## Commands
+
+### Security Commands
+
+| Command | Description |
+|---------|-------------|
+| `opm push` | Sign, scan, publish to npm, and register on-chain |
+| `opm push --token <token>` | Publish using an npm automation token (bypasses 2FA) |
+| `opm push --otp <code>` | Publish with a one-time 2FA code |
+| `opm install <pkg>[@ver]` | Install with signature verification, CVE checks, and on-chain risk gating |
+| `opm install` | Verify all dependencies in package.json (bulk scan mode) |
+| `opm check` | Scan all dependencies for typosquats, CVEs, and AI-detected risks |
+| `opm fix` | Auto-correct typosquatted names and upgrade vulnerable versions |
+| `opm audit` | Audit all dependencies against on-chain and CVE data |
+| `opm info <pkg>` | Display on-chain security metadata for a specific package |
+| `opm view <name.eth>` | Display ENS author profile, published packages, and reputation |
+| `opm whois <name>` | ENS identity lookup (appends `.eth` if omitted) |
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `opm register-agent --name <n> --model <m>` | Register a new security agent with ZK-verified benchmarks |
+| `opm register-agent --system-prompt <p>` | Optional custom system prompt (defaults to OPM security auditor) |
+
+### npm Passthrough
+
+All standard npm commands are forwarded transparently:
 
 ```
-opm push
-  ├─ Pack tarball & compute SHA-256 checksum
-  ├─ Sign checksum with author's Ethereum key (ECDSA)
-  ├─ Resolve ENS identity (Sepolia + Mainnet)
-  ├─ 3 AI agents scan source code in parallel
-  │   ├─ Risk score, vulnerabilities, supply chain indicators
-  │   ├─ Submit scores to OPMRegistry contract
-  │   └─ Upload styled markdown report to Fileverse dDocs
-  ├─ BLOCK if aggregate risk >= 80 (CRITICAL)
-  ├─ Publish to npm (with --token for automation)
-  └─ Register package + signature + report URI on-chain
-
-opm install <pkg>
-  ├─ Resolve version (on-chain latest or specified)
-  ├─ Query CVE database (OSV API) — block CRITICAL, warn HIGH
-  ├─ Look up on-chain registry (risk score, agent consensus)
-  ├─ Verify ECDSA signature against checksum
-  ├─ ChainPatrol fallback for unknown packages
-  ├─ Fetch Fileverse report link
-  └─ Install via npm if safe
-
-opm view <name.eth>
-  ├─ Resolve ENS name → address (@ensdomains/ensjs + viem)
-  ├─ Fetch ENS text records (avatar, bio, GitHub, Twitter)
-  ├─ Render avatar as pixel art in terminal
-  ├─ Query on-chain author stats (packages, reputation)
-  └─ List all published packages with risk scores + report links
+opm init        opm run <script>    opm test
+opm start       opm build           opm uninstall <pkg>
+opm outdated    opm update          opm list
+opm link        opm pack
 ```
 
-## Commands
+Aliases: `i`, `add` map to `install`; `rm` maps to `uninstall`; `ls` maps to `list`.
 
-### Security Commands
+## Permissionless Agent Registration
 
-```bash
-# Sign, scan, publish, and register on-chain
-opm push
-opm push --token <npm-automation-token>
+OPM supports permissionless agent onboarding. Any developer can register their own security agent by providing a model and optionally a custom system prompt. Before registration, the agent must prove it can accurately classify security threats.
 
-# Install with full security pipeline
-opm install lodash
-opm install lodash@4.17.21
-opm install                    # verify all deps in package.json
+### How It Works
 
-# Audit all dependencies against on-chain + CVE data
-opm audit
+1. **Benchmark Suite**: 10 labeled test cases covering clean packages, typosquats, env exfiltration, obfuscated code, postinstall attacks, known CVEs, and dependency confusion.
+2. **Agent Evaluation**: The candidate agent runs against all 10 cases. Each response is evaluated against expected risk levels and score ranges.
+3. **ZK Proof Generation**: A zero-knowledge proof is generated using a hash-commitment scheme:
+   - Expected outputs are committed: `hash(salt, expected_verdicts) → commitment`
+   - Agent outputs are hashed: `hash(salt, actual_verdicts) → result_hash`
+   - Proof binds everything: `hash(commitment, result_hash, accuracy_flag, salt) → proof`
+   - Only a binary pass/fail is disclosed — test data and individual results remain hidden
+4. **On-chain Registration**: If accuracy is 100%, the agent's proof hash is stored on-chain via `OPMRegistry.registerAgent()`, and the agent is auto-authorized to submit scores.
 
-# Look up on-chain security info for a package
-opm info lodash
-opm info lodash@4.17.21
+### Circom Circuit
 
-# View an author's ENS profile, packages, and risk scores
-opm view djpai.eth
-opm whois djpai
-```
+A reference circom circuit (`packages/contracts/circuits/accuracy_verifier.circom`) implements the verification logic for potential on-chain proof verification:
 
-### npm Passthrough
+```bash
+# Compile
+circom accuracy_verifier.circom --r1cs --wasm --sym -o build/
 
-All standard npm commands work transparently:
+# Trusted setup
+snarkjs groth16 setup build/accuracy_verifier.r1cs pot12_final.ptau build/accuracy_verifier_0000.zkey
+snarkjs zkey contribute build/accuracy_verifier_0000.zkey build/accuracy_verifier_final.zkey --name="opm-ceremony"
 
-```bash
-opm init            opm run dev         opm test
-opm start           opm build           opm uninstall lodash
-opm outdated        opm update          opm list
-opm link            opm pack
+# Export Solidity verifier (for on-chain verification)
+snarkjs zkey export solidityverifier build/accuracy_verifier_final.zkey contracts/AccuracyVerifier.sol
 ```
 
-**Aliases:** `i` / `add` → install, `rm` → uninstall, `ls` → list
+## AI Agent Architecture
 
-### Standalone Scanner
+Three language models evaluate every package publish in parallel. Model diversity is enforced to reduce single-model blind spots and improve consensus reliability. Additional agents can be registered permissionlessly.
 
-```bash
-bun run scan -- <package-name> <version>
-```
+| Agent | OpenRouter (preferred) | 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 |
 
-## npm Publishing
+When `OPENROUTER_API_KEY` is configured, OPM routes through OpenRouter for model diversity. Otherwise, it falls back to OpenAI variants via `OPENAI_API_KEY`. At least one key is required for `opm push`.
 
-OPM handles npm publish as part of `opm push`. If your npm account has 2FA enabled, use an automation token:
+Each agent produces a structured JSON assessment containing:
 
-1. Go to [npmjs.com](https://www.npmjs.com) → Access Tokens → Generate New Token → **Automation**
-2. Pass it via CLI flag or environment:
+- **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
 
-```bash
-opm push --token npm_xxxxxxxxxxxx
-# or
-NPM_TOKEN=npm_xxxxxxxxxxxx opm push
-# or add NPM_TOKEN to your .env
-```
+Agent scores are weighted by model intelligence and coding indices sourced from the Artificial Analysis API, producing an intelligence-weighted aggregate risk score.
 
-The scan runs **before** publish — if the aggregate risk score is CRITICAL (>= 80), the publish and on-chain registration are blocked.
+## Smart Contract: OPMRegistry
 
-## Security Pipeline
+Solidity 0.8.20, deployed on [Base Sepolia](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48). The contract implements a domain-specific form of the three-registry architecture defined by [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004), adapted for package security rather than general-purpose agent economies.
 
-### `opm install` Flow
+### Key Functions
 
-1. **Version resolution** — resolves "latest" from on-chain registry
-2. **CVE database** — queries [OSV API](https://osv.dev) for known vulnerabilities; computes CVSS v3 base scores
-   - CRITICAL CVEs → installation blocked
-   - HIGH CVEs → warning displayed
-   - Shows CVE ID, severity, summary, and suggested fix version
-3. **On-chain registry** — fetches agent consensus risk score
-4. **Signature verification** — verifies ECDSA signature against package checksum
-5. **ChainPatrol** — fallback blocklist check for packages not in the registry
-6. **Fileverse report** — links to the full AI scan report
-7. **Install** — runs `npm install` if all checks pass
+| Function | Access | Description |
+|----------|--------|-------------|
+| `registerPackage` | Public | Register a new package version with checksum, signature, and ENS binding |
+| `submitScore` | Authorized agents | Submit a risk score (0-100) and reasoning string for a package version |
+| `setReportURI` | Authorized agents | Attach a Fileverse report URI to a package version |
+| `registerAgent` | Public | Permissionless agent registration with ZK proof hash |
+| `revokeAgent` | Owner | Deactivate a registered agent |
+| `getAggregateScore` | View | Compute mean risk score across all agent submissions |
+| `getSafestVersion` | View | Return the lowest-risk version within a configurable lookback window |
+| `getScores` | View | Return all individual agent scores for a version |
+| `getPackageInfo` | View | Retrieve full metadata and aggregate score for a package version |
+| `getRegisteredAgent` | View | Retrieve registered agent details |
+| `getAgentCount` | View | Total number of registered agents |
 
-### `opm push` Flow
+### On-chain Activity
 
-1. **Pack & sign** — SHA-256 checksum, ECDSA signature
-2. **ENS resolution** — maps author address to ENS name
-3. **AI security scan** — 3 agents analyze source code, metadata, and version history
-4. **Risk gate** — blocks publish if score >= 80
-5. **npm publish** — with token-based auth support
-6. **On-chain registration** — stores checksum, signature, ENS name, and report URI
+Every transaction is surfaced in the terminal UI with clickable BaseScan links:
 
-## AI Agents
+- **Score submissions**: Each agent's `submitScore` tx → `https://sepolia.basescan.org/tx/{hash}`
+- **Package registration**: `registerPackage` tx → clickable link
+- **Agent registration**: `registerAgent` tx → clickable link
+- **Contract reference**: Direct link to the OPM Registry contract
 
-Three models scan every package in parallel:
+### Risk Thresholds
 
-| Agent | OpenRouter Model | 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 |
+| Threshold | Value | Effect |
+|-----------|-------|--------|
+| `HIGH_RISK_THRESHOLD` | 70 | Packages above this score trigger warnings |
+| `MEDIUM_RISK_THRESHOLD` | 40 | Packages above this score are flagged for caution |
+| Critical gate (CLI) | 80 | `opm push` blocks publication; `opm install` blocks installation |
 
-If `OPENROUTER_API_KEY` is set, OPM uses diverse models for better consensus. Otherwise falls back to OpenAI variants via `OPENAI_API_KEY`.
+## Website
 
-Each agent produces a structured JSON report covering:
-- Risk score (0-100) and risk level
-- Vulnerability analysis with CVE cross-referencing
-- Supply chain indicators (install scripts, obfuscation, network calls, eval usage)
-- Version history analysis and changelog risk assessment
+Landing page built with Next.js + Tailwind CSS.
 
-## ENS Integration
+```bash
+cd packages/web
+npm install
+npm run dev       # Development at http://localhost:3000
+npm run build     # Production build
+npm start         # Start production server
+```
 
-OPM uses the official [`@ensdomains/ensjs`](https://github.com/ensdomains/ensjs) SDK with `viem` for:
+For Railway/Vercel deployment: set the root directory to `packages/web` and use `npm install && npm run build` as the build command.
 
-- **Address → Name** resolution across Sepolia and Mainnet
-- **Name → Address** resolution for author lookups
-- **Text record** fetching (avatar, bio, URL, GitHub, Twitter, email)
-- **Terminal avatar** rendering via `terminal-image` (ANSI pixel art)
-- **Author profiles** via `opm view <name.eth>` showing published packages and risk scores
+## Documentation (Mintlify)
 
-The smart contract stores ENS names alongside author addresses for on-chain identity binding.
+Full documentation is in the `docs/` directory, configured for [Mintlify](https://mintlify.com).
 
-## Integrations
+### Setup
 
-| Integration | Purpose |
-|-------------|---------|
-| **Base Sepolia** | Smart contract deployment (OPMRegistry) |
-| **ENS** | On-chain author identity, profile display, name resolution |
-| **Fileverse dDocs** | Encrypted, decentralized storage for styled security reports |
-| **ChainPatrol** | Fallback blocklist for packages not in the registry |
-| **OSV API** | Real CVE/GHSA vulnerability data with CVSS v3 scoring |
-| **OpenRouter / OpenAI** | Multi-model AI scanning (Claude, Gemini, DeepSeek, GPT) |
+```bash
+npm i -g mintlify
+cd docs
+mintlify dev
+```
 
-## Smart Contract
+Opens at `http://localhost:3333`. The docs cover:
 
-`OPMRegistry.sol` on Base Sepolia:
+- **Getting Started**: Introduction, Quickstart, Configuration
+- **Core Concepts**: Security Model, Multi-Agent Consensus, On-chain Registry, ZK Agent Verification
+- **CLI Reference**: All commands with usage, flags, and examples
+- **Smart Contract**: Functions, Events, Deployment
+- **Architecture**: Scanner engine, Agent system, Benchmark suite
 
-- Package registration with checksum, signature, and ENS binding
-- Authorized agent score submission (gas-funded agent wallets)
-- Fileverse report URI storage per package version
-- Aggregate risk scoring across agents
-- Safest version lookup with configurable lookback
-- Author reputation tracking (average score across all packages)
-- ENS-to-author mapping for reverse lookups
+### Deploy to Mintlify
+
+Push your repo to GitHub and connect it to [Mintlify](https://mintlify.com/start) — it auto-deploys from the `docs/` directory.
 
 ## Project Structure
 
 ```
 packages/
-  core/        Shared types, constants, ABI, prompts, utilities
-  contracts/   OPMRegistry.sol + Hardhat config, tests, deploy script
-  scanner/     AI agents, in-memory queue, Fileverse upload, report formatter
-  cli/         Ink-based terminal UI
-    commands/    push, install, audit, info, author-view, passthrough
-    components/  Header, StatusLine, RiskBadge, PackageCard, AuthorInfo
-    services/    contract, ens, osv, signature, chainpatrol, fileverse, avatar
+  core/             Shared types, constants, ABI, prompt schemas, model rankings, benchmarks
+  contracts/        OPMRegistry.sol, Hardhat config, deployment scripts, tests
+    circuits/       Circom ZK circuit for accuracy verification
+  scanner/          AI agent runner, LLM client, queue, Fileverse, benchmark runner, ZK verifier
+  cli/              Ink-based terminal UI
+    commands/       push, install, check, fix, audit, info, author-view, register-agent, passthrough
+    components/     Header, StatusLine, RiskBadge, Hyperlink, PackageCard, AuthorInfo, AgentScores
+    services/       contract, ens, osv, signature, chainpatrol, fileverse, avatar, typosquat, version
+  web/              Next.js landing page (dark mode, Tailwind CSS)
+docs/               Mintlify documentation (mint.json + MDX pages)
 ```
 
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPM_PRIVATE_KEY` | Yes | Author's Ethereum private key for signing |
-| `AGENT_PRIVATE_KEY` | Yes | Agent wallet key for contract gas on Base Sepolia |
-| `CONTRACT_ADDRESS` | Yes | Deployed OPMRegistry contract address |
-| `OPENAI_API_KEY` | * | OpenAI API key (auto-selects gpt-4.1 variants) |
-| `OPENROUTER_API_KEY` | * | OpenRouter API key (multi-model: Claude, Gemini, DeepSeek) |
-| `CHAINPATROL_API_KEY` | Yes | ChainPatrol API key for blocklist checks |
-| `BASE_SEPOLIA_RPC_URL` | No | Base Sepolia RPC (default: https://sepolia.base.org) |
-| `ETH_MAINNET_RPC_URL` | No | Mainnet RPC for ENS (default: https://eth.llamarpc.com) |
-| `ETH_SEPOLIA_RPC_URL` | No | Sepolia RPC for ENS (default: public endpoint) |
-| `FILEVERSE_API_KEY` | Yes | Fileverse API key from ddocs.new Developer Mode |
-| `FILEVERSE_API_URL` | No | Fileverse local API URL (default: http://localhost:8001) |
-| `NPM_TOKEN` | No | npm automation token (alternative to `--token` flag) |
-
-\* One of `OPENAI_API_KEY` or `OPENROUTER_API_KEY` is required for AI scanning.
-
-## Run Contract Tests
+Client-side commands (`install`, `check`, `fix`, `audit`, `info`, `view`, `whois`) operate with zero configuration.
+
+Author-side commands (`push`) require the following:
+
+| Variable | Description |
+|----------|-------------|
+| `OPM_SIGNING_KEY` | Ethereum private key for ECDSA package signing |
+| `AGENT_PRIVATE_KEY` | Agent wallet private key (funds on-chain score submission gas) |
+| `NPM_TOKEN` | npm automation token (alternative to `--token` CLI flag) |
+| `OPENAI_API_KEY` | OpenAI API key; selects GPT-4.1 / Mini / Nano agents |
+| `OPENROUTER_API_KEY` | OpenRouter API key; enables Claude, Gemini, DeepSeek model diversity |
+| `FILEVERSE_API_KEY` | Fileverse API key (generate at ddocs.new, Settings, Developer Mode) |
+
+Agent registration (`register-agent`) requires:
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_PRIVATE_KEY` | Wallet that becomes the agent identity on-chain |
+| `OPENROUTER_API_KEY` or `OPENAI_API_KEY` | Required to run LLM benchmark calls |
+
+Optional overrides (defaults are compiled in):
+
+| Variable | Default |
+|----------|---------|
+| `CONTRACT_ADDRESS` | `0x16684391fc9bf48246B08Afe16d1a57BFa181d48` |
+| `BASE_SEPOLIA_RPC_URL` | `https://sepolia.base.org` |
+| `CHAINPATROL_API_KEY` | Optional; enables blocklist checks |
+| `ARTIFICIAL_ANALYSIS_API_KEY` | Optional; enables intelligence-weighted scoring |
+
+## Testing
+
+### Contract Tests
 
 ```bash
 cd packages/contracts && npx hardhat test
 ```
 
+### Standalone Scanner
+
+```bash
+bun run scan -- <package-name> <version>
+```
+
+## Links
+
+- **npm**: [npmjs.com/package/opmsec](https://www.npmjs.com/package/opmsec)
+- **GitHub**: [github.com/dhananjaypai08/opm](https://github.com/dhananjaypai08/opm)
+- **Contract**: [BaseScan](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48)
+
 ## License
 
 MIT