safehands-pharos 1.2.5 → 1.3.0

package/docs/reports/live_verification_report.md

@@ -0,0 +1,147 @@
+# SafeHands-Pharos — Live Docs & Testnet Verification Report
+
+> **Date:** 2026-06-12  
+> **Version:** 1.2.0  
+
+---
+
+## 1. Files Changed
+
+| File | Change |
+|------|--------|
+| `src/lib/constants.ts` | USDT, WBTC, WETH, WPHRS verification upgraded from `PROJECT_CONFIGURED` → `DOCS_VERIFIED` after confirming against official Pharos Token Registry |
+| `src/tools/tokenRegistryStatus.ts` | Handler now reads `verificationStatus` from registry entries directly |
+| `src/lib/testRpcLive.ts` | **NEW** — Live RPC verification with structured output |
+| `src/lib/testLiveSafehands.ts` | **NEW** — 7-point live CLI verification |
+| `src/lib/testX402Live.ts` | **NEW** — x402 behavior verification (local server) |
+| `src/lib/testDodoLive.ts` | **NEW** — DODO/FaroSwap live verification with clean skip |
+| `package.json` | Added 4 new npm scripts |
+| `README.md` | Added Real Testnet Verification section + updated Tests section |
+| `OFFICIAL_DOCS_ALIGNMENT_REPORT.md` | **NEW** — Full docs alignment table |
+
+## 2. Official Docs Checked
+
+| Source | Fetched |
+|--------|---------|
+| https://docs.pharos.xyz/getting-started/network/atlantic-testnet | ✅ |
+| https://docs.pharos.xyz/getting-started/token-registry | ✅ |
+| https://docs.pharos.xyz/getting-started/canonical-contracts | ✅ |
+| https://docs.pharos.xyz/developer-guide/x402 | ✅ |
+| https://docs.pharos.xyz/tooling-and-infrastructure/pharos-skill-engine-guide | ✅ |
+| https://developers.circle.com/stablecoins/usdc-contract-addresses | ✅ |
+| https://docs.faroswap.xyz/en/introduction | ❌ HTTP 307 |
+
+## 3. Docs Alignment Summary
+
+- **13 DOCS_VERIFIED** — Environment, Chain ID, RPC, Explorer, Native Token, USDC, USDT, WBTC, WETH, WPHRS, x402 behavior, Skill Engine structure, Testnet scope
+- **1 DOCS_DEMO_NON_OFFICIAL** — x402 demo token
+- **4 PROJECT_CONFIGURED** — DODO Approve, DODO Route Proxy, Position Manager, RiskRegistry
+- **0 CONFLICT**
+
+## 4. Real RPC Test Result
+
+```
+npm run test:rpc:live
+```
+
+| Check | Result |
+|-------|--------|
+| RPC reachable | ✅ yes |
+| Chain ID | 688689 ✅ match |
+| Latest block | 24023029 |
+| Wallet balance | SKIPPED_NO_WALLET_ADDRESS |
+| **Status** | **PASS** |
+
+## 5. Real SafeHands CLI Check Result
+
+```
+npm run test:live:safehands
+```
+
+| # | Check | Result |
+|---|-------|--------|
+| 1 | wallet_health_no_wallet | ✅ PASS |
+| 2 | token_registry_canonical_usdc (DOCS_VERIFIED) | ✅ PASS |
+| 3 | token_registry_x402_demo (DOCS_DEMO_NON_OFFICIAL) | ✅ PASS |
+| 4 | token_registry_usdt_docs_verified | ✅ PASS |
+| 5 | preflight_block_unlimited_approval | ✅ PASS |
+| 6 | preflight_block_mainnet | ✅ PASS |
+| 7 | preflight_allow_testnet | ✅ PASS |
+| **Status** | **7/7 PASS** |
+
+## 6. Real x402 Behavior Result
+
+```
+npm run test:x402:live
+```
+
+**Label: LOCAL_X402_SERVER_DOCS_BEHAVIOR_TEST**
+
+| # | Check | Result |
+|---|-------|--------|
+| 1 | /supported without private key | ✅ 200 OK |
+| 2 | /health without private key | ✅ 200 OK |
+| 3 | Paid endpoint without config → structured 503 | ✅ |
+| 4 | No crash on missing config | ✅ |
+| 5 | x402 token matches docs (USDC on eip155:688689) | ✅ |
+| **Status** | **5/5 PASS** |
+
+## 7. DODO/FaroSwap Real Verification Result
+
+```
+npm run test:dodo:live
+```
+
+| # | Check | Result |
+|---|-------|--------|
+| 1 | DODO API route check | ⏭️ SKIPPED_MISSING_DODO_API_KEY |
+| 2 | DODO Approve address verification | ✅ PROJECT_CONFIGURED |
+| 3 | DODO Route Proxy verification | ✅ PROJECT_CONFIGURED |
+| **Status** | **2/3 PASS, 1 SKIPPED** |
+
+## 8. Address Metadata Changes
+
+| Token | Before | After | Source |
+|-------|--------|-------|--------|
+| USDC | DOCS_VERIFIED | DOCS_VERIFIED | Token Registry + Circle |
+| TUSDC | DOCS_DEMO_NON_OFFICIAL | DOCS_DEMO_NON_OFFICIAL | x402 docs |
+| USDT | (no verificationStatus) | **DOCS_VERIFIED** | Token Registry |
+| WBTC | (no verificationStatus) | **DOCS_VERIFIED** | Token Registry |
+| WETH | (no verificationStatus) | **DOCS_VERIFIED** | Token Registry |
+| WPHRS | (no verificationStatus) | **DOCS_VERIFIED** | Token Registry |
+| DODO addresses | PROJECT_CONFIGURED | PROJECT_CONFIGURED | FaroSwap docs unavailable |
+| RiskRegistry | PROJECT_CONFIGURED | PROJECT_CONFIGURED | Not in canonical contracts |
+
+## 9. Commands Run and Results
+
+| Command | Exit Code |
+|---------|-----------|
+| `npm run build` | 0 ✅ |
+| `npx tsc -p tsconfig.all.json --pretty false` | 0 ✅ |
+| `npm audit --omit=dev --audit-level=high` | 0 ✅ (0 vulnerabilities) |
+| `npm pack --dry-run` | 0 ✅ (210 files, 128.4 kB) |
+| `npm run test:all` | 0 ✅ (37/37 passed) |
+| `npm run demo` | 0 ✅ |
+| `npm run test:rpc:live` | 0 ✅ (PASS) |
+| `npm run test:live:safehands` | 0 ✅ (7/7) |
+| `npm run test:x402:live` | 0 ✅ (5/5) |
+| `npm run test:dodo:live` | 0 ✅ (2/3, 1 skipped) |
+
+## 10. Remaining Docs-Unverified Values
+
+| Value | Status | Reason |
+|-------|--------|--------|
+| DODO Approve Address `0x4Cf3…` | PROJECT_CONFIGURED | FaroSwap docs HTTP 307 |
+| DODO Route Proxy `0x8198…` | PROJECT_CONFIGURED | FaroSwap docs HTTP 307 |
+| Position Manager `0x1c43…` | PROJECT_CONFIGURED | FaroSwap docs HTTP 307 |
+| RiskRegistry `0x71fc…` | PROJECT_CONFIGURED | Custom project deployment |
+
+## 11. Real Transactions Broadcast
+
+**None.** Zero transactions were signed or broadcast during this verification pass. All tests are read-only RPC calls, deterministic preflight policy checks, or local server behavior tests.
+
+## 12. Final Status
+
+**Status: Ready for DoraHacks Phase 1 submission with real docs/live verification**
+
+All 13 docs-verifiable values match official Pharos documentation. Live RPC confirms chain ID 688689 and block production. 37 smoke tests + 7 CLI checks + 5 x402 checks pass. DODO skips cleanly. Zero vulnerabilities. No overclaimed addresses.

package/docs/reports/pharos_skill_engine_alignment_report.md

@@ -0,0 +1,85 @@
+# SafeHands-Pharos — Official Pharos Skill Engine Alignment Report
+
+> **Date:** 2026-06-12  
+> **Version:** 1.2.0  
+
+---
+
+## 1. Files Changed
+| File | Change |
+|------|--------|
+| `src/lib/constants.ts` | Upgraded `0xE0BE08c7...` to primary `USDC_ADDRESS`, relabeled `0xcfC8330f...` as `CIRCLE_USDC_ADDRESS`. |
+| `src/tools/tokenRegistryStatus.ts` | Rewrote classification to output `SKILL_ENGINE_CANONICAL_TOKEN` or `ALTERNATE_SOURCE_TOKEN` based on new registry metadata. |
+| `skill/SKILL.md` | **NEW** — Created official SKILL.md file adhering to Pharos Skill Engine formatting standards with YAML frontmatter. |
+| `skill/references/safehands.md` | **NEW** — Copied over the CLI reference guide into the required skill package structure. |
+| `skill/assets/safehands/*` | **NEW** — Policy defaults and example actions migrated. Example actions now strictly use `0xE0BE08c7...`. |
+| `src/lib/testTools.ts` | Added 6 new smoke tests covering the `skill/` package structure and exact token metadata values. |
+| `src/lib/testLiveSafehands.ts` | Updated live CLI checks to verify new USDC classification. |
+| `src/index.ts` | Fixed the `--demo` exit path bug to ensure test pipelines exit cleanly without starting the MCP server inadvertently. |
+| `package.json` | Appended the `skill` directory and new alignment reports to the npm `files` array for proper packaging. |
+| `README.md` | Added the "Official Pharos Skill Engine Alignment" section and updated token addresses in the context table. |
+| `OFFICIAL_DOCS_ALIGNMENT_REPORT.md` | Updated docs alignment tables and summaries to reflect the Skill Engine metadata. |
+
+## 2. Official Pharos Skill Engine Zip Findings
+Inspection of `pharos-skill-engine-0.1.0.zip` revealed:
+- **Structure:** `SKILL.md`, `references/`, and `assets/`.
+- **Token Metadata:** The file `assets/tokens.json` officially defines the Atlantic Testnet USDC address as **`0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8`**.
+- **Role:** The official skill handles execution (`cast`/`forge`), confirming SafeHands' positioning as a complementary preflight guardrail rather than an execution wrapper.
+
+## 3. Token Metadata Changes
+- **Primary USDC (`0xE0BE08c7...`)**: The official Pharos Skill Engine token (previously treated as a docs demo token) has been promoted to the canonical testnet USDC default.
+  - **Status:** `SKILL_ENGINE_CANONICAL_TOKEN`
+  - **Verification:** `DOCS_VERIFIED_FROM_PHAROS_SKILL_ENGINE`
+- **Alternate USDC (`0xcfC8330f...`)**: The USDC address sourced from Circle's official documentation is preserved but deprioritized to avoid conflicts.
+  - **Status:** `ALTERNATE_SOURCE_TOKEN`
+  - **Verification:** `CIRCLE_REFERENCED_USDC`
+
+Both tokens are handled gracefully by `token_registry_status`, ensuring the agent receives factual provenance.
+
+## 4. Skill Package Structure Created
+The `skill/` directory was generated successfully, mirroring the PiggyBank template layout:
+```text
+skill/
+├── SKILL.md (with YAML frontmatter, Capability Index, Pre-checks)
+├── references/
+│   └── safehands.md
+└── assets/
+    └── safehands/
+        ├── policy-defaults.json
+        └── example-actions.json
+```
+The package allows an AI agent to dynamically invoke `safehands_preflight_check` using official Pharos patterns.
+
+## 5. Tests Added/Updated
+- **`skill_package_skill_md_exists`**: Confirms presence of `SKILL.md`.
+- **`skill_package_yaml_frontmatter`**: Ensures exact match for `name: safehands-pharos-guard` in frontmatter.
+- **`skill_package_references_exist`**: Verifies presence of the `references/safehands.md` guide.
+- **`skill_package_assets_exist`**: Verifies presence of the JSON assets.
+- **`skill_package_example_uses_skill_engine_usdc`**: Blocks regressions to the `0xcfC8...` address within example configs.
+- **`token_registry_circle_usdc_alternate`**: Ensures `0xcfC8...` retains its explicit alternate status.
+- **`demo_runs_or_fails_gracefully`**: Fixed to properly handle the exit code when the demo runs successfully.
+
+## 6. Commands Run and Results
+| Command | Result |
+|---------|--------|
+| `npm ci` | 0 ✅ |
+| `npm run build` | 0 ✅ |
+| `npx tsc -p tsconfig.all.json --pretty false` | 0 ✅ |
+| `npm run test:all` | 0 ✅ (43/43 smoke tests passed) |
+| `npm audit --omit=dev --audit-level=high` | 0 ✅ (0 vulnerabilities) |
+| `npm run demo` | 0 ✅ (Clean exit, output identical to previous demo) |
+
+## 7. npm pack Safety Result
+```bash
+npm pack --dry-run
+```
+- Includes the new `skill/` directory and `OFFICIAL_DOCS_ALIGNMENT_REPORT.md`.
+- **Secret scan**: Passed (0 exposed variables found).
+- **Total files:** 215 files (135.9 kB).
+
+## 8. Remaining Risks/TODOs
+- **DODO / FaroSwap Router Addresses:** Currently `PROJECT_CONFIGURED`. This remains unverified due to the FaroSwap documentation returning an HTTP 307 redirect. This cannot be fixed without live docs.
+- **RiskRegistry Contract:** A project-deployed contract (`PROJECT_CONFIGURED`) used to simulate risk scores. Expected hackathon behavior.
+
+## 9. Final Status
+**Status: Ready for DoraHacks Phase 1 submission with official Pharos Skill Engine alignment**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safehands-pharos",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "Pharos Skill Engine-compatible transaction safety firewall for AI agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -18,6 +18,8 @@
     "skill",
     "README.md",
     ".env.example",
+    "docs",
+    ".agents",
     "LICENSE"
   ],
   "scripts": {

package/skill/SKILL.md

@@ -1,127 +1,133 @@
----
-name: safehands-pharos-guard
-description: >
-  REQUIRED before any Pharos AI agent write action involving token approvals, payments, swaps,
-  x402 paid requests, or custom contract calls. SafeHands runs policy-based preflight checks
-  and returns ALLOW, WARN, BLOCK, REQUIRE_CONFIRMATION, REQUIRE_FUNDING, or REQUIRE_TOKEN_REVIEW
-  before execution. Use this skill as a safety firewall before invoking Pharos Skill Engine
-  write operations.
-version: 1.2.0
-requires:
-  anyBins:
-  - npx
----
-
-# SafeHands Pharos Guard
-
-Transaction Safety Firewall / Guardrail Skill for Pharos AI agents. SafeHands checks whether an action is safe before execution on Pharos Atlantic Testnet.
-
-SafeHands complements the official `pharos-skill-engine`. It is not a replacement. The official Skill Engine provides general on-chain capabilities (queries, transactions, contract deployments). SafeHands answers: **"Is this action safe to execute?"**
-
-```text
-User intent
-→ SafeHands preflight (ALLOW / WARN / BLOCK / REQUIRE_CONFIRMATION)
-→ Pharos Skill Engine or MCP execution (only if safe)
-→ SafeHands risk report
-```
-
-## Prerequisites
-
-1. **Install SafeHands** (via npx, no global install required):
-   ```bash
-   npx safehands-pharos --help
-   ```
-   If `npx safehands-pharos` is not available, install globally:
-   ```bash
-   npm install -g safehands-pharos
-   ```
-
-2. **No private key required** for safety checks. Private keys are only needed for write execution (which is disabled by default).
-
-## Network Configuration
-
-SafeHands reads network configuration from its built-in constants. Default network: **Atlantic Testnet**.
-
-| Field | Value |
-|-------|-------|
-| Environment | `atlantic-testnet` |
-| Chain ID | `688689` |
-| RPC URL | `https://atlantic.dplabs-internal.com` |
-| Native Token | `PHRS` |
-| Primary USDC | `0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8` |
-| Mainnet | `false` |
-
-Token addresses are sourced from the official Pharos Skill Engine `assets/tokens.json`.
-
-## Safety Model
-
-SafeHands enforces these guardrails by default:
-
-- **Block** mainnet actions
-- **Block** chain ID mismatch
-- **Block** unlimited token approvals
-- **Block** SSRF-sensitive x402 URLs (localhost, private IPs)
-- **Block** payments above configured limits
-- **Block** x402 payments above `MAX_X402_PAYMENT_USDC`
-- **Warn** when token is custom or non-registry
-- **Warn** when token security provider is unavailable
-- **Require confirmation** for medium-risk actions
-- **Allow** low-risk Pharos Atlantic Testnet actions
-
-Write tools are disabled by default (`WRITE_TOOLS_ENABLED=false`).
-
-## Capability Index
-
-Load the corresponding reference file based on user needs to get full command templates.
-
-| User Need | Capability | Detailed Instructions |
-|-----------|------------|----------------------|
-| Check whether an on-chain action is safe before execution | SafeHands Preflight Check | → `references/safehands.md#safehands-preflight-check` |
-| Check whether an x402 paid endpoint is safe to pay | SafeHands x402 Preflight | → `references/safehands.md#safehands-x402-preflight` |
-| Check whether an agent wallet is ready to act | SafeHands Wallet Health | → `references/safehands.md#safehands-wallet-health` |
-| Check whether a token address is canonical or custom | Token Registry Status | → `references/safehands.md#token-registry-status` |
-| Explain why an action was blocked or warned | Explain Risk | → `references/safehands.md#explain-risk` |
-| Generate a human-readable safety report | SafeHands Risk Report | → `references/safehands.md#safehands-risk-report` |
-
-## General Error Handling
-
-Before executing commands, the Agent should perform pre-checks; when commands fail, provide user-friendly error messages based on the structured JSON output.
-
-| Error Scenario | Error Code | Handling |
-|---------------|-----------|----------|
-| Invalid address format | `INVALID_TOKEN_ADDRESS` / `INVALID_WALLET_ADDRESS` | Prompt to check address format (0x + 40 hex characters) |
-| Write tools disabled | `WRITE_TOOLS_DISABLED` | Inform user that write tools are disabled by default |
-| SSRF blocked URL | `SSRF_BLOCKED` | Do not fetch or pay; inform user the URL is blocked |
-| Mainnet action attempted | `MAINNET_NOT_SUPPORTED` | Do not execute; SafeHands is testnet-only |
-| Chain ID mismatch | `CHAIN_ID_MISMATCH` | Switch to Pharos Atlantic Testnet (688689) |
-| Signer not available | `NO_SIGNER_AVAILABLE` | Ask user to configure wallet mode |
-| Invalid input JSON | `INVALID_INPUT_JSON` | Fix the JSON input and retry |
-| Policy blocked | `POLICY_BLOCKED` | Explain reasons to the user; do not execute |
-
-See `references/safehands.md` for detailed error handling tables for each operation.
-
-## Security Reminders
-
-- **No private key required** for read-only safety checks (preflight, token registry, wallet health, explain risk).
-- **Write tools are disabled by default.** Set `WRITE_TOOLS_ENABLED=true` only for trusted testnet execution.
-- **Private keys are never returned** in CLI or MCP responses.
-- **Unlimited approvals are blocked** unless explicitly allowed via `ALLOW_UNLIMITED_APPROVAL=true`.
-- **SSRF protection** blocks localhost and private IP x402 URLs by default.
-- **Testnet only.** SafeHands is not audited for mainnet production use.
-
-## Write Operation Pre-checks (Required for All Write Operations)
-
-For all write operations, the Agent must run SafeHands preflight first:
-
-```bash
-npx safehands-pharos skill safehands_preflight_check --input-json '<action_json>'
-```
-
-1. If `decision` is `BLOCK`, **stop execution**.
-2. If `decision` is `WARN`, explain the risk and ask for user confirmation.
-3. If `decision` is `REQUIRE_CONFIRMATION`, ask for explicit user approval.
-4. If `decision` is `REQUIRE_FUNDING`, ask user to fund the wallet.
-5. If `decision` is `REQUIRE_TOKEN_REVIEW`, ask user to verify the token contract.
-6. If `decision` is `ALLOW`, proceed with the Pharos Skill Engine write operation.
-
-For full command templates, parameters, output parsing, and error handling, see [`references/safehands.md`](references/safehands.md).
+---
+name: safehands-pharos-guard
+description: >
+  REQUIRED before any Pharos AI agent write action involving token approvals, payments, swaps,
+  x402 paid requests, or custom contract calls. SafeHands runs policy-based preflight checks
+  and returns ALLOW, WARN, BLOCK, REQUIRE_CONFIRMATION, REQUIRE_FUNDING, or REQUIRE_TOKEN_REVIEW
+  before execution. Use this skill as a safety firewall before invoking Pharos Skill Engine
+  write operations.
+version: 1.3.0
+requires:
+  anyBins:
+  - npx
+---
+
+# SafeHands Pharos Guard
+
+Transaction Safety Firewall / Guardrail Skill for Pharos AI agents. SafeHands checks whether an action is safe before execution on Pharos Atlantic Testnet.
+
+SafeHands complements the official `pharos-skill-engine`. It is not a replacement. The official Skill Engine provides general on-chain capabilities (queries, transactions, contract deployments). SafeHands answers: **"Is this action safe to execute?"**
+
+```text
+User intent
+→ SafeHands preflight (ALLOW / WARN / BLOCK / REQUIRE_CONFIRMATION)
+→ Pharos Skill Engine or MCP execution (only if safe)
+→ SafeHands risk report
+```
+
+## Real-World Use Cases
+
+1. **Anti-Drain Protection:** An AI Agent is tricked by a prompt injection to approve `999999 USDC` to a hacker's contract. SafeHands intercepts the action, detects an unlimited approval, and returns `BLOCK`.
+2. **SSRF Payment Prevention:** A malicious website asks the AI Agent to pay `0.001 USDC` to an x402 URL pointing to `http://localhost:8080/admin`. SafeHands detects the private IP address, blocks the HTTP request, and returns `BLOCK` preventing server compromise.
+3. **Fake Token Detection:** An AI Agent decides to buy a token named "Official Pharos Coin" on the testnet. SafeHands checks the `token_registry_status`, realizes it's a fake token not listed in the official docs, and returns `WARN` to ask the human for confirmation before swapping.
+
+## Prerequisites
+
+1. **Install SafeHands** (via npx, no global install required):
+   ```bash
+   npx safehands-pharos --help
+   ```
+   If `npx safehands-pharos` is not available, install globally:
+   ```bash
+   npm install -g safehands-pharos
+   ```
+
+2. **No private key required** for safety checks. Private keys are only needed for write execution (which is disabled by default).
+
+## Network Configuration
+
+SafeHands reads network configuration from its built-in constants. Default network: **Atlantic Testnet**.
+
+| Field | Value |
+|-------|-------|
+| Environment | `atlantic-testnet` |
+| Chain ID | `688689` |
+| RPC URL | `https://atlantic.dplabs-internal.com` |
+| Native Token | `PHRS` |
+| Primary USDC | `0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8` |
+| Mainnet | `false` |
+
+Token addresses are sourced from the official Pharos Skill Engine `assets/tokens.json`.
+
+## Safety Model
+
+SafeHands enforces these guardrails by default:
+
+- **Block** mainnet actions
+- **Block** chain ID mismatch
+- **Block** unlimited token approvals
+- **Block** SSRF-sensitive x402 URLs (localhost, private IPs)
+- **Block** payments above configured limits
+- **Block** x402 payments above `MAX_X402_PAYMENT_USDC`
+- **Warn** when token is custom or non-registry
+- **Warn** when token security provider is unavailable
+- **Require confirmation** for medium-risk actions
+- **Allow** low-risk Pharos Atlantic Testnet actions
+
+Write tools are disabled by default (`WRITE_TOOLS_ENABLED=false`).
+
+## Capability Index
+
+Load the corresponding reference file based on user needs to get full command templates.
+
+| User Need | Capability | Detailed Instructions |
+|-----------|------------|----------------------|
+| Check whether an on-chain action is safe before execution | SafeHands Preflight Check | → `references/safehands.md#safehands-preflight-check` |
+| Check whether an x402 paid endpoint is safe to pay | SafeHands x402 Preflight | → `references/safehands.md#safehands-x402-preflight` |
+| Check whether an agent wallet is ready to act | SafeHands Wallet Health | → `references/safehands.md#safehands-wallet-health` |
+| Check whether a token address is canonical or custom | Token Registry Status | → `references/safehands.md#token-registry-status` |
+| Explain why an action was blocked or warned | Explain Risk | → `references/safehands.md#explain-risk` |
+| Generate a human-readable safety report | SafeHands Risk Report | → `references/safehands.md#safehands-risk-report` |
+
+## General Error Handling
+
+Before executing commands, the Agent should perform pre-checks; when commands fail, provide user-friendly error messages based on the structured JSON output.
+
+| Error Scenario | Error Code | Handling |
+|---------------|-----------|----------|
+| Invalid address format | `INVALID_TOKEN_ADDRESS` / `INVALID_WALLET_ADDRESS` | Prompt to check address format (0x + 40 hex characters) |
+| Write tools disabled | `WRITE_TOOLS_DISABLED` | Inform user that write tools are disabled by default |
+| SSRF blocked URL | `SSRF_BLOCKED` | Do not fetch or pay; inform user the URL is blocked |
+| Mainnet action attempted | `MAINNET_NOT_SUPPORTED` | Do not execute; SafeHands is testnet-only |
+| Chain ID mismatch | `CHAIN_ID_MISMATCH` | Switch to Pharos Atlantic Testnet (688689) |
+| Signer not available | `NO_SIGNER_AVAILABLE` | Ask user to configure wallet mode |
+| Invalid input JSON | `INVALID_INPUT_JSON` | Fix the JSON input and retry |
+| Policy blocked | `POLICY_BLOCKED` | Explain reasons to the user; do not execute |
+
+See `references/safehands.md` for detailed error handling tables for each operation.
+
+## Security Reminders
+
+- **No private key required** for read-only safety checks (preflight, token registry, wallet health, explain risk).
+- **Write tools are disabled by default.** Set `WRITE_TOOLS_ENABLED=true` only for trusted testnet execution.
+- **Private keys are never returned** in CLI or MCP responses.
+- **Unlimited approvals are blocked** unless explicitly allowed via `ALLOW_UNLIMITED_APPROVAL=true`.
+- **SSRF protection** blocks localhost and private IP x402 URLs by default.
+- **Testnet only.** SafeHands is not audited for mainnet production use.
+
+## Write Operation Pre-checks (Required for All Write Operations)
+
+For all write operations, the Agent must run SafeHands preflight first:
+
+```bash
+npx safehands-pharos skill safehands_preflight_check --input-json '<action_json>'
+```
+
+1. If `decision` is `BLOCK`, **stop execution**.
+2. If `decision` is `WARN`, explain the risk and ask for user confirmation.
+3. If `decision` is `REQUIRE_CONFIRMATION`, ask for explicit user approval.
+4. If `decision` is `REQUIRE_FUNDING`, ask user to fund the wallet.
+5. If `decision` is `REQUIRE_TOKEN_REVIEW`, ask user to verify the token contract.
+6. If `decision` is `ALLOW`, proceed with the Pharos Skill Engine write operation.
+
+For full command templates, parameters, output parsing, and error handling, see [`references/safehands.md`](references/safehands.md).