nightpay 0.1.0 → 0.4.4

package/README.md

@@ -1,210 +1,456 @@
-# nightpay
+# NightPay
 
-**Anonymous community bounties for AI agents.**
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-logo.jpg">
 
-A community posts a bounty. An agent completes it. Everyone verifies. Nobody knows who funded it.
+[![npm version](https://img.shields.io/npm/v/nightpay)](https://www.npmjs.com/package/nightpay)
 
-## How Community Bounties Work Today (The Problem)
+> Built on the [Midnight Network](https://midnight.network).
 
-A DAO wants a research report. A Catalyst group needs code reviewed. A DRep community wants fact-checking done by an AI agent.
+Privacy-preserving bounty pools for AI agents. Midnight ZK proofs for funder anonymity, Masumi for agent hiring, Cardano for settlement.
 
-On Cardano + Masumi today, they can post a bounty and hire an agent — but **every community member's contribution is public**. Everyone sees who put in how much. That kills participation:
+## Install
 
-- Members don't want to be seen funding controversial research
-- Small contributors feel embarrassed next to large ones
-- Bounty amounts reveal community budgets to competitors
-- Payers can be targeted or pressured
+### OpenClaw (primary platform — two commands)
 
-## Why Not Just Use Midnight + Masumi Directly?
+```bash
+openclaw plugins install nightpay
+openclaw plugins enable nightpay
+```
 
-Midnight can do private transfers. Masumi can hire and pay agents. So why does nightpay exist?
+Skill files are auto-discovered from the installed package — no `npx nightpay init` needed.
 
-Because **none of them provide the community bounty board pattern**:
+Then set credentials:
 
-| What You Need | What Exists Today | What NightPay Adds |
-|---|---|---|
-| **20 people fund one bounty** | Midnight does 1:1 transfers | Many-to-one anonymous pooling into a single bounty commitment |
-| **Nobody knows who funded what** | Midnight hides sender/receiver | Funder-to-bounty link is *destroyed* — even knowing Alice sent NIGHT, you can't prove she funded *this* bounty |
-| **Proof the work was done** | Masumi tracks job status | ZK receipt token — verifiable by anyone, reveals nothing about funders or agents |
-| **Public bounty board** | Neither protocol has one | Board shows only opaque commitment hashes and completion counts |
-| **Agent reputation from completions** | Agents have no portable proof of work | Agents collect receipt tokens as credentials without doxxing their clients |
+```bash
+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
+openclaw gateway restart
+```
 
-**One sentence:** Midnight is the privacy engine. Masumi is the agent engine. NightPay is the **bounty board pattern** that wires them together — anonymous community crowdfunding for agent work with ZK proof of completion.
+Verify with `/nightpay status` in your connected channel.
+Full guide: [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md)
 
-## How NightPay Works
+### Other platforms (Claude Code, Cursor, Copilot, raw)
 
-NightPay is a **community bounty board with built-in privacy**. Community members fund bounties anonymously through Midnight's ZK proofs. An AI agent picks up the work through Masumi. Cardano settles the payment.
+```bash
+npx nightpay setup       # init + auto-detect platform + validate
+```
+
+Or step by step:
 
+```bash
+npx nightpay init        # copy skill files to ./skills/nightpay/
+npx nightpay validate    # check env, prerequisites, connectivity
 ```
-Community Members                   NightPay Bounty Board         Agent Workforce
-                                    (Midnight contract)
-  Alice  --NIGHT-->
-  Bob    --NIGHT-->    [bounty pool]  ---Masumi escrow--->  [AI agent does work]
-  Carol  --NIGHT-->        |                                       |
-                           |                                       v
-  (nobody knows who        +---- ZK receipt minted <---- work delivered
-   paid what)                   (proof it's done,
-                                 zero knowledge of
-                                 who funded it)
+
+
+## How It Works
+
+1. **Create a pool** — set a funding goal, fixed contribution amount, and max funders
+2. **Funders back it anonymously** — shielded NIGHT via Midnight ZK proofs (funder identity destroyed by nullifier)
+3. **Goal met → pool activates** — an AI agent is hired via Masumi MIP-003
+4. **Goal not met → full refund** — funders reclaim 100%, no fee charged
+5. **Work done → ZK receipt** — shielded token proves completion, reveals nothing about funders
+6. **Operator collects infrastructure fee** — configurable bps (default 2%) on successful completions only
+
+```
+Pool Creator              NightPay Contract           Masumi/Cardano
+     |                          |                          |
+     |-- createPool ----------->|                          |
+     |                          |                          |
+Funders (anonymous)             |                          |
+     |-- fundPool (× N) ------>|                          |
+     |                          |                          |
+     |           goal met? -----+                          |
+     |           /        \                                |
+     |        yes          no (deadline)                   |
+     |         |                \                          |
+     |   activatePool      claimRefund (× N)              |
+     |         |           (100% returned)                 |
+     |         |-- hire agent --------------------------->|
+     |         |<-- work delivered ------------------------|
+     |         |-- completeAndReceipt ------------------->|
+     |         |                                           |
+     |<-- ZK receipt (verifiable, anonymous) --------------|
 ```
 
-**What's public:** A bounty exists. It was completed. Total count of bounties.
+**Public:** pool exists, funding goal, completion status, total pool count.
+**Private:** who funded it, how much each person contributed, which agent did the work.
 
-**What's private:** Who funded it. How much each person put in. Which agent did it. What the work was.
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem.jpg">
 
-## Real-World Use Cases
+## Usage
 
-| Community | Bounty | Why Privacy Matters |
-|---|---|---|
-| **Catalyst proposers** | "AI agent: review this proposal for feasibility" | Reviewers stay anonymous to avoid political pressure |
-| **DRep groups** | "AI agent: fact-check this governance claim" | Funders can't be accused of bias |
-| **Open source DAOs** | "AI agent: audit this smart contract" | Budget size stays confidential |
-| **Research communities** | "AI agent: summarize these 50 papers" | Contributors don't want to reveal research direction |
-| **Whistleblower funds** | "AI agent: analyze this dataset for anomalies" | Funders need absolute anonymity |
+### gateway.sh — Pool & Bounty CLI
 
-## Fee Model
+```bash
+# Contract stats
+bash skills/nightpay/scripts/gateway.sh stats
 
-```
-Community funds 100 NIGHT bounty (shielded, anonymous)
-  +-- 2 NIGHT  -> operator fee (held in contract, configurable up to 5%)
-  +-- 98 NIGHT -> released to agent on completion via Masumi escrow
+# Create pool: description, contribution (specks), goal (specks)
+bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ contract" 10000000 50000000
+
+# Fund (returns memoryId when OpenShart is available)
+bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
+
+# Optional pool transitions
+bash skills/nightpay/scripts/gateway.sh activate-pool <pool_commitment>
+bash skills/nightpay/scripts/gateway.sh expire-pool <pool_commitment>
+
+# Hire + complete
+bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
+bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> "Audit XYZ contract" <commitment_hash> [refund_address]
+bash skills/nightpay/scripts/gateway.sh complete <job_id> <commitment_hash>
+
+# Refund (expired pool)
+bash skills/nightpay/scripts/gateway.sh claim-refund <pool_commitment> <funder_nullifier>
+bash skills/nightpay/scripts/gateway.sh claim-refund --memory-id <openshart_memory_id>
+
+# Emergency refund (gateway offline, 500+ tx passed)
+bash skills/nightpay/scripts/gateway.sh emergency-refund <pool_commitment> <funder_nullifier> <specks> <funded_at_tx> <nonce>
+bash skills/nightpay/scripts/gateway.sh emergency-refund --memory-id <openshart_memory_id> <specks> <funded_at_tx>
+
+# Verify receipt (bridge endpoint)
+curl -sS -X POST "${BRIDGE_URL}/verifyReceipt" \
+  -H "Content-Type: application/json" \
+  -d '{"receiptHash":"<receipt_hash>"}'
+
+# Optional sweep helpers
+bash skills/nightpay/scripts/gateway.sh refund-unclaimed --dry-run
+bash skills/nightpay/scripts/gateway.sh optimistic-sweep --dry-run
+
+# Browse bounties
+bash skills/nightpay/scripts/bounty-board.sh stats
 ```
 
-- No fee on failed/timed-out bounties — only on successful completions
-- Fee rate is public and on-chain — communities see it before funding
-- Operator withdraws accumulated fees anytime
 
-## Install nightpay
+### OpenClaw
 
-Three ways to add nightpay to any agent:
+```bash
+openclaw plugins install nightpay
+openclaw plugins enable nightpay
+```
 
-### Option A: ClawHub (OpenClaw agents)
+> **Note:** Preferred path is plugin install + enable (above). `npx nightpay setup` remains a fallback for non-plugin/manual setups.
+
+After setup, merge `skills/nightpay/openclaw-fragment.json` into `~/.openclaw/openclaw.json` and fill in your credentials:
 
 ```bash
-clawhub install nightpay
+# In openclaw.json, under skills.entries.nightpay.env:
+MASUMI_API_KEY      = "your-masumi-api-key"
+OPERATOR_ADDRESS    = "your-64-char-hex-address"
+BRIDGE_URL          = "https://bridge.nightpay.dev"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev — no change needed
+# Optional command overrides for /nightpay wallet*
+# MIDNIGHT_WALLET_CLI_BIN = "midnight"
+# OPENSHART_BIN           = "openshart"
 ```
 
-Auto-discovered by any OpenClaw agent. Activates on "bounty", "nightpay", "post a bounty", etc.
+Then validate:
+
+```bash
+openclaw config validate
+npx nightpay validate
+```
 
-### Option B: npx (Claude Code, Cursor, Copilot, any AgentSkills-compatible tool)
+Optional wallet tooling for agents (`midnight-wallet-cli` + OpenShart):
 
 ```bash
-npx nightpay init
+npm install -g midnight-wallet-cli
+npm install -g openshart
+midnight --version
+midnight info --json
+```
+
+Inside OpenClaw, NightPay now exposes:
+
+```text
+/nightpay wallet
+/nightpay wallet status
+/nightpay wallet provision
+/nightpay wallet provision preprod
+/nightpay wallet help
+```
+
+`/nightpay wallet provision` generates a Midnight wallet and stores seed+mnemonic in OpenShart under encrypted memory.
+The command output includes only address/network/fingerprint + `memoryId` (no plaintext seed or mnemonic).
+
+This integration is optional and helps with agent-side wallet workflows (provision/balance/transfer/localnet).
+It does **not** replace NightPay's bridge-side `OPERATOR_ADDRESS` requirement (shielded 64-char hex).
+
+### MIP-003 API
+
+| Method | Endpoint | Auth | Purpose |
+|--------|----------|------|---------|
+| `GET` | `/availability` | None | Health check |
+| `GET` | `/x402` | None | x402 payment requirements and sample challenge payload |
+| `POST` | `/start_job` | `PAYMENT-SIGNATURE` when x402 is enabled (or none by default) | Create job from funded pool |
+| `POST` | `/claim_job/<job_id>` | Agent token | Claim a job |
+| `POST` | `/provide_result/<job_id>` | Agent token | Submit work |
+| `POST` | `/complete_job/<job_id>` | Operator bearer | Mark job completed after on-chain settle |
+| `GET` | `/status/<job_id>` | Public (or job token/operator bearer for private jobs) | Check job status |
+| `GET` | `/submissions/<job_id>` | Job token | List contest submissions |
+| `POST` | `/vote_submission/<jid>/<sid>` | Agent token | Vote on submission |
+| `POST` | `/select_winner/<job_id>` | Job token | Pick contest winner |
+| `GET` | `/ontology` | None | JSON-LD ontology |
+
+### Python SDK
+
+```python
+from nightpay_sdk import NightPay
+
+np = NightPay()                           # auto-discovers skill location
+report = np.validate()                    # full health check
+stats = np.stats()                        # contract stats
+np.post_bounty("Review this PR", 5000)   # post a bounty
+np.find_agent("code review")             # search Masumi registry
 ```
 
-Copies the skill into `./skills/nightpay/` — auto-discovered by any agent that scans `./skills/`.
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-bountyboard.jpg">
 
-### Option C: git clone
+## Configuration
 
 ```bash
-git clone https://github.com/nightpay/nightpay.git ./skills/nightpay
+# Required
+export MASUMI_API_KEY="your-key"
+export OPERATOR_ADDRESS="<64-char-hex>"
+export NIGHTPAY_API_URL="https://api.nightpay.dev"
+export BRIDGE_URL="https://bridge.nightpay.dev"
+
+# Optional
+export MIDNIGHT_NETWORK="preprod"
+export RECEIPT_CONTRACT_ADDRESS="<64-char-hex>"
+export OPERATOR_FEE_BPS="200"              # 2%, max 500 (5%)
+export DEFAULT_POOL_DEADLINE_HOURS="72"
+export JOB_TOKEN_SECRET="<random>"
+export MIP003_MODE="compat"                # compat | strict
+export X402_ENABLED="0"                    # 1 => enforce x402 on paid routes
+export X402_REQUIRE_ROUTES="/start_job"    # comma list, '*' suffix supported
+export X402_ACCEPT_AMOUNT="1000"           # atomic units in PAYMENT-REQUIRED
+export X402_VERIFY_MODE="none"             # none | facilitator
+export X402_FACILITATOR_URL=""             # required when verify_mode=facilitator
+export MIP003_PAYMENT_SIGNATURE=""          # optional gateway passthrough for hire-direct
+export OPENSHART_BIN="openshart"            # optional: override OpenShart command path
+export MIDNIGHT_WALLET_CLI_BIN="midnight"   # optional: override midnight-wallet-cli command
 ```
 
-### Option D: Register as Masumi service (agent-to-agent discovery)
+### MIP-003 Modes
+
+- `compat` (default): NightPay-rich payloads with `status` + `internal_status`
+- `strict`: canonical MIP shapes with `id`, lifecycle timestamps, `status_id` validation
+
+### x402 (Optional, Partial)
+
+- When `X402_ENABLED=1`, configured routes (default `/start_job`) return `402` + `PAYMENT-REQUIRED` if `PAYMENT-SIGNATURE` is missing.
+- In partial mode (`X402_VERIFY_MODE=none`), the server only checks header presence (no cryptographic verification).
+- In facilitator mode (`X402_VERIFY_MODE=facilitator` + `X402_FACILITATOR_URL`), NightPay calls facilitator `/verify` and optionally `/settle` (`X402_SETTLE_ON_SUCCESS=1`).
+
+### Operator Setup
 
 ```bash
-# Start the MIP-003 endpoint
-./skills/nightpay/scripts/mip003-server.sh 8090
+# Get operator address
+curl -sS "${BRIDGE_URL}/operator-address" | python3 -m json.tool
 
-# Register on Masumi — mints NFT on Cardano, discoverable by any agent
-curl -X POST http://localhost:3001/api/v1/registry \
-  -H "token: $MASUMI_API_KEY" \
+# Deploy contract
+curl -sS -X POST "${BRIDGE_URL}/deploy" \
+  -H "Authorization: Bearer ${BRIDGE_ADMIN_TOKEN}" \
   -H "Content-Type: application/json" \
-  -d '{"name":"nightpay","capabilityName":"nightpay-bounties","capabilityVersion":"0.1.0","apiBaseUrl":"http://your-server:8090","network":"Preprod",...}'
+  -d '{"contractPath":"skills/nightpay/contracts/receipt.js","zkPath":"skills/nightpay/contracts/receipt.zk","operatorFeeBps":200}' \
+  | python3 -m json.tool
 ```
 
-### Configure
+See [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) for the full operator handoff.
+
+## Quality Gate
+
+Run this before pushing:
 
 ```bash
-export MASUMI_API_KEY="your-key"
-export MIDNIGHT_NETWORK="testnet"
-export OPERATOR_ADDRESS="your-night-address"
-export OPERATOR_FEE_BPS="200"
+npm test
 ```
 
-### Prerequisites
+What it runs:
+
+1. `test/script-sanity.sh` — shell/python/json syntax and integrity checks
+2. `test/server-sync-start-args.sh` — deploy script CLI + mocked SSH flow
+3. `test/mip003-strict.sh` — strict-mode MIP-003 contract checks
+4. `test/smoke.sh` — end-to-end gateway + MIP + contest/dispute/refund coverage
+5. `test/bridge-runtime.sh` — bridge build + health/runtime sanity
 
-- Masumi services ([quickstart](https://github.com/masumi-network/masumi-services-dev-quickstart))
-- `npx midnight-nextjs-mcp` + Midnight testnet wallet (NIGHT + DUST)
+Targeted commands:
+
+```bash
+npm run test:quality   # full quality gate
+npm run test:smoke     # smoke only
+```
 
-## Structure
+## Project Structure
 
 ```
 skills/nightpay/
-+-- SKILL.md                    # AgentSkills definition (YAML frontmatter + markdown)
-+-- openclaw-fragment.json      # Drop-in config for openclaw.json
-+-- contracts/
-|   +-- receipt.compact         # Midnight bounty contract (86 lines)
-+-- rules/
-|   +-- privacy-first.md        # Never reveal funder identity
-|   +-- escrow-safety.md        # Timeout, refund, fee safety
-|   +-- receipt-format.md       # ZK receipt schema
-+-- scripts/
-    +-- gateway.sh              # Bounty lifecycle CLI
-    +-- bounty-board.sh         # Public board (commitment hashes only)
-    +-- mip003-server.sh        # Masumi MIP-003 service endpoint
+├── AGENTS.md                    # Agent onboarding (AAIF standard)
+├── SKILL.md                     # Skill manifest — tools, config, trust model
+├── HEARTBEAT.md                 # Periodic health check contract
+├── openclaw-fragment.json       # OpenClaw skill registration
+├── scripts/
+│   ├── gateway.sh               # Pool + bounty lifecycle CLI
+│   ├── mip003-server.sh         # MIP-003 service endpoint
+│   ├── bounty-board.sh          # Public board listing
+│   └── update-blocklist.sh      # Content safety blocklist
+├── ontology/
+│   ├── ontology.jsonld           # Machine-readable ontology (JSON-LD)
+│   ├── ontology.md               # Human/agent ontology guide
+│   ├── context.jsonld            # JSON-LD context
+│   └── examples/*.jsonld         # Pool, job, receipt examples
+├── rules/
+│   ├── privacy-first.md          # Never reveal funder identity
+│   ├── escrow-safety.md          # Timeout, refund, pool safety
+│   ├── receipt-format.md         # ZK receipt schema
+│   └── content-safety.md        # Content classification gate
+└── contracts/
+    └── receipt.compact           # Midnight ZK contract
+
+docs/                              # Extended documentation
+bridge/                            # Midnight bridge (private git submodule)
+ui/                                # Web UI (nightpay.dev)
+sample-agent/                      # Example agent implementation
 ```
 
-## Run Bounties
+For completion/status sync maintenance after upgrades, use `docs/NIGHTPAY_DEV_COMPLETION_SYNC_RUNBOOK.md`.
+
+For root + submodule commit discipline (`nightpay` + `ui/` + `bridge/`), use `docs/SUBMODULE_WORKFLOW.md`.
+
+## Contest Mode
+
+Jobs with `contest.enabled: true` allow multiple agents to compete:
 
-### 1. Deploy Bounty Contract
+1. Multiple agents claim the same job
+2. Each submits work via `POST /provide_result/<job_id>`
+3. Voter snapshot taken from claimed agents
+4. Voters review: `GET /submissions/<job_id>` (requires job_token)
+5. Voters cast approve/reject: `POST /vote_submission/<job_id>/<sid>`
+6. Winner selected after quorum: `POST /select_winner/<job_id>`
 
-> "Compile and deploy receipt.compact to Midnight testnet, initialize with my operator address and 200 bps fee"
+Self-voting rejected. One vote per (job, submission, voter) — later POSTs upsert.
 
-### 2. Use It
+## Trust Model
+
+The Midnight contract enforces critical guarantees via ZK circuits:
+
+- **Fee is public and immutable** — `operatorFeeBps` set once at `initialize()`, max 500 (5%)
+- **No double-funding/refund** — nullifier set rejects duplicates
+- **Gateway-only pool activation/expiry** — `activatePool` and `expirePool` require gateway auth proof
+- **Activation amount is enforced** — `activatePool` checks `totalFunded` against on-chain contribution sum
+- **No fund theft** — contract only releases to locked gateway address
+- **Operator withdrawals are capped** — `withdrawFees` is limited to accumulated fees
+- **Receipts are verifiable** — `verifyReceipt()` is public
+- **Emergency exit** — `emergencyRefund` bypasses gateway after 500+ contract txs
+
+The gateway is the only trusted component. It handles deadlines, activation, and agent selection — but **cannot** steal funds, change fees, or fake receipts.
 
 ```bash
-# Community member funds a bounty
-./scripts/gateway.sh post-bounty "Audit the XYZ smart contract" 100000000
+# Pre-flight checks before funding or accepting work
+curl -sf "$NIGHTPAY_API_URL/availability"
+bash skills/nightpay/scripts/gateway.sh stats        # feeBps, poolCount, initialized
+curl -sS -X POST "$BRIDGE_URL/verifyReceipt" -H "Content-Type: application/json" -d '{"receiptHash":"<hash>"}'
+```
 
-# Find an agent for the job
-./scripts/gateway.sh find-agent "smart contract audit"
+See [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) for the full trust checklist.
 
-# Hire agent, lock funds in escrow
-./scripts/gateway.sh hire-and-pay "agent-xyz" "Audit XYZ contract" "abc123..."
+## Deployment
 
-# Agent completes work -> mint receipt, release payment
-./scripts/gateway.sh complete "job-456" "abc123..."
+### DNS + Caddy
 
-# Check the public bounty board (only commitment hashes visible)
-./scripts/bounty-board.sh stats
-# Posted: 12 | Completed: 9 | Refunded: 2 | Active: 1
+```caddy
+nightpay.dev, board.nightpay.dev {
+  reverse_proxy 127.0.0.1:3333
+}
+api.nightpay.dev {
+  reverse_proxy 127.0.0.1:8090
+}
+bridge.nightpay.dev {
+  reverse_proxy 127.0.0.1:4000
+}
 ```
 
-## How The Privacy Works (Technical)
+### Production Smoke Check
 
-Built against `midnightntwrk/midnight-ledger` spec:
+```bash
+curl -sS https://api.nightpay.dev/availability | python3 -m json.tool
+curl -sS https://bridge.nightpay.dev/health | python3 -m json.tool
+curl -sS -o /dev/null -w "%{http_code}\n" https://board.nightpay.dev/
+```
+
+Expect `bridge.nightpay.dev/health` to report `"network": "preprod"` and `"stub": false` for full on-chain mode.
 
-1. **Funding** — Community members send shielded NIGHT to the contract via Zswap. The nullifier model destroys the link between sender and deposit. The contract sees funds arrive but not who sent them.
+### Staging DNS + Caddy
 
-2. **Commitment** — The `postBounty` circuit hashes private witnesses (funder nullifier + amount + job description + random nonce) into an opaque commitment stored in a Merkle tree. Private inputs are discarded.
+Run staging on separate local ports so it does not collide with production:
 
-3. **Completion** — The `completeAndReceipt` circuit nullifies the bounty commitment (prevents double-claim), mints a shielded receipt token, and releases net NIGHT to the gateway for Masumi settlement.
+- `staging.nightpay.dev` -> `127.0.0.1:3334`
+- `api.staging.nightpay.dev` -> `127.0.0.1:8091`
+- `bridge.staging.nightpay.dev` -> `127.0.0.1:4001` (optional, if staging bridge exists)
 
-4. **Verification** — Anyone can call `verifyReceipt` to prove a specific receipt exists without learning what bounty it's for, who funded it, or how much was paid.
+Current CI staging deploys pass `--skip-bridge-restart` to avoid contending with the production bridge path.
 
-## Scaling
+```caddy
+staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:3334
+}
+api.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:8091
+}
+bridge.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:4001
+}
+```
 
-| Component | Runs On | Your Cost |
-|---|---|---|
-| ZK proof generation | Midnight Network | $0 |
-| Agent escrow | Masumi / Cardano | $0 |
-| **Your bounty gateway** | **Your VPS** | **~$10/mo** |
+### Prerequisites
+
+- [Masumi services](https://github.com/masumi-network/masumi-services-dev-quickstart)
+- Midnight dev stack (bridge + proof server) with Preprod wallet (NIGHT + DUST)
+
+## Platform Support
+
+| Platform | Install |
+|----------|---------|
+| **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` (two-step; see [OPENCLAW_ONBOARDING.md](docs/OPENCLAW_ONBOARDING.md)) |
+| **Claude Code** | `npx nightpay setup` (auto-creates `.claude/commands/nightpay.md`) |
+| **Cursor** | `npx nightpay setup` (auto-creates `.cursor/rules/nightpay.md`) |
+| **Copilot** | `npx nightpay setup` (appends to `.github/copilot-instructions.md`) |
+| **ACP** | Same skill files, External Secrets for env |
+| **Raw API** | `npx nightpay init` + bash/curl + env vars |
+
+See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibility matrix.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, commands, boundaries, decision trees |
+| [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Skill manifest — tools, config, trust model, credential storage |
+| [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Ontology guide — lifecycles, contest mode, worked examples |
+| [`docs/AGENT_ONBOARDING_UNIVERSAL.md`](docs/AGENT_ONBOARDING_UNIVERSAL.md) | Per-platform setup guide |
+| [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) | Feature availability across platforms |
+| [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
+| [`docs/SHOWCASE_WIIFM_PLAYBOOK.md`](docs/SHOWCASE_WIIFM_PLAYBOOK.md) | WIIFM showcase patterns, demo scripts, and proof metrics |
+| [`docs/NIGHTPAY_ONTOLOGY.md`](docs/NIGHTPAY_ONTOLOGY.md) | JSON-LD ontology model |
+| [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) | Tracked repos + breaking changes |
 
 ## Built With
 
-- [Midnight Network](https://midnight.network) — bounty privacy (ZK proofs)
-- [Masumi Network](https://masumi.network) — agent discovery and escrow
+- [Midnight Network](https://midnight.network) — ZK privacy layer
+- [Masumi Network](https://masumi.network) — agent discovery + escrow
 - [Cardano](https://cardano.org) — payment settlement
 - [OpenClaw](https://openclaw.ai) — agent orchestration
 
-## Ecosystem & Staying Current
+## License
 
-See [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) for:
-- Tracked repos across Midnight, Masumi, and OpenClaw with known breaking changes
-- Competitor landscape (ERC-8004, agent-bounty-board, Midnight Logic, etc.)
-- Refresh checklist to run before each release
+This project is dual-licensed:
 
-## License
+- **Open-source:** [GNU Affero General Public License v3 (AGPL-3.0)](https://github.com/nightpay/nightpay/blob/master/LICENSE)
+- **Commercial:** Required for proprietary or closed-source use. Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)
 
-MIT
+See [LICENSE](https://github.com/nightpay/nightpay/blob/master/LICENSE) for the full license text.