@agenticvault/agentic-vault 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "agentic-vault",
+  "displayName": "Agentic Vault",
+  "version": "0.1.0",
+  "description": "Server-side EVM signing with policy-constrained MCP tools for Claude Code",
+  "publisher": "agenticvault",
+  "skills": [
+    "skills/sign-swap/SKILL.md",
+    "skills/sign-permit/SKILL.md",
+    "skills/check-wallet/SKILL.md",
+    "skills/audit-log/SKILL.md"
+  ],
+  "mcpServers": {
+    "agentic-vault": {
+      "command": "node",
+      "args": ["dist/agentic/cli.js"]
+    }
+  }
+}

package/.env.example

@@ -0,0 +1,16 @@
+# AWS KMS Signer Configuration
+# Used by agentic-vault CLI and MCP server as fallback when --key-id/--region flags are omitted.
+VAULT_KEY_ID=alias/my-signing-key
+VAULT_REGION=us-east-1
+
+# AWS Credentials (choose one method)
+# Method 1: AWS SSO / IAM role (recommended — no env vars needed)
+# Method 2: Static credentials
+# AWS_ACCESS_KEY_ID=AKIA...
+# AWS_SECRET_ACCESS_KEY=...
+# AWS_SESSION_TOKEN=...
+# Method 3: Named profile
+# AWS_PROFILE=my-profile
+
+# Testnet RPC (for integration tests only)
+# SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY

package/.mcp.json.example

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "agentic-vault": {
+      "command": "npx",
+      "args": [
+        "-y", "-p", "@agenticvault/agentic-vault",
+        "agentic-vault-mcp",
+        "--key-id", "YOUR_KMS_KEY_ID",
+        "--region", "us-east-1"
+      ],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
+        "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
+        "AWS_SESSION_TOKEN": "${AWS_SESSION_TOKEN}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agenticvault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,163 @@
+<!-- Source: README.md | Commit: 96a8dcc | Last synced: 2026-02-16 -->
+
+# Agentic Vault
+
+[![npm version](https://img.shields.io/npm/v/@agenticvault/agentic-vault)](https://www.npmjs.com/package/@agenticvault/agentic-vault)
+[![CI](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | 日本語 | [한국어](README.ko.md)
+
+AWS KMS によるサーバーサイド EVM 署名と、組み込みの DeFi プロトコル解析機能を提供します。MCP、CLI、または OpenClaw を通じてウォレットを AI エージェントに公開し、デフォルト拒否のポリシーエンジンと完全な監査ログを備えています。
+
+## Agentic Vault を選ぶ理由
+
+AI エージェントはブロックチェーントランザクションに署名する必要がありますが、秘密鍵を直接渡すのは危険です。Agentic Vault は鍵を AWS KMS（HSM）に保管し、エージェントが署名できる操作範囲を制限するポリシーエンジンを提供します。エージェントからは高レベルのツール（`sign_swap`、`sign_permit`）のみが見え、秘密鍵がハードウェアの外に出ることはありません。
+
+## 特徴
+
+- **HSM による安全な署名** -- 秘密鍵は AWS KMS の外に出ることはなく、署名にはダイジェストのみが送信されます
+- **DeFi プロトコル対応** -- ERC-20、Uniswap V3、Aave V3 の calldata デコードとプロトコル固有のポリシールールに対応
+- **デフォルト拒否ポリシーエンジン** -- チェーン ID、コントラクト、セレクター、金額、期限、およびプロトコルレベルの制約
+- **複数のインターフェース** -- TypeScript ライブラリ、CLI、MCP サーバー、または OpenClaw プラグインとして使用可能
+- **監査ログ** -- すべての署名操作（承認、拒否、エラー）の構造化 JSON 監査記録
+- **EVM ネイティブ** -- [viem](https://viem.sh) をベースに構築、EIP-712 型付きデータを完全サポート
+
+## クイックスタート
+
+```bash
+npm install @agenticvault/agentic-vault
+```
+
+```typescript
+import { createSigningProvider, EvmSignerAdapter } from '@agenticvault/agentic-vault';
+
+const provider = createSigningProvider({
+  provider: 'aws-kms',
+  keyId: 'arn:aws:kms:us-east-1:123456789:key/your-key-id',
+  region: 'us-east-1',
+});
+
+const signer = new EvmSignerAdapter(provider);
+const address = await signer.getAddress();
+```
+
+AWS 不要のクイックテストには `dry-run` モード（デコード + ポリシーチェックのみ、署名なし）をご利用ください：
+
+```bash
+npx agentic-vault dry-run --chain-id 1 --to 0xa0b869... --data 0x095ea7b3...
+```
+
+鍵の作成と IAM ポリシーの設定については [AWS KMS セットアップガイド](docs/guides/aws-kms-setup.md)をご覧ください。
+
+## インターフェース
+
+| インターフェース | ユースケース | AWS 必須 |
+|-----------------|-------------|:---:|
+| TypeScript ライブラリ | アプリケーションに署名機能を組み込む | はい |
+| CLI | コマンドライン署名 + ドライラン | 一部 |
+| MCP サーバー | AI エージェント（Claude など）にウォレットを公開 | はい |
+| OpenClaw プラグイン | OpenClaw エージェントツールとして使用 | はい |
+
+使用例と設定については[インターフェースガイド](docs/guides/interfaces.md)をご覧ください。
+
+## 対応プロトコル
+
+| プロトコル | アクション | デコーダー | ポリシー評価器 |
+|-----------|-----------|:---:|:---:|
+| ERC-20 | `approve`、`transfer` | あり | あり（承認上限、spender ホワイトリスト） |
+| Uniswap V3 | `exactInputSingle` | あり | あり（トークンペア、スリッページ、受取人） |
+| Aave V3 | `supply`、`borrow`、`repay`、`withdraw` | あり | あり（アセットホワイトリスト、金利モード） |
+
+不明な calldata は常に拒否されます（フェイルクローズ）。Dispatcher は 2 段階の解決を使用します：まずコントラクトアドレス、次にセレクターベースのフォールバック（例：ERC-20）。
+
+## 設定
+
+ポリシーエンジンは JSON 設定ファイルを使用します。ポリシーファイルが未提供の場合、ポリシーで管理されるすべての署名操作は拒否されます（デフォルト拒否）。
+
+完全なスキーマと例については[ポリシーリファレンス](docs/reference/policy.md)をご覧いただくか、[`policy.example.json`](policy.example.json) から始めてください。
+
+## セキュリティモデル
+
+### 信頼境界
+
+```
+ AI エージェント（Claude / MCP Client / OpenClaw）
+          |
+          | MCP Protocol / OpenClaw Plugin API
+          v
+ +------------------------------------+
+ |   Agentic Vault                    |
+ |  +-----------+ +--------+ +-----+ |
+ |  | Protocol  | | Policy | | Audit| |
+ |  | Dispatcher| | Engine | | Sink | |
+ |  +-----------+ +--------+ +-----+ |
+ |          |                         |
+ |  +--------------------+           |
+ |  | EvmSignerAdapter   |           |
+ |  +--------------------+           |
+ +-----------|------------------------+
+             | ダイジェストのみ
+             v
+ +------------------------------------+
+ |       AWS KMS (HSM)                |
+ |   秘密鍵は外部に出ません            |
+ +------------------------------------+
+```
+
+### 基本原則
+
+| 原則 | 説明 |
+|------|------|
+| 鍵の隔離 | 秘密鍵は HSM 内に保持され、署名には 32 バイトのダイジェストのみが送信されます |
+| デフォルト拒否 | ポリシーエンジンは明示的に許可されていないすべてのリクエストを拒否します |
+| フェイルクローズ | 不明な calldata は常に拒否されます。既知のプロトコルでも評価器がなければ拒否されます |
+| 監査証跡 | すべての操作は構造化 JSON として stderr に記録され、呼び出し元タグが付与されます |
+| 最小限の攻撃面 | 生の署名ツール（`sign_transaction`、`sign_typed_data`）はデフォルトで無効です |
+
+## Claude Code プラグイン
+
+4 つのスキルが MCP ツールを通じてウォレットと連携します。鍵に直接アクセスすることはありません。
+
+| スキル | 説明 |
+|--------|------|
+| `sign-swap` | スワップ署名操作のオーケストレーション |
+| `sign-permit` | EIP-2612 permit 署名のオーケストレーション |
+| `check-wallet` | ウォレットアドレスとヘルスステータスの確認 |
+| `audit-log` | 監査ログのクエリ |
+
+## パッケージエクスポート
+
+| サブパス | 内容 | MCP 依存 |
+|---------|------|:-:|
+| `@agenticvault/agentic-vault` | コア署名（SigningProvider、EvmSignerAdapter、factory） | なし |
+| `@agenticvault/agentic-vault/protocols` | プロトコルデコーダー、dispatcher、PolicyEngine V2、workflows | なし |
+| `@agenticvault/agentic-vault/agentic` | MCP サーバー、監査ログ記録 | あり |
+
+## ドキュメント
+
+| ドキュメント | 説明 |
+|-------------|------|
+| [インターフェースガイド](docs/guides/interfaces.md) | TypeScript、CLI、MCP、OpenClaw の使い方 |
+| [ポリシーリファレンス](docs/reference/policy.md) | ポリシー JSON スキーマ、フィールド、例 |
+| [AWS KMS セットアップ](docs/guides/aws-kms-setup.md) | 鍵の作成、IAM ポリシー、認証方法 |
+| [OpenClaw プラグイン](packages/openclaw-plugin/) | OpenClaw プラグインパッケージと設定 |
+| [アーキテクチャ決定](docs/project/adrs/ADR-001-architecture-decisions.md) | 主要な設計決定の ADR |
+| [コントリビュートガイド](CONTRIBUTING.md) | 開発ワークフローとガイドライン |
+
+## ロードマップ
+
+- 追加の署名プロバイダー（GCP KMS、HashiCorp Vault）
+- 追加のプロトコルデコーダー（Curve、Compound V3）
+- マルチシグネチャ対応
+- リモート MCP サーバーモード（HTTP トランスポート + OAuth 2.1）
+
+## コントリビュート
+
+開発ワークフロー、ブランチ命名規則、コミット規約については [CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。
+
+本プロジェクトは [Contributor Covenant 行動規範](CODE_OF_CONDUCT.md) に従います。
+
+## ライセンス
+
+[MIT](LICENSE)

package/README.ko.md

@@ -0,0 +1,163 @@
+<!-- Source: README.md | Commit: 96a8dcc | Last synced: 2026-02-16 -->
+
+# Agentic Vault
+
+[![npm version](https://img.shields.io/npm/v/@agenticvault/agentic-vault)](https://www.npmjs.com/package/@agenticvault/agentic-vault)
+[![CI](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | 한국어
+
+AWS KMS를 활용한 서버 측 EVM 서명과 내장된 DeFi 프로토콜 인식 기능을 제공합니다. MCP, CLI 또는 OpenClaw를 통해 지갑을 AI 에이전트에 노출하며, 기본 거부 정책 엔진과 완전한 감사 로깅을 갖추고 있습니다.
+
+## Agentic Vault를 선택하는 이유
+
+AI 에이전트는 블록체인 트랜잭션에 서명해야 하지만, 개인키를 직접 제공하는 것은 위험합니다. Agentic Vault는 키를 AWS KMS(HSM)에 보관하고, 에이전트가 서명할 수 있는 작업 범위를 제한하는 정책 엔진을 제공합니다. 에이전트는 고수준 도구(`sign_swap`, `sign_permit`)만 볼 수 있으며, 개인키는 절대 하드웨어 밖으로 나가지 않습니다.
+
+## 주요 기능
+
+- **HSM 기반 안전한 서명** -- 개인키는 AWS KMS를 벗어나지 않으며, 서명에는 다이제스트만 전송됩니다
+- **DeFi 프로토콜 인식** -- ERC-20, Uniswap V3, Aave V3의 calldata 디코딩 및 프로토콜별 정책 규칙 지원
+- **기본 거부 정책 엔진** -- 체인 ID, 컨트랙트, 셀렉터, 금액, 기한 및 프로토콜 수준 제약
+- **다양한 인터페이스** -- TypeScript 라이브러리, CLI, MCP 서버 또는 OpenClaw 플러그인으로 사용 가능
+- **감사 로그** -- 모든 서명 작업(승인, 거부, 오류)에 대한 구조화된 JSON 감사 기록
+- **EVM 네이티브** -- [viem](https://viem.sh) 기반으로 구축, EIP-712 타입 데이터 완전 지원
+
+## 빠른 시작
+
+```bash
+npm install @agenticvault/agentic-vault
+```
+
+```typescript
+import { createSigningProvider, EvmSignerAdapter } from '@agenticvault/agentic-vault';
+
+const provider = createSigningProvider({
+  provider: 'aws-kms',
+  keyId: 'arn:aws:kms:us-east-1:123456789:key/your-key-id',
+  region: 'us-east-1',
+});
+
+const signer = new EvmSignerAdapter(provider);
+const address = await signer.getAddress();
+```
+
+AWS 없이 빠른 테스트를 하려면 `dry-run` 모드(디코딩 + 정책 검사만, 서명 없음)를 사용하세요:
+
+```bash
+npx agentic-vault dry-run --chain-id 1 --to 0xa0b869... --data 0x095ea7b3...
+```
+
+키 생성 및 IAM 정책 설정은 [AWS KMS 설정 가이드](docs/guides/aws-kms-setup.md)를 참조하세요.
+
+## 인터페이스
+
+| 인터페이스 | 사용 사례 | AWS 필수 |
+|-----------|----------|:---:|
+| TypeScript 라이브러리 | 애플리케이션에 서명 기능 내장 | 예 |
+| CLI | 커맨드라인 서명 + 드라이런 | 부분 |
+| MCP 서버 | AI 에이전트(Claude 등)에 지갑 노출 | 예 |
+| OpenClaw 플러그인 | OpenClaw 에이전트 도구로 사용 | 예 |
+
+사용 예제 및 설정은 [인터페이스 가이드](docs/guides/interfaces.md)를 참조하세요.
+
+## 지원 프로토콜
+
+| 프로토콜 | 작업 | 디코더 | 정책 평가기 |
+|---------|------|:---:|:---:|
+| ERC-20 | `approve`, `transfer` | 있음 | 있음 (승인 한도, spender 화이트리스트) |
+| Uniswap V3 | `exactInputSingle` | 있음 | 있음 (토큰 페어, 슬리피지, 수신자) |
+| Aave V3 | `supply`, `borrow`, `repay`, `withdraw` | 있음 | 있음 (자산 화이트리스트, 금리 모드) |
+
+알 수 없는 calldata는 항상 거부됩니다(페일 클로즈). Dispatcher는 2단계 해석을 사용합니다: 먼저 컨트랙트 주소, 그다음 셀렉터 기반 폴백(예: ERC-20).
+
+## 설정
+
+정책 엔진은 JSON 설정 파일을 사용합니다. 정책 파일이 제공되지 않으면 정책으로 관리되는 모든 서명 작업이 거부됩니다(기본 거부).
+
+전체 스키마와 예제는 [정책 레퍼런스](docs/reference/policy.md)를 참조하거나, [`policy.example.json`](policy.example.json)에서 시작하세요.
+
+## 보안 모델
+
+### 신뢰 경계
+
+```
+ AI 에이전트 (Claude / MCP Client / OpenClaw)
+          |
+          | MCP Protocol / OpenClaw Plugin API
+          v
+ +------------------------------------+
+ |   Agentic Vault                    |
+ |  +-----------+ +--------+ +-----+ |
+ |  | Protocol  | | Policy | | Audit| |
+ |  | Dispatcher| | Engine | | Sink | |
+ |  +-----------+ +--------+ +-----+ |
+ |          |                         |
+ |  +--------------------+           |
+ |  | EvmSignerAdapter   |           |
+ |  +--------------------+           |
+ +-----------|------------------------+
+             | 다이제스트만 전송
+             v
+ +------------------------------------+
+ |       AWS KMS (HSM)                |
+ |   개인키는 외부로 유출되지 않음       |
+ +------------------------------------+
+```
+
+### 핵심 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| 키 격리 | 개인키는 HSM 내에 보관되며, 서명에는 32바이트 다이제스트만 전송됩니다 |
+| 기본 거부 | 정책 엔진은 명시적으로 허용되지 않은 모든 요청을 거부합니다 |
+| 페일 클로즈 | 알 수 없는 calldata는 항상 거부됩니다. 알려진 프로토콜이라도 평가기가 없으면 거부됩니다 |
+| 감사 추적 | 모든 작업은 구조화된 JSON으로 stderr에 기록되며, 호출자 태그가 포함됩니다 |
+| 최소 공격면 | 원시 서명 도구(`sign_transaction`, `sign_typed_data`)는 기본적으로 비활성화됩니다 |
+
+## Claude Code 플러그인
+
+4개의 스킬이 MCP 도구를 통해 지갑과 상호작용합니다. 키에 직접 접근하지 않습니다.
+
+| 스킬 | 설명 |
+|------|------|
+| `sign-swap` | 스왑 서명 작업 오케스트레이션 |
+| `sign-permit` | EIP-2612 permit 서명 오케스트레이션 |
+| `check-wallet` | 지갑 주소 및 상태 확인 |
+| `audit-log` | 감사 로그 조회 |
+
+## 패키지 내보내기
+
+| 서브경로 | 내용 | MCP 의존성 |
+|---------|------|:-:|
+| `@agenticvault/agentic-vault` | 코어 서명 (SigningProvider, EvmSignerAdapter, factory) | 없음 |
+| `@agenticvault/agentic-vault/protocols` | 프로토콜 디코더, dispatcher, PolicyEngine V2, workflows | 없음 |
+| `@agenticvault/agentic-vault/agentic` | MCP 서버, 감사 로그 기록 | 있음 |
+
+## 문서
+
+| 문서 | 설명 |
+|------|------|
+| [인터페이스 가이드](docs/guides/interfaces.md) | TypeScript, CLI, MCP, OpenClaw 사용법 |
+| [정책 레퍼런스](docs/reference/policy.md) | 정책 JSON 스키마, 필드, 예제 |
+| [AWS KMS 설정](docs/guides/aws-kms-setup.md) | 키 생성, IAM 정책, 인증 방법 |
+| [OpenClaw 플러그인](packages/openclaw-plugin/) | OpenClaw 플러그인 패키지 및 설정 |
+| [아키텍처 결정](docs/project/adrs/ADR-001-architecture-decisions.md) | 주요 설계 결정 ADR |
+| [기여 가이드](CONTRIBUTING.md) | 개발 워크플로 및 가이드라인 |
+
+## 로드맵
+
+- 추가 서명 프로바이더 (GCP KMS, HashiCorp Vault)
+- 추가 프로토콜 디코더 (Curve, Compound V3)
+- 멀티시그 지원
+- 원격 MCP 서버 모드 (HTTP 전송 + OAuth 2.1)
+
+## 기여하기
+
+개발 워크플로, 브랜치 명명 규칙, 커밋 규약은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.
+
+본 프로젝트는 [Contributor Covenant 행동 강령](CODE_OF_CONDUCT.md)을 따릅니다.
+
+## 라이선스
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,161 @@
+# Agentic Vault
+
+[![npm version](https://img.shields.io/npm/v/@agenticvault/agentic-vault)](https://www.npmjs.com/package/@agenticvault/agentic-vault)
+[![CI](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/agenticvault/agentic-vault/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+English | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
+
+Server-side EVM signing with AWS KMS and built-in DeFi protocol awareness. Expose your wallet to AI agents via MCP, CLI, or OpenClaw with deny-by-default policy enforcement and full audit logging.
+
+## Why Agentic Vault
+
+AI agents need to sign blockchain transactions, but giving them private keys is dangerous. Agentic Vault solves this by keeping keys in AWS KMS (HSM) and providing a policy engine that constrains what agents can sign. The agent sees high-level tools (`sign_swap`, `sign_permit`); the private key never leaves the hardware.
+
+## Features
+
+- **HSM-backed signing** -- private keys never leave AWS KMS; only digests are sent for signing
+- **DeFi protocol awareness** -- calldata decoding for ERC-20, Uniswap V3, and Aave V3 with protocol-specific policy rules
+- **Deny-by-default policy engine** -- chain, contract, selector, amount, deadline, and protocol-level constraints
+- **Multiple interfaces** -- use as a TypeScript library, CLI, MCP server, or OpenClaw plugin
+- **Audit logging** -- structured JSON audit trail for every signing operation (approved, denied, errored)
+- **EVM-native** -- built on [viem](https://viem.sh) with full EIP-712 typed data support
+
+## Quick Start
+
+```bash
+npm install @agenticvault/agentic-vault
+```
+
+```typescript
+import { createSigningProvider, EvmSignerAdapter } from '@agenticvault/agentic-vault';
+
+const provider = createSigningProvider({
+  provider: 'aws-kms',
+  keyId: 'arn:aws:kms:us-east-1:123456789:key/your-key-id',
+  region: 'us-east-1',
+});
+
+const signer = new EvmSignerAdapter(provider);
+const address = await signer.getAddress();
+```
+
+For a no-AWS quick test, use `dry-run` mode (decode + policy check without signing):
+
+```bash
+npx agentic-vault dry-run --chain-id 1 --to 0xa0b869... --data 0x095ea7b3...
+```
+
+See [AWS KMS Setup](docs/guides/aws-kms-setup.md) for key creation and IAM policy.
+
+## Interfaces
+
+| Interface | Use Case | AWS Required |
+|-----------|----------|:---:|
+| TypeScript Library | Embed signing in your app | Yes |
+| CLI | Command-line signing + dry-run | Partial |
+| MCP Server | Expose wallet to AI agents (Claude, etc.) | Yes |
+| OpenClaw Plugin | Use as OpenClaw agent tool | Yes |
+
+See [Interfaces Guide](docs/guides/interfaces.md) for usage examples and configuration.
+
+## Supported Protocols
+
+| Protocol | Actions | Decoder | Policy Evaluator |
+|----------|---------|:---:|:---:|
+| ERC-20 | `approve`, `transfer` | Yes | Yes (allowance cap, spender allowlist) |
+| Uniswap V3 | `exactInputSingle` | Yes | Yes (token pair, slippage, recipient) |
+| Aave V3 | `supply`, `borrow`, `repay`, `withdraw` | Yes | Yes (asset allowlist, interest rate mode) |
+
+Unknown calldata is always rejected (fail-closed). The dispatcher uses 2-stage resolution: contract address first, then selector-based fallback (e.g., ERC-20).
+
+## Configuration
+
+The policy engine uses a JSON configuration file. Without a policy file, all policy-guarded signing operations are denied (deny-by-default).
+
+See [Policy Reference](docs/reference/policy.md) for the full schema and examples, or start with [`policy.example.json`](policy.example.json).
+
+## Security Model
+
+### Trust Boundary
+
+```
+ AI Agent (Claude / MCP Client / OpenClaw)
+          |
+          | MCP Protocol / OpenClaw Plugin API
+          v
+ +------------------------------------+
+ |   Agentic Vault                    |
+ |  +-----------+ +--------+ +-----+ |
+ |  | Protocol  | | Policy | | Audit| |
+ |  | Dispatcher| | Engine | | Sink | |
+ |  +-----------+ +--------+ +-----+ |
+ |          |                         |
+ |  +--------------------+           |
+ |  | EvmSignerAdapter   |           |
+ |  +--------------------+           |
+ +-----------|------------------------+
+             | digest only
+             v
+ +------------------------------------+
+ |       AWS KMS (HSM)                |
+ |   Private key never leaves         |
+ +------------------------------------+
+```
+
+### Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| Key isolation | Private keys remain in the HSM; only 32-byte digests are sent for signing |
+| Deny by default | Policy engine rejects all requests unless explicitly allowed |
+| Fail-closed | Unknown calldata is always rejected; known protocol without evaluator is rejected |
+| Audit trail | Every operation is logged as structured JSON to stderr with caller tag |
+| Minimal surface | Raw signing tools (`sign_transaction`, `sign_typed_data`) are disabled by default |
+
+## Claude Code Plugin
+
+4 skills interact with the wallet through MCP tools only -- they never access keys directly.
+
+| Skill | Description |
+|-------|-------------|
+| `sign-swap` | Orchestrate a swap signing operation |
+| `sign-permit` | Orchestrate an EIP-2612 permit signing |
+| `check-wallet` | Check wallet address and health status |
+| `audit-log` | Query the audit log |
+
+## Package Exports
+
+| Subpath | Contents | MCP dependency |
+|---------|----------|:-:|
+| `@agenticvault/agentic-vault` | Core signing (SigningProvider, EvmSignerAdapter, factory) | No |
+| `@agenticvault/agentic-vault/protocols` | Protocol decoders, dispatcher, PolicyEngine V2, workflows | No |
+| `@agenticvault/agentic-vault/agentic` | MCP server, audit logger | Yes |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Interfaces Guide](docs/guides/interfaces.md) | TypeScript, CLI, MCP, and OpenClaw usage |
+| [Policy Reference](docs/reference/policy.md) | Policy JSON schema, fields, and examples |
+| [AWS KMS Setup](docs/guides/aws-kms-setup.md) | Key creation, IAM policy, authentication |
+| [OpenClaw Plugin](packages/openclaw-plugin/) | OpenClaw plugin package and configuration |
+| [Architecture Decisions](docs/project/adrs/ADR-001-architecture-decisions.md) | ADRs for key design choices |
+| [Contributing](CONTRIBUTING.md) | Development workflow and guidelines |
+
+## Roadmap
+
+- Additional signing providers (GCP KMS, HashiCorp Vault)
+- More protocol decoders (Curve, Compound V3)
+- Multi-signature support
+- Remote MCP server mode (HTTP transport with OAuth 2.1)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, branch naming, and commit conventions.
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE)