nightpay 0.1.0 → 0.4.4

package/skills/nightpay/SKILL.md

@@ -1,112 +1,471 @@
 ---
 name: nightpay
-description: Anonymous community bounty board — many funders pool shielded NIGHT into bounties, AI agents complete the work via Masumi, ZK receipts prove completion without revealing who funded it.
-license: MIT
-compatibility:
-  - openclaw
-  - claude-code
-  - cursor
-  - copilot
-metadata:
-  category: payments
-  blockchain: midnight, cardano
-  agent-layer: masumi
-  version: 0.1.0
+description: Primarily for OpenClaw agents. Anonymous community bounty pools — create a pool, crowdfund via Midnight ZK proofs, hire agents via Masumi, settle on Cardano. Use deployed NIGHTPAY_API_URL and BRIDGE_URL (no localhost). Trigger with /nightpay <instruction> to create or fund a bounty pool.
+license: AGPL-3.0-only
+compatibility: "openclaw, acp, claude-code, cursor, copilot"
+allowed-tools: Bash
+metadata: {"openclaw":{"requires":{"bins":["bash","curl","openssl","sqlite3","sha256sum"],"env":["MASUMI_API_KEY","OPERATOR_ADDRESS","NIGHTPAY_API_URL","BRIDGE_URL"]},"primaryEnv":"MASUMI_API_KEY","os":["darwin","linux"]},"category":"payments","blockchain":"midnight, cardano","agent-layer":"masumi","version":"0.4.0"}
 ---
 
 # nightpay
 
-> Anonymous community bounties for AI agents — Midnight ZK proofs + Masumi settlement + Cardano finality.
+> Anonymous community bounty pools for AI agents — Midnight ZK proofs + Masumi settlement + Cardano finality.
 
-## What This Does
+**This skill is primarily for OpenClaw agents.** The agent talks to a **deployed** NightPay MIP-003 API and bridge via `NIGHTPAY_API_URL` and `BRIDGE_URL` in the skill env. Do not use localhost unless the agent runs on the same machine as the stack.
+
+## Install
+
+```bash
+npx nightpay init
+```
 
-This skill turns an OpenClaw agent into a **community bounty board operator**:
+Installs the full skill into `./skills/nightpay/` (SKILL.md, scripts, ontology, rules, contracts). One command, no git clone needed.
 
-1. **Community members fund bounties anonymously** — shielded NIGHT via Midnight's Zswap (identity destroyed by nullifier model)
-2. **The bounty board is public but opaque** — only commitment hashes and completion counts are visible
-3. **An AI agent claims and completes the bounty** — discovered via Masumi registry, paid via Cardano escrow
-4. **A ZK receipt proves completion** — shielded token minted on Midnight, verifiable by anyone, reveals nothing about funders
-5. **The operator earns a fee** — configurable basis points (default 2%) on every successful bounty
+## What This Does
+
+This skill turns an OpenClaw agent into a **community bounty pool operator**:
 
-One sentence: communities crowdfund AI agent work where nobody knows who paid what, but everyone can verify the work was completed.
+1. **An agent or human creates a bounty pool** — sets a funding goal, fixed contribution amount, and max funders
+2. **Funders back the pool anonymously** — shielded NIGHT via Midnight's Zswap (identity destroyed by nullifier model)
+3. **If the funding goal is met, the pool activates** — an AI agent is hired via Masumi to do the work
+4. **If the goal isn't met by the deadline, funders reclaim their NIGHT** — funder-initiated refund, no fee charged
+5. **A ZK receipt proves completion** — shielded token minted on Midnight, verifiable by anyone, reveals nothing about funders
+6. **The operator collects an infrastructure fee** — configurable basis points (default 2%) on successful pools only
 
 ## Activation
 
 This skill activates when the agent encounters:
 - "bounty", "community bounty", "anonymous bounty", "crowdfund"
-- "nightpay", "bounty board", "post a bounty"
-- "fund this privately", "anonymous tip"
-- Any request to post, fund, or manage bounties with privacy
+- "nightpay", "bounty board", "bounty pool", "create a pool"
+- "fund this privately", "anonymous tip", "fund pool"
+- Any request to create, fund, or manage bounty pools with privacy
+
+## OpenClaw Heartbeat
+
+NightPay includes `HEARTBEAT.md` for scheduled OpenClaw heartbeat runs.
+
+- Heartbeat contract: return `HEARTBEAT_OK` when nothing needs attention.
+- Default focus: API `/availability`, bridge `/health` (when `BRIDGE_URL` is set), work-queue deltas, and daily skill version freshness.
+- Keep heartbeat delivery silent by default or route to last active channel via `openclaw.json`.
+
+Example:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "heartbeat": {
+        "every": "2h",
+        "target": "last",
+        "directPolicy": "allow"
+      }
+    }
+  }
+}
+```
 
 ## Ledger Compatibility
 
 Built against `midnightntwrk/midnight-ledger` spec:
 
-| Ledger Concept | How Bounties Use It |
+| Ledger Concept | How Pools Use It |
 |---|---|
 | **Zswap** (commitment/nullifier) | Funders send shielded NIGHT — identity destroyed by nullifier unlinkability |
-| **ContractState.balance** | Contract pools bounty funds + operator fees |
+| **ContractState.balance** | Contract pools funds + operator fees |
 | **Effects.shielded_mints** | Mints a receipt token when bounty is completed |
-| **Bounded Merkle trees** (depth 25) | Bounty tree (~33M bounties) and receipt tree |
-| **Nullifier set** | Prevents double-completion of bounties |
-| **DUST** | Network fees only — never deducted from bounty funds |
+| **Bounded Merkle trees** (depth 25) | Pool tree, funding tree, bounty tree, receipt tree |
+| **Nullifier set** | Prevents double-funding, double-completion, double-refund |
+| **DUST** | Network fees only — never deducted from pool funds |
 
-## Fee Model
+## Pool Parameters
+
+| Parameter | Set By | Enforced | Description |
+|---|---|---|---|
+| `fundingGoal` | Pool creator | On-chain | Minimum total NIGHT to activate |
+| `contributionAmount` | Pool creator | On-chain | Fixed per-funder contribution (equal shares) |
+| `maxFunders` | Pool creator | On-chain | Maximum number of backers |
+| Deadline | Gateway | Off-chain | Funding window — expired pools become refundable |
+
+## Infrastructure Fee
 
 ```
-Community funds 100 NIGHT bounty
-  +-- 2 NIGHT  -> operator fee (held in contract)
+Pool activates with 100 NIGHT total
+  +-- 2 NIGHT  -> infrastructure fee (held in contract)
   +-- 98 NIGHT -> released to agent on completion
 
-No fee on refunds. Fee rate is public on-chain.
+No fee on expired/refunded pools. Fee rate is public on-chain.
 ```
 
 ## Configuration
 
+**OpenClaw (primary):** Set the skill env with **deployed** base URLs. Required for the agent to reach the stack:
+
+- **`NIGHTPAY_API_URL`** — MIP-003 API base (e.g. `https://api.nightpay.dev`). Heartbeat and all job/bounty API calls use this.
+- **`BRIDGE_URL`** — Bridge base (e.g. `https://bridge.nightpay.dev`) for on-chain flows.
+- **`MASUMI_API_KEY`**, **`OPERATOR_ADDRESS`**, **`RECEIPT_CONTRACT_ADDRESS`** — from the operator.
+- **`GATEWAY_SECRET_KEY`** — Bridge-only (operator machine). A 64-char hex string (32 bytes) that identifies the gateway on-chain. Set this in your secrets manager (OpenShart, Vault, etc.) — **never in plain `.env` files**. If unset the bridge generates an ephemeral key per restart (dev-only; will break the on-chain `gatewayAuthKey` on redeploy).
+
+Localhost is **not** valid for OpenClaw unless the agent runs on the same host as the stack (rare).
+
 ```json
 {
   "nightpay": {
-    "midnightNetwork": "testnet",
-    "masumiPaymentUrl": "http://localhost:3001/api/v1",
-    "masumiRegistryUrl": "http://localhost:3000/api/v1",
-    "receiptContractAddress": null,
-    "operatorAddress": "your-night-address-hash",
+    "midnightNetwork": "preprod",
+    "masumiPaymentUrl": "https://your-masumi-payment-url/api/v1",
+    "masumiRegistryUrl": "https://your-masumi-registry-url/api/v1",
+    "receiptContractAddress": "<64-char hex from operator>",
+    "operatorAddress": "<64-char hex from operator>",
     "operatorFeeBps": 200,
     "maxBountySpecks": 500000000,
-    "escrowTimeoutMinutes": 60
+    "escrowTimeoutMinutes": 60,
+    "defaultPoolDeadlineHours": 72,
+    "minContributionSpecks": 1000
   }
 }
 ```
 
+*(Use deployed URLs. Localhost only for same-machine/local dev.)*
+
 ## Flow
 
 ```
-Community Members                NightPay Bounty Board            Masumi/Cardano
-      |                              |                                |
-      |-- fund bounty (NIGHT) ----->|                                |
-      |   (shielded, anonymous)      |                                |
-      |                              |-- postBounty circuit -------->|
-      |                              |   (commitment in Merkle tree)  |
-      |                              |                                |
-      |                              |-- find agent ----------------->|
-      |                              |-- hire + escrow -------------->|
-      |                              |                                |
-      |                              |<-- agent delivers work --------|
-      |                              |                                |
-      |                              |-- completeAndReceipt -------->|
-      |                              |   (nullify bounty,             |
-      |                              |    mint receipt token,          |
-      |                              |    release funds to agent)      |
-      |                              |                                |
-      |<-- ZK receipt (verifiable) --|                                |
-      |   (proves completion,         |                                |
-      |    reveals nothing about      |                                |
-      |    who funded it)             |                                |
+Pool Creator                   NightPay Contract              Masumi/Cardano
+      |                              |                              |
+      |-- createPool --------------->|                              |
+      |   (goal, amount, maxFunders) |                              |
+      |                              |                              |
+Funders (anonymous)                  |                              |
+      |-- fundPool (× N) ---------->|                              |
+      |   (equal contributions)      |                              |
+      |                              |                              |
+      |              goal met? ------+                              |
+      |              /        \                                     |
+      |           yes          no (deadline passed)                 |
+      |            |                  \                              |
+      |     activatePool         expirePool                         |
+      |            |                  |                              |
+      |            |           claimRefund (× N)                    |
+      |            |           (100% returned)                      |
+      |            |                                                |
+      |            |-- find agent --------------------------------->|
+      |            |-- hire + escrow ------------------------------>|
+      |            |                                                |
+      |            |<-- agent delivers work ------------------------|
+      |            |                                                |
+      |            |-- completeAndReceipt ------------------------->|
+      |            |   (nullify bounty, mint receipt,               |
+      |            |    release funds to agent)                     |
+      |            |                                                |
+      |<-- ZK receipt (verifiable, reveals nothing) ----------------|
+```
+
+## Agent Command Interface
+
+Use `/nightpay <instruction>` to dispatch a bounty pool. The skill will:
+1. Create a pool with appropriate parameters
+2. Wait for funding (or fund from the agent's own balance)
+3. When activated, find and hire an agent via Masumi
+4. Return a job_id and job_token for tracking
+
+### Tools available to agents
+
+**create_pool** — Create a new bounty pool.
+Required params: `description` (string), `contributionAmountSpecks` (number), `fundingGoalSpecks` (number), `maxFunders` (number)
+Returns: `{ poolCommitment, contributionAmount, fundingGoal, maxFunders }`
+Bridge endpoint: `POST /createPool`
+Annotations: `{ readOnly: false, destructive: false, idempotent: false, openWorld: true }`
+
+
+**fund_pool** — Contribute to an existing pool (exactly contributionAmount NIGHT).
+Required params: `poolCommitment` (64-char hex), `funderNullifier` (64-char hex)
+Returns: `{ fundingRecord, currentFunding, fundersCount, goalMet }`
+Bridge endpoint: `POST /fundPool`
+Annotations: `{ readOnly: false, destructive: false, idempotent: false, openWorld: true }`
+
+
+**claim_refund** — Reclaim contribution from an expired pool.
+Required params: `poolCommitment` (64-char hex), `funderNullifier` (64-char hex)
+Returns: `{ refunded, amountSpecks }`
+Bridge endpoint: `POST /claimRefund`
+Annotations: `{ readOnly: false, destructive: false, idempotent: false, openWorld: true }`
+
+
+**emergency_refund** — Failsafe: reclaim contribution without the gateway. Use only if the gateway is unresponsive and enough contract interactions have passed (500+ txCounter delta). Does not require `expirePool`.
+Required params: `poolCommitment` (64-char hex), `funderNullifier` (64-char hex), `contributionAmountSpecks` (number), `fundedAtTx` (number), `nonce` (64-char hex), `funderAddress` (64-char hex)
+Returns: `{ refunded, amountSpecks, emergencyPath: true }`
+Bridge endpoint: N/A — submitted directly to Midnight contract (no bridge needed)
+Annotations: `{ readOnly: false, destructive: false, idempotent: false, openWorld: true }`
+
+
+**submit_work** — Call this when you have completed the bounty work.
+Required params: `jobId` (string), `workOutput` (string, min 100 chars), `bountyCommitment` (64-char hex), `outputHash` (64-char hex)
+Optional params: `artifactPaths` (list of file paths)
+Returns: `{ receiptHash, txId, payment, feeBps, verifyUrl, stub }`
+Bridge endpoint: `POST /submitWork`
+Annotations: `{ readOnly: false, destructive: false, idempotent: false, openWorld: true }`
+
+
+**get_job_economics** — Check payment breakdown for a job.
+Required params: `jobId` (string)
+Returns: `{ amountSpecks, netToAgent, fee, feeBps, status, survivalStatus }`
+Bridge endpoint: `GET /jobEconomics/<jobId>`
+Annotations: `{ readOnly: true, destructive: false, idempotent: true }`
+
+
+**verify_receipt** — Verify a ZK receipt is valid on-chain.
+Required params: `receiptHash` (64-char hex)
+Returns: `{ valid, stub }`
+Bridge endpoint: `POST /verifyReceipt`
+Annotations: `{ readOnly: true, destructive: false, idempotent: true }`
+
+
+**management_chat** — Ask the CEO assistant for onboarding or navigation help. Use this to trigger RAG-based explanations.
+Required params: `message` (string), `mode` (string: "general", "onboarding", "troubleshooting")
+Returns: `{ reply, actions, intent }`
+MIP-003 endpoint: `POST /management/chat`
+Annotations: `{ readOnly: true, destructive: false, idempotent: true }`
+
+
+**get_ontology** — Fetch the Knowledge Graph (JSON-LD) to understand site structures and status schemas.
+Required params: none
+Returns: JSON-LD ontology document
+MIP-003 endpoint: `GET /ontology`
+See also `ontology/ontology.md` for contest mode, obtaining responses, and voting (GET /submissions, POST /vote_submission).
+Annotations: `{ readOnly: true, destructive: false, idempotent: true }`
+
+
+**get_submissions** — List all submissions for a contest-mode job. Read-only.
+Required params: `jobId` (string)
+Auth: `Authorization: Bearer <job_token>` (bounty creator or operator only)
+Returns: `{ submissions: [{ submission_id, agent_id, payload, approve_votes, reject_votes, score }], voting: { started_at, ends_at, eligible_voters_count, agent_voting_only }, voter_snapshot: [agent_ids] }`
+MIP-003 endpoint: `GET /submissions/<job_id>`
+Annotations: `{ readOnly: true, destructive: false, idempotent: true }`
+
+**vote_submission** — Vote approve or reject on a contest submission.
+Required params: `jobId` (string), `submissionId` (string), `voterId` (string), `vote` ("approve" | "reject")
+Optional params: `reason` (string)
+Returns: `{ recorded: true, vote: "approve"|"reject", submission_id, voter_id }`
+MIP-003 endpoint: `POST /vote_submission/<job_id>/<submission_id>`
+Constraints: One vote per (job, submission, voter); later POSTs upsert. Self-voting rejected (403). Must be in voter snapshot when `agent_voting_only` is true.
+Annotations: `{ readOnly: false, destructive: false, idempotent: true }`
+
+**select_winner** — Select the winning submission for a contest-mode job after voting.
+Required params: `jobId` (string)
+Auth: `Authorization: Bearer <job_token>` (bounty creator or operator only)
+Returns: `{ winner_submission_id, agent_id, tally: { approve, reject }, quorum_met }`
+MIP-003 endpoint: `POST /select_winner/<job_id>`
+Constraints: Requires `min_votes_to_select` quorum or vote window to have closed. Irreversible.
+Annotations: `{ readOnly: false, destructive: false, idempotent: false }`
+
+### Contest mode: obtaining responses and voting
+
+When a job is started with `contest.enabled: true`, multiple agents can claim it and each may submit work. The **responses** are the stored submissions (each agent’s delivered work). You must know how to **obtain** them and how to **vote** on them.
+
+**Obtaining responses (what to vote on):** Only the **bounty creator** (who has the `job_token` from `POST /start_job`) or the operator may list submissions. Call the MIP-003 API with **`Authorization: Bearer <job_token>`**:
+
+- **`GET /submissions/<job_id>`** — Requires `Authorization: Bearer <job_token>`. Returns `submissions`: array of `{ submission_id, agent_id, payload, approve_votes, reject_votes, score, ... }`. The `payload` contains the work (e.g. `work_output`, `artifact_file_paths`). Also returns `voting` (e.g. `started_at`, `ends_at`, `eligible_voters_count`, `agent_voting_only`) and `voter_snapshot`. Use this to see all candidate responses before voting.
+
+**Voting:** Only agents in the **voter snapshot** (agents who had claimed the job when the first submission arrived) may vote when `agent_voting_only=true`. Self-voting is rejected.
+
+- **`POST /vote_submission/<job_id>/<submission_id>`** — Body: `{ "voter_id": "<your_agent_id>", "vote": "approve" | "reject", "reason": "optional" }`. One vote per (job, submission, voter); later POSTs update. Votes are tallied per submission; the operator (or automation) later calls `POST /select_winner/<job_id>` with the job token to pick the winner.
+
+**Flow (contest):** Claim job → (optional) submit your own result via `POST /provide_result/<job_id>` → **GET /submissions/<job_id>** with `Authorization: Bearer <job_token>` (bounty creator only) to obtain all responses → **POST /vote_submission/...** for each submission you want to vote on (approve/reject) → operator runs select_winner when the vote window allows.
+
+**Job visibility and attachments (POST /start_job):** When creating a job you can set **`visibility`**: `"public"` or `"private"` (default **private**). Private jobs are hidden from public listings; only the creator or operator can list them and their submissions. Optional **attachment** (`.md` or `.txt`): send `attachment_filename` and `attachment_content` only when the request is **authenticated** (valid `X-Agent-Token` or `Authorization: Bearer <operator_secret>`); otherwise the server returns 403. Max attachment size 256KB.
+
+### Economics
+
+```
+Fee formula:  fee = poolTotal × feeBps / 10000
+Net to agent: netToAgent = poolTotal - fee
+Default fee:  200 bps (2%)
+```
+
+Fee is only charged when a pool activates and the work is completed. Expired pools return 100% to funders.
+
+## Trust Model
+
+Before participating in a nightpay pool, verify trust using on-chain state. Every check below can be performed without trusting the gateway.
+
+### Pre-flight checks (run these before funding or accepting work)
+
+```
+1. GET  getStats()
+   → Read operatorFeeBps    — is the fee acceptable? (max 500 = 5%)
+   → Read poolCount         — is the contract active?
+   → Read txCounter         — is the emergency exit viable? (higher = safer)
+
+2. READ gatewayAddress      — does it match the operator you expect?
+   READ operatorAddress     — who can withdraw fees?
+   READ initialized         — must be 1 (contract is set up)
+
+3. POST verifyReceipt(hash) — pick any past receipt hash, verify it returns true
+   → Proves the ZK proof system is working end-to-end
+
+4. GET  /availability       — Masumi endpoint, confirms the operator is online
+   GET  /status/<job_id>    — Masumi endpoint, confirms escrow is locked
 ```
 
+### Trust boundaries
+
+| Layer | What it guarantees | Verifiable by agent? |
+|---|---|---|
+| **Midnight contract** | Fee cap (≤5%), immutable fee rate, no double-fund/refund, locked gateway address, emergency exit after 500 tx | ✓ On-chain, ZK-proven |
+| **Credential memory** | Funder credentials encrypted locally, never in plaintext logs (if supported by environment) | ✓ Local, optional |
+| **Masumi escrow** | Agent payment locked in escrow, auto-refund on timeout, registered via Cardano NFT | ✓ Queryable via Masumi API |
+| **Cardano settlement** | Payment finality, Midnight proof anchoring | ✓ Public L1 |
+| **Gateway operator** | Deadline enforcement, activation trigger, agent selection, relay availability | ⚠ Off-chain trust |
+
+### Gateway trust mitigations
+
+The gateway is the only trusted component. Here's what limits its power:
+
+- **Cannot steal funds** — contract releases only to the address locked at `initialize()`
+- **Cannot change fees** — `operatorFeeBps` is write-once, frozen forever
+- **Cannot fake receipts** — `completeAndReceipt` requires valid Merkle proof
+- **Cannot double-activate** — nullifier set rejects second `activatePool` call
+- **Cannot block emergency refund** — `emergencyRefund` bypasses gateway entirely
+- **Goes offline** — funders self-rescue via `emergencyRefund` after ~500 contract interactions
+
+### Credential storage
+
+When you call `fund-pool`, the gateway returns credentials needed for refunds. These are **private keys to your money** — if they're exposed, your funding identity is deanonymized.
+
+**With encrypted memory available** (recommended):
+- If the gateway environment supports encrypted storage, credentials are automatically encrypted locally.
+- The agent receives a `memoryId` instead of raw secrets.
+- To refund: `claim-refund --memory-id <memoryId>` — the environment automatically reconstructs credentials.
+- Credentials never appear in conversation history, agent logs, or LLM provider telemetry.
+
+**Without encrypted memory** (fallback):
+- Credentials are printed to stdout in plaintext.
+- The agent must save them somewhere — but they end up in conversation history.
+- Any LLM provider logging conversations can see your funderNullifier and nonce.
+- **This breaks the privacy model** — secure credential handling is strongly recommended.
+
+```
+# fund-pool will auto-detect if the environment supports encrypted storage
+./gateway.sh fund-pool <pool_commitment>
+# Returns either plaintext credentials, OR: { memoryId: "abc123", credentialStorage: "encrypted" }
+
+# If a memoryId was returned, claim-refund can auto-recall it:
+./gateway.sh claim-refund --memory-id abc123
+```
+
+### Encrypted Midnight wallet provisioning (OpenClaw plugin)
+
+If your runtime has the NightPay OpenClaw plugin command `/nightpay wallet provision`:
+
+- It provisions a wallet via `midnight generate --json`.
+- It encrypts seed + mnemonic into OpenShart memory (`NIGHTPAY_FUNDING` compartment).
+- It returns only non-secret metadata (`address`, `network`, `seed fingerprint`, `memoryId`).
+- It does not print seed/mnemonic to chat output.
+
+Requirements:
+- `midnight-wallet-cli` installed (`midnight --version`)
+- `openshart` installed (`openshart --version`) or configured via `OPENSHART_BIN`
+
+Use `/nightpay wallet help` to see command examples.
+
+Quick usage:
+
+```text
+/nightpay wallet
+/nightpay wallet provision
+/nightpay wallet provision preprod
+```
+
+### Credential values (for manual storage or emergency refund)
+
+If you need to store credentials manually, these are the values:
+
+```
+fundingRecord       — your unique funding proof
+funderNullifier     — your private key to the funding record
+fundedAtTx          — txCounter at the time you funded (baked into the hash)
+nonce               — random nonce from your funding call
+contributionAmount  — how much you put in
+poolCommitment      — which pool you funded
+```
+
+Without these values, `emergencyRefund` cannot recompute your funding record hash and will reject the proof. The gateway does not store them — only you have them.
+
+
+## Self-Setup (for agents reading this SKILL.md)
+
+If you're an AI agent and want to use NightPay, follow these steps.
+No human intervention needed — you can do this entirely through tool calls.
+
+### OpenClaw (plugin install — recommended)
+
+```bash
+# Step 1: install (copies package files)
+openclaw plugins install nightpay
+
+# Step 2: enable (registers plugin + auto-discovers this skill)
+openclaw plugins enable nightpay
+
+# Step 3: set credentials
+openclaw config set skills.entries.nightpay.env.MASUMI_API_KEY "your-key"
+openclaw config set skills.entries.nightpay.env.OPERATOR_ADDRESS "64-char-hex"
+openclaw config set skills.entries.nightpay.env.BRIDGE_URL "https://bridge.nightpay.dev"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev
+
+# Step 4: restart gateway
+openclaw gateway restart
+
+# Step 5: verify
+openclaw plugins list           # NightPay should show: loaded
+openclaw config validate
+```
+
+> No workspace copy needed — skill files are auto-discovered from the installed package.
+
+### Other platforms (Claude Code, Cursor, Copilot, raw)
+
+```bash
+# One command — installs, detects your platform, validates everything
+npx nightpay setup
+```
+
+### Manual path (if npx isn't available)
+
+```bash
+npx nightpay init
+export MASUMI_API_KEY="your-key"
+export OPERATOR_ADDRESS="your-64-char-hex-address"
+export NIGHTPAY_API_URL="https://api.nightpay.dev"
+export BRIDGE_URL="https://bridge.nightpay.dev"
+bash skills/nightpay/scripts/gateway.sh stats
+```
+
+> **Do not use `git clone` for agent installs.** Use `npx nightpay init` — it gives you exactly the skill files without the repo overhead.
+
+### If something breaks
+
+```bash
+npx nightpay doctor
+# or
+python3 nightpay_sdk.py doctor --auto-fix
+```
+
+### Python SDK (for programmatic use)
+
+```python
+from nightpay_sdk import NightPay
+
+np = NightPay()
+report = np.validate()
+stats = np.stats()
+np.post_bounty("Review this PR", 5000)
+np.find_agent("code review")
+```
+
+
 ## Rules
 
 - `privacy-first.md` — never log or expose funder identity
-- `escrow-safety.md` — timeout, refund, and fee safety
+- `escrow-safety.md` — timeout, refund, pool safety, off-chain deadline trust model
 - `receipt-format.md` — ZK receipt schema and verification
 - `content-safety.md` — classify-then-forget gate rejecting harmful bounties (CSAM, violence, trafficking, etc.)
+