opmsec 0.1.0 → 0.1.3

package/docs/cli/view.mdx

@@ -0,0 +1,52 @@
+---
+title: 'opm view / opm whois'
+description: 'Author profile and published packages.'
+---
+
+# opm view / opm whois
+
+Show author profile and published packages. Resolves ENS identity and displays on-chain reputation.
+
+## Usage
+
+<CodeGroup>
+
+```bash View by ENS name
+opm view vitalik.eth
+```
+
+```bash Whois (auto-appends .eth)
+opm whois vitalik
+```
+
+</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>.
+</Note>
+
+## Output
+
+### Identity
+
+- **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>

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

@@ -0,0 +1,58 @@
+---
+title: 'Multi-Agent Consensus'
+description: 'Three LLMs run in parallel, submit scores on-chain, and 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.
+
+## Agent Configuration
+
+| 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 |
+
+Model diversity reduces single-model blind spots and improves consensus reliability. Override models via `AGENT1_MODEL`, `AGENT2_MODEL`, and `AGENT3_MODEL`.
+
+## Analysis Pipeline
+
+Each agent receives:
+
+- 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 produces structured JSON:
+
+- **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.
+
+<Note>
+If `ARTIFICIAL_ANALYSIS_API_KEY` is unset or the API is unavailable, OPM falls back to **equal weighting** (simple arithmetic mean).
+</Note>
+
+## Fallback Behavior
+
+- **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.

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

@@ -0,0 +1,74 @@
+---
+title: 'On-chain Registry'
+description: 'OPMRegistry.sol stores packages, versions, author profiles, agent scores, and report URIs on Base Sepolia.'
+---
+
+# 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.
+
+## Deployment
+
+| Property | Value |
+|----------|-------|
+| **Chain** | Base Sepolia |
+| **Chain ID** | 84532 |
+| **Contract Address** | `0x16684391fc9bf48246B08Afe16d1a57BFa181d48` |
+| **Explorer** | [BaseScan](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48) |
+
+Override via `CONTRACT_ADDRESS` in your environment.
+
+## Data Structures
+
+| 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 Functions
+
+| 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` |
+
+## 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.
+
+## Risk Thresholds (Contract)
+
+| Constant | Value |
+|----------|-------|
+| `HIGH_RISK_THRESHOLD` | 70 |
+| `MEDIUM_RISK_THRESHOLD` | 40 |

package/docs/concepts/security-model.mdx

@@ -0,0 +1,76 @@
+---
+title: 'Security Model'
+description: 'OPM defense-in-depth: cryptographic attestation, multi-agent AI, CVE integration, supply chain checks, and ENS-based 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.
+
+## 1. Cryptographic Layer
+
+- **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
+
+Installation is blocked if the tarball checksum does not match the on-chain value or if the signature verification fails.
+
+## 2. AI Layer
+
+Three heterogeneous LLMs analyze packages in parallel:
+
+- 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
+
+<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>
+
+## 3. CVE Layer
+
+- **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
+
+## 4. Supply Chain 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
+
+## Risk Thresholds
+
+| Range | Level | Effect |
+|-------|-------|--------|
+| 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 |

package/docs/concepts/zk-agent-verification.mdx

@@ -0,0 +1,82 @@
+---
+title: 'ZK Agent Verification'
+description: 'Permissionless agent registration requires passing a benchmark suite and proving 100% accuracy via zero-knowledge proofs.'
+---
+
+# ZK Agent Verification
+
+OPM supports **permissionless agent registration** on the on-chain registry. To prevent malicious or spamming agents from participating, agents must pass a benchmark suite and prove **100% accuracy** via a zero-knowledge proof—without revealing the test data or individual results.
+
+## Benchmark Suite
+
+The benchmark consists of **10 labeled test cases** covering:
+
+| Category | Description |
+|----------|-------------|
+| Clean packages | Legitimate, low-risk packages |
+| Typosquats | Name-similar malicious packages |
+| Env exfiltration | Environment variable exfiltration attempts |
+| Obfuscated code | Heavily obfuscated or minified payloads |
+| Postinstall attacks | Malicious `postinstall` scripts |
+| Known CVEs | Packages with known vulnerabilities |
+| Dependency confusion | Scoped vs unscoped name conflicts |
+
+Each test case has an **expected output**: a risk level (LOW, MEDIUM, HIGH, CRITICAL) and score range. Expected outputs are committed via a hash before the agent runs.
+
+## Verification Flow
+
+1. **Commitment**: Expected outputs hashed with a salt → `commitmentHash`
+2. **Execution**: Candidate agent runs against all 10 cases
+3. **Comparison**: Actual outputs compared to expected; `passed = 1` iff all match
+4. **Proof**: ZK proof binds `commitmentHash`, `passed`, and `result_hash` without revealing test data or individual results
+5. **Registration**: Only agents with `passed = 1` (100% accuracy) are registered on-chain
+
+## Circom Circuit
+
+The `accuracy_verifier.circom` circuit implements the verification logic:
+
+- **Private inputs**: `expected[N]`, `actual[N]`, `salt`
+- **Public input**: `commitmentHash` (Poseidon hash of `salt` and `expected[0..N-1]`)
+- **Public outputs**: `passed` (1 if all match, 0 otherwise), `proofHash`
+
+The circuit:
+
+1. Verifies the commitment: `hash(salt, expected[0..N-1]) === commitmentHash`
+2. Checks equality for each test case: `expected[i] === actual[i]`
+3. Computes `passed` as the product of all match bits (1 iff all match)
+4. Outputs `proofHash = hash(commitmentHash, passed, salt)` binding the result to the commitment
+
+<CodeGroup>
+
+```bash Compile
+circom accuracy_verifier.circom --r1cs --wasm --sym -o build/
+```
+
+```bash 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"
+snarkjs zkey export verificationkey build/accuracy_verifier_final.zkey build/verification_key.json
+```
+
+```bash Prove
+snarkjs groth16 prove build/accuracy_verifier_final.zkey build/accuracy_verifier_js/accuracy_verifier.wasm input.json build/proof.json build/public.json
+```
+
+```bash Verify
+snarkjs groth16 verify build/verification_key.json build/public.json build/proof.json
+```
+
+</CodeGroup>
+
+## On-Chain Registration
+
+Agents call `OPMRegistry.registerAgent(name, model, systemPromptHash, proofHash)` with a valid proof hash. The contract:
+
+- Requires `proofHash != bytes32(0)`
+- Rejects agents already authorized or registered
+- Stores `RegisteredAgent` with `proofHash` for auditability
+- Auto-authorizes the agent for `submitScore` and `setReportURI`
+
+<Warning>
+The Circom circuit is available for on-chain verification. A Solidity verifier can be exported via `snarkjs zkey export solidityverifier` for full trustless verification in future contract upgrades.
+</Warning>

package/docs/configuration.mdx

@@ -0,0 +1,82 @@
+---
+title: 'Configuration'
+description: 'Environment variables for OPM: signing keys, API keys, RPC URLs, and model overrides.'
+---
+
+# Configuration
+
+OPM is configured via environment variables. Read-only commands (`install`, `audit`, `info`, `view`, `whois`, `check`) work with zero configuration. Author-side commands (`push`, `register-agent`) require keys and optional overrides.
+
+## Environment Variables
+
+### Signing & Identity
+
+| Variable | Description | Required For |
+|----------|-------------|--------------|
+| `OPM_SIGNING_KEY` | Author's Ethereum private key for package signing (ECDSA secp256k1) | `opm push` |
+| `OPM_PRIVATE_KEY` | Alias for `OPM_SIGNING_KEY` | `opm push` |
+| `AGENT_PRIVATE_KEY` | Agent wallet key for score submission and agent registration; must hold Base Sepolia ETH for gas | `opm push`, `register-agent` |
+
+### npm
+
+| Variable | Description | Required For |
+|----------|-------------|--------------|
+| `NPM_TOKEN` | npm automation token for publish (bypasses 2FA) | `opm push` (optional; use `--token` flag otherwise) |
+
+### AI / LLM
+
+| Variable | Description | Required For |
+|----------|-------------|--------------|
+| `OPENROUTER_API_KEY` | OpenRouter API key for multi-model access (Claude, Gemini, DeepSeek) | `opm push`, `opm check` (at least one of OPENROUTER or OPENAI) |
+| `OPENAI_API_KEY` | OpenAI API key; fallback to GPT-4.1 family | `opm push`, `opm check` |
+| `LLM_PROVIDER` | Force provider: `"openrouter"` or `"openai"` | Optional override |
+| `AGENT1_MODEL` | Override agent-1 model (default: Claude Sonnet 4) | Optional |
+| `AGENT2_MODEL` | Override agent-2 model (default: Gemini 2.5 Flash) | Optional |
+| `AGENT3_MODEL` | Override agent-3 model (default: DeepSeek Chat) | Optional |
+
+### Report Storage
+
+| Variable | Description | Required For |
+|----------|-------------|--------------|
+| `FILEVERSE_API_KEY` | API key for report uploads to IPFS (generate at [ddocs.new](https://ddocs.new) → Settings → Developer Mode) | `opm push` report uploads |
+| `FILEVERSE_API_URL` | Override Fileverse API base URL (default: `http://localhost:8001`) | Optional |
+
+### On-Chain Registry
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CONTRACT_ADDRESS` | OPMRegistry contract address | `0x16684391fc9bf48246B08Afe16d1a57BFa181d48` |
+| `BASE_SEPOLIA_RPC_URL` | Base Sepolia RPC endpoint | `https://sepolia.base.org` |
+
+### External Services
+
+| Variable | Description | Required For |
+|----------|-------------|--------------|
+| `CHAINPATROL_API_KEY` | ChainPatrol API key for blocklist checks | Optional; enables blocklist fallback |
+| `ARTIFICIAL_ANALYSIS_API_KEY` | API key for model intelligence rankings (intelligence-weighted scoring) | Optional; falls back to equal weighting if unset |
+
+## Example `.env`
+
+<CodeGroup>
+
+```bash Minimal
+# No env vars needed for: install, audit, info, view, whois, check
+```
+
+```bash Full (push + reports)
+OPM_SIGNING_KEY=0x...
+AGENT_PRIVATE_KEY=0x...
+NPM_TOKEN=npm_...
+OPENROUTER_API_KEY=sk-or-...
+FILEVERSE_API_KEY=...
+CONTRACT_ADDRESS=0x16684391fc9bf48246B08Afe16d1a57BFa181d48
+BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+CHAINPATROL_API_KEY=...
+ARTIFICIAL_ANALYSIS_API_KEY=...
+```
+
+</CodeGroup>
+
+<Tip>
+Start the Fileverse API server locally before `opm push` if using report uploads: `npx @fileverse/api --apiKey <YOUR_API_KEY>`
+</Tip>

package/docs/contract/deployment.mdx

@@ -0,0 +1,57 @@
+---
+title: 'Deployment'
+description: 'Deploy OPMRegistry to Base Sepolia.'
+---
+
+# Deployment
+
+## Prerequisites
+
+- **Node.js** (v18+)
+- **Hardhat** (via <code>npx hardhat</code>)
+- **Base Sepolia ETH** for gas (obtain from [Base Sepolia Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet))
+
+## Environment Variables
+
+Create a <code>.env</code> file in <code>packages/contracts</code>:
+
+<CodeGroup>
+
+```bash .env
+BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+DEPLOYER_PRIVATE_KEY=0x...   # Deployer wallet (receives owner role)
+AGENT_PRIVATE_KEY=0x...      # Optional: auto-authorize this agent after deploy
+```
+
+</CodeGroup>
+
+## Commands
+
+<Steps>
+  <Step title="Compile">
+    <CodeGroup>
+      ```bash
+      npx hardhat compile
+      ```
+    </CodeGroup>
+  </Step>
+  <Step title="Deploy">
+    <CodeGroup>
+      ```bash
+      npx hardhat run scripts/deploy.ts --network baseSepolia
+      ```
+    </CodeGroup>
+  </Step>
+  <Step title="Authorize initial agents">
+    If <code>AGENT_PRIVATE_KEY</code> is set, the deploy script automatically calls <code>setAgent(agentAddress, true)</code>. Otherwise, call <code>setAgent</code> on the contract via Hardhat console or a custom script.
+  </Step>
+</Steps>
+
+## Post-Deploy
+
+1. **Set contract address** — Add <code>CONTRACT_ADDRESS=&lt;deployed-address&gt;</code> to your CLI and scanner <code>.env</code>.
+2. **Verify on BaseScan** — Run <code>npx hardhat verify --network baseSepolia &lt;CONTRACT_ADDRESS&gt;</code> to publish source code for verification.
+
+<Note>
+The deploy script outputs the contract address. The default OPM contract is <code>0x16684391fc9bf48246B08Afe16d1a57BFa181d48</code> on Base Sepolia.
+</Note>

package/docs/contract/events.mdx

@@ -0,0 +1,115 @@
+---
+title: 'Contract Events'
+description: 'All OPMRegistry events with parameters.'
+---
+
+# Contract Events
+
+## PackageRegistration
+
+### PackageRegistered
+
+```solidity
+event PackageRegistered(string name, string version, address author, string ensName);
+```
+
+Emitted when a package version is registered via <code>registerPackage</code>.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Package name |
+| version | string | Semantic version |
+| author | address | Author wallet address |
+| ensName | string | Author ENS name |
+
+---
+
+## Score Submission
+
+### ScoreSubmitted
+
+```solidity
+event ScoreSubmitted(string name, string version, address agent, uint8 riskScore, string reasoning);
+```
+
+Emitted when an agent submits a risk score via <code>submitScore</code>.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Package name |
+| version | string | Semantic version |
+| agent | address | Agent wallet address |
+| riskScore | uint8 | Risk score 0–100 |
+| reasoning | string | Agent reasoning |
+
+### ReportURISet
+
+```solidity
+event ReportURISet(string name, string version, string uri);
+```
+
+Emitted when an agent sets the report URI via <code>setReportURI</code>.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Package name |
+| version | string | Semantic version |
+| uri | string | Fileverse/IPFS report URI |
+
+---
+
+## Author
+
+### AuthorRegistered
+
+```solidity
+event AuthorRegistered(address addr, string ensName);
+```
+
+Emitted when an author is first registered (on first <code>registerPackage</code> call).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| addr | address | Author wallet address |
+| ensName | string | Author ENS name |
+
+---
+
+## Agent Management
+
+### AgentAuthorized
+
+```solidity
+event AgentAuthorized(address agent, bool status);
+```
+
+Emitted when an agent is authorized or deauthorized via <code>setAgent</code> or <code>revokeAgent</code>, or when a new agent registers via <code>registerAgent</code>.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| agent | address | Agent wallet address |
+| status | bool | true = authorized, false = deauthorized |
+
+### AgentRegistered
+
+```solidity
+event AgentRegistered(
+    address indexed agent,
+    string name,
+    string model,
+    bytes32 systemPromptHash,
+    bytes32 proofHash,
+    uint256 timestamp
+);
+```
+
+Emitted when a new agent registers via <code>registerAgent</code> (permissionless ZK-verified registration).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| agent | address | Agent wallet address (indexed) |
+| name | string | Agent identifier |
+| model | string | LLM model |
+| systemPromptHash | bytes32 | Keccak256 of system prompt |
+| proofHash | bytes32 | Keccak256 of ZK proof |
+| timestamp | uint256 | Block timestamp |