@bankofbots/skill 0.1.0 → 0.3.0

package/SKILL.md

@@ -5,339 +5,49 @@ description: >
   build a verifiable BOB Score — a trust score (think FICO but for AI Agents)
   that other agents and services can check to give them confidence before doing
   business with yours.
-metadata: '{"openclaw":{"requires":{"env":["BOB_API_KEY","BOB_AGENT_ID"]},"primaryEnv":"BOB_API_KEY"}}'
+metadata: '{"openclaw":{"requires":{"env":["BOB_API_KEY","BOB_AGENT_ID"]},"optional":{"env":["BOB_API_URL"]},"primaryEnv":"BOB_API_KEY"}}'
 ---
 
-You have access to `bob`, the Bank of Bots CLI for managing agent wallets, payments, and transactions. Requires `BOB_API_KEY` and `BOB_AGENT_ID` environment variables to be set. Optionally set `BOB_API_URL` to point to a custom backend.
+You are a BOB (Bank of Bots) agent. You use `bob`, the Bank of Bots CLI, to manage wallets, send BTC payments, and build your BOB Score through verified payment history.
 
-All commands output structured JSON with an `ok` field and `next_actions` that suggest follow-up commands.
-
-**Supported rails: `lightning` and `onchain` (BTC only).** USD and USDC rails are not available.
+**Rails: `lightning` and `onchain` only. BTC only. All amounts in satoshis.**
 
 ## Setup
 
-Download the latest `bob` binary from **https://github.com/bankofbots/bob-cli/releases/latest** and place it on your PATH. Then set:
-- `BOB_API_KEY` — your agent API key
-- `BOB_AGENT_ID` — your agent ID
-- `BOB_API_URL` — `https://api.bankofbots.ai/api/v1`
-
-## Core concepts
-
-- **Agent**: An AI agent with its own identity, wallets, and spending policies
-- **Wallet**: Holds a BTC balance on a specific rail (lightning or onchain)
-- **Policy**: Spend limits, rate limits, and kill switches that constrain agent behavior
-- **Transaction**: A record of money moving in or out of a wallet
-- **Service Gate**: A priced action that callers unlock by presenting a completed payment intent
-
-## Commands
-
-### Check your identity
-
-```bash
-bob auth me
-```
-
-Returns your role (agent or operator), identity details, and role-aware `next_actions`.
-
-### Agent details and wallet balances
-
-```bash
-bob agent get <agent-id>
-```
-
-Response includes a `wallets` array with each wallet's balance, currency, rail, and status.
-
-### Wallet management
-
-```bash
-# List wallets for an agent
-bob wallet list <agent-id>
-
-# Get/set wallet budget (sats)
-bob wallet budget get <agent-id> --wallet-id <id>
-bob wallet budget set <agent-id> --wallet-id <id> --amount <sats>
-```
-
-`bob wallet list` includes a `bob_address` field when a default agent address is available.
-
-### One-shot send (auto-quote + execute)
-
-```bash
-bob send <agent-id> <destination> --amount <sats> [--currency BTC]
-```
-
-Destination is auto-detected:
-- `jade@bankofbots.ai` → routes as `bob_address` (BTC)
-- `lnbc...` → Lightning invoice
-- `bc1.../tb1...` → on-chain BTC address
-
-| Flag | Description |
-|---|---|
-| `--amount` | Required. Satoshis |
-| `--priority` | cheapest, fastest, or balanced (default: balanced) |
-| `--description` | Optional payment note |
-| `--max-fee` | Maximum acceptable fee in sats |
-| `--rail` | Pin to lightning or onchain |
-| `--destination-type` | Override auto-detection: `raw` or `bob_address` |
-
-Quotes then executes in one step. Returns `intent_id`, `payment_id`, and `quote_summary`. On failure, `next_actions` includes exact recovery commands.
-
-### CLI config introspection
-
-```bash
-# Show active api_url, platform, config file path and source (env/config/default)
-bob config show
-
-# Update a single config value without re-init
-bob config set api-url <url>
-bob config set platform <generic|openclaw|claude>
-```
-
-### Record a transaction (spend from your wallet)
-
-```bash
-bob tx record <agent-id> --amount <sats> --currency BTC
-```
-
-| Flag | Description |
-|---|---|
-| `--amount` | Required. Satoshis |
-| `--currency` | BTC (only supported currency) |
-| `--rail` | lightning or onchain (default: auto) |
-| `--endpoint` | Target endpoint or merchant identifier |
-| `--wallet-id` | Specific wallet to debit (auto-selected if omitted) |
-
-### Transfer BTC to another agent
-
-```bash
-bob tx transfer <from-agent-id> --to-agent-id <to-agent-id> --amount <sats> --currency BTC
-```
-
-| Flag | Description |
-|---|---|
-| `--to-agent-id` | Required. Destination agent ID |
-| `--amount` | Required. Satoshis |
-| `--description` | Optional note |
-
-### Quote and execute payments (intent workflow)
-
-The intent workflow quotes routes before executing, giving you visibility into fees, ETAs, and available rails.
-
-```bash
-# Quote routes for a payment
-bob intent quote <agent-id> --amount <sats> --destination-type raw --destination-ref <lnbc...|bc1...>
-
-# Execute a quoted intent (uses best quote by default)
-bob intent execute <agent-id> <intent-id> [--quote-id <id>]
-
-# Check intent status and route details
-bob intent get <agent-id> <intent-id>
-
-# List recent intents
-bob intent list <agent-id>
-```
-
-| Flag | Description |
-|---|---|
-| `--amount` | Required. Satoshis |
-| `--destination-type` | `raw` or `bob_address` |
-| `--destination-ref` | Lightning invoice, on-chain address, or `alias@bankofbots.ai` |
-| `--priority` | `cheapest`, `fastest`, or `balanced` (default: balanced) |
-| `--execution-mode` | `auto` or `pinned` (default: auto) |
-| `--rail` | Pin to `lightning` or `onchain` |
-| `--wallet-id` | Pin to a specific wallet |
-| `--max-fee` | Maximum acceptable fee in sats |
-
-### Non-custodial proof submission
-
-Submit proof of BTC payment to verify settlement and build your BOB Score:
-
-```bash
-# On-chain transaction proof
-bob intent submit-proof <agent-id> <intent-id> --txid <txid>
-
-# Lightning payment hash proof
-bob intent submit-proof <agent-id> <intent-id> --payment-hash <hash>
-
-# Lightning preimage proof (strongest verification)
-bob intent submit-proof <agent-id> <intent-id> --preimage <hex> --proof-ref <payment-hash>
-
-# With optional BOLT11 invoice for amount verification
-bob intent submit-proof <agent-id> <intent-id> --preimage <hex> --proof-ref <payment-hash> --invoice <lnbc...>
-
-# Historical proof import for credit building
-bob agent credit-import <agent-id> --preimage <hex> --proof-ref <payment-hash> --amount <sats> --direction inbound --invoice <lnbc...>
-```
-
-| Proof Type | Description |
-|---|---|
-| `btc_onchain_tx` | On-chain transaction ID |
-| `btc_lightning_payment_hash` | Lightning payment hash |
-| `btc_lightning_preimage` | Lightning preimage (SHA256 verified against payment hash, strongest proof) |
-
-### Query history
-
-```bash
-# Transactions
-bob tx list <agent-id> --status complete --direction outbound --limit 10
-
-# Transfers
-bob tx transfers <agent-id>
-
-# Spend summary
-bob spend list <agent-id>
-```
-
-### View policies
-
-```bash
-bob policy list <agent-id>
-```
-
-### Agent credit score and history
-
-```bash
-# View credit score, tier, and effective policy limits
-bob agent credit <agent-id>
-
-# View credit event timeline
-bob agent credit-events <agent-id> [--limit 50] [--offset 0]
-```
-
-The BOB Score runs from 0–1000. New operators start at **350**. Tiers: **Legendary** (925+), **Elite** (800+), **Trusted** (650+, 1.5x limits), **Established** (500+, 1.2x limits), **Verified** (400+, 1.0x limits), **New** (300+, 1.0x limits), **Unverified** (150+, 0.6x limits), **Blacklisted** (0+, 0.6x limits). When credit tier enforcement is enabled, the tier multiplier adjusts spend and rate limits up or down from the base policy values.
-
-### Agent routing profile (autonomous rail preference)
-
-```bash
-# Inspect current weighting and preferred rail order
-bob agent routing-profile <agent-id>
-
-# Update balanced-scoring weights + preferred rails
-bob agent routing-profile set <agent-id> \
-  --cost-weight 0.6 \
-  --eta-weight 0.4 \
-  --reliability-weight 0.2 \
-  --liquidity-weight 0.1 \
-  --preferred-btc lightning,onchain
-```
-
-Routing profile influences quote ranking for `priority=balanced` and is applied during intent quote + execute.
-
-### Agent webhooks and event stream
-
-```bash
-# Create/list/get/update/delete webhooks scoped to one agent
-bob agent webhooks create <agent-id> --url https://example.com/hook --events payment_intent.complete,payment.failed
-bob agent webhooks list <agent-id>
-bob agent webhooks get <agent-id> <webhook-id>
-bob agent webhooks update <agent-id> <webhook-id> --active true
-bob agent webhooks delete <agent-id> <webhook-id>
-
-# Pull recent agent events (paginated)
-bob agent events <agent-id> --limit 30 --offset 0
-```
-
-Agent-scoped webhooks/events include payment intent lifecycle events (`quoted`, `executing`, `submitted`, `complete`, `failed`) so agents can react asynchronously without polling.
-
-### Operator credit controls
-
 ```bash
-# View current operator credit posture
-bob operator credit summary
-
-# Force snapshot recompute
-bob operator credit refresh
-
-# Toggle runtime enforcement of credit tier multipliers
-bob operator credit enforcement set --enabled=true
-```
-
-### Operator payment addresses
-
-```bash
-# Create and inspect address aliases
-bob address create --handle ops
-bob address list
-
-# Bind destination endpoints
-bob address add-endpoint <address-id> --currency BTC --rail lightning --destination-type raw --destination-ref <lnbc...>
-
-# Enable/disable a bound endpoint
-bob address set-endpoint-status <address-id> <endpoint-id> --status disabled
-
-# Resolve live routing capabilities
-bob address resolve --address ops@bankofbots.ai --currency BTC
+# Install: download bob binary from https://github.com/bankofbots/bob-cli/releases/latest
+# Required env: BOB_API_KEY, BOB_AGENT_ID
+# Optional env: BOB_API_URL (default: https://api.bankofbots.ai/api/v1)
+bob auth me                          # verify connection
+bob wallet list $BOB_AGENT_ID        # check wallets and funding status
+bob agent credit $BOB_AGENT_ID       # check BOB Score
 ```
 
-### Service gates (pay-to-access)
+## Core commands
 
 ```bash
-# Create a priced gate (agent must have a payment address)
-bob gate create <agent-id> --name "premium-api" --price 1000 --currency BTC
-
-# List active gates
-bob gate list <agent-id>
-
-# Get gate details
-bob gate get <agent-id> <gate-id>
-
-# Disable/re-enable a gate
-bob gate update <agent-id> <gate-id> --status disabled
-
-# Unlock a gate (caller presents a completed payment intent targeting the gate owner)
-bob gate unlock <owner-agent-id> <gate-id> --intent-id <payment-intent-id>
-
-# View unlock history
-bob gate unlocks <agent-id> <gate-id>
+# Send BTC (one-shot: auto-quotes and executes)
+bob send $BOB_AGENT_ID <destination> --amount <sats>
 
-# List gates this agent has unlocked as a caller
-bob gate my-unlocks <agent-id>
+# Submit payment proof (builds BOB Score)
+bob intent submit-proof $BOB_AGENT_ID <intent-id> --preimage <hex> --proof-ref <payment-hash>
 
-# Discover another agent's active gates
-bob gate discover <agent-id>
+# Check score and history
+bob agent credit $BOB_AGENT_ID
+bob agent credit-events $BOB_AGENT_ID
 ```
 
-| Flag | Description |
-|---|---|
-| `--name` | Required. Human-readable gate name |
-| `--price` | Required. Minimum payment amount in sats |
-| `--currency` | BTC |
-| `--intent-id` | Required for unlock. Completed payment intent ID |
-| `--status` | For update: active or disabled |
-
-## Output format
-
-Every command returns JSON with this structure:
-
-```json
-{
-  "ok": true,
-  "command": "bob tx record",
-  "data": { ... },
-  "next_actions": [
-    {
-      "command": "bob tx list <agent-id>",
-      "description": "View transaction history"
-    }
-  ]
-}
-```
-
-Always check `ok` before using `data`. When `ok` is false, `data.error` contains the error message and `next_actions` provides recovery suggestions.
-
-## Error recovery
-
-When `ok` is false, `next_actions` provides context-aware recovery suggestions. Key patterns:
+## Rules
 
-1. **Kill switch active**: STOP all transactions immediately. Run `bob policy list <agent-id>` to confirm.
-2. **Spend/rate limit exceeded**: Check `bob spend list <agent-id>` to see current usage vs limits.
-3. **Insufficient balance**: Check `bob wallet list <agent-id>` to see available funds.
-4. **403 Forbidden**: Check `bob auth me` to verify your identity and role.
-5. **409 Conflict**: Resource already exists (e.g., agent already registered). Do not retry — run `bob agent get <agent-id>` to confirm current state.
+1. **Always check `ok`** before using `data`. On failure, read `data.error` and follow `next_actions`.
+2. **Kill switch**: If denied with kill switch reason, stop all transactions immediately. Do not retry.
+3. **409 Conflict**: Do not retry — resource already exists. Inspect current state first.
+4. **`tx record`** debits wallet balance — only run when wallet has sufficient funds.
+5. **Never invent amounts, txids, or payment hashes.** Use only values returned by the API or provided by the user.
 
-## Important rules
+## Reference files
 
-1. **Amounts** are always in satoshis (BTC).
-2. **Policies** set by your operator constrain your spending. If a transaction is denied, `data.error` explains why. Do not retry denied transactions without changing the parameters.
-3. **Kill switch**: If you receive a kill switch denial, stop all transaction attempts immediately. The operator has frozen your spending.
-4. **next_actions**: Every response includes suggested follow-up commands. Use them to discover what to do next.
+- [Full command reference](references/commands.md) — all commands and flags
+- [Proof submission](references/proofs.md) — proof types, submission flow, historical import
+- [BOB Score & tiers](references/scoring.md) — tiers, credit events, how to build score
+- [Error recovery](references/errors.md) — hard stops, recoverable errors, output format

package/index.js

@@ -2,9 +2,11 @@ const fs = require("fs");
 const path = require("path");
 
 const skillPath = path.join(__dirname, "SKILL.md");
+const referencesDir = path.join(__dirname, "references");
 
 module.exports = {
   skillPath,
+  referencesDir,
   get content() {
     return fs.readFileSync(skillPath, "utf8");
   },

package/install.js

@@ -9,9 +9,11 @@ const skillPath = path.join(__dirname, "SKILL.md");
 
 console.log("\n@bankofbots/skill installed.");
 console.log("Skill file: " + skillPath);
-console.log("\nTo activate for your platform, copy SKILL.md to:");
-console.log("  Claude Code : .claude/skills/bankofbots/SKILL.md");
-console.log("  OpenClaw    : ~/.openclaw/skills/bankofbots/SKILL.md");
+console.log("\nTo activate for your platform, copy the skill directory to:");
+console.log("  Claude Code : .claude/skills/bankofbots/");
+console.log("  OpenClaw    : ~/.openclaw/skills/bankofbots/");
+console.log("\nQuick copy (from your project root):");
+console.log("  cp -r node_modules/@bankofbots/skill/SKILL.md node_modules/@bankofbots/skill/references .claude/skills/bankofbots/");
 console.log("\nOr read it programmatically:");
-console.log('  require("@bankofbots/skill")  // returns { skillPath, content }');
+console.log('  require("@bankofbots/skill")  // returns { skillPath, referencesDir, content }');
 console.log("");

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@bankofbots/skill",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Bank of Bots skill file for AI agents (Claude Code, OpenClaw, and compatible platforms)",
   "main": "index.js",
   "files": [
     "SKILL.md",
+    "references/",
     "README.md",
     "index.js",
     "install.js"

package/references/commands.md

@@ -0,0 +1,123 @@
+# BOB CLI — Full Command Reference
+
+## Identity
+
+```bash
+bob auth me                          # your role, agent/operator ID, next_actions
+bob config show                      # active api_url, platform, config file path
+bob config set api-url <url>
+bob config set platform <generic|openclaw|claude>
+```
+
+## Agent
+
+```bash
+bob agent get <agent-id>             # details + wallets array with balances
+bob agent credit <agent-id>          # BOB Score, tier, effective policy limits
+bob agent credit-events <agent-id> [--limit 50] [--offset 0]
+bob agent routing-profile <agent-id>
+bob agent routing-profile set <agent-id> \
+  --cost-weight 0.6 --eta-weight 0.4 \
+  --reliability-weight 0.2 --liquidity-weight 0.1 \
+  --preferred-btc lightning,onchain
+```
+
+## Wallets
+
+```bash
+bob wallet list <agent-id>           # balances, rails, status; includes bob_address
+bob wallet budget get <agent-id> --wallet-id <id>
+bob wallet budget set <agent-id> --wallet-id <id> --amount <sats>
+```
+
+## Sending (one-shot)
+
+```bash
+bob send <agent-id> <destination> --amount <sats>
+```
+
+Destination auto-detected: `jade@bankofbots.ai` → bob_address, `lnbc...` → Lightning, `bc1...` → onchain.
+
+| Flag | Description |
+|---|---|
+| `--amount` | Required. Satoshis |
+| `--priority` | cheapest, fastest, balanced (default: balanced) |
+| `--description` | Optional payment note |
+| `--max-fee` | Max fee in sats |
+| `--rail` | Pin to lightning or onchain |
+| `--destination-type` | Override: raw or bob_address |
+
+## Intent workflow (quote → inspect → execute)
+
+```bash
+bob intent quote <agent-id> --amount <sats> --destination-type raw --destination-ref <dest>
+bob intent execute <agent-id> <intent-id> [--quote-id <id>]
+bob intent get <agent-id> <intent-id>
+bob intent list <agent-id>
+```
+
+| Flag | Description |
+|---|---|
+| `--amount` | Required. Satoshis |
+| `--destination-type` | raw or bob_address |
+| `--destination-ref` | Lightning invoice, onchain address, or alias@bankofbots.ai |
+| `--priority` | cheapest, fastest, balanced |
+| `--execution-mode` | auto or pinned |
+| `--rail` | Pin to lightning or onchain |
+| `--wallet-id` | Pin to specific wallet |
+| `--max-fee` | Max fee in sats |
+
+## Transactions
+
+```bash
+bob tx record <agent-id> --amount <sats> --currency BTC [--rail lightning|onchain] [--endpoint <url>]
+bob tx list <agent-id> [--status complete] [--direction outbound] [--limit 10]
+bob tx transfer <from-agent-id> --to-agent-id <to-id> --amount <sats> --currency BTC
+bob tx transfers <agent-id>
+bob spend list <agent-id>
+```
+
+`tx record` debits wallet balance — requires funded wallet.
+
+## Policies
+
+```bash
+bob policy list <agent-id>
+```
+
+## Webhooks & events
+
+```bash
+bob agent webhooks create <agent-id> --url <url> --events payment_intent.complete,payment.failed
+bob agent webhooks list <agent-id>
+bob agent webhooks get <agent-id> <webhook-id>
+bob agent webhooks update <agent-id> <webhook-id> --active true
+bob agent webhooks delete <agent-id> <webhook-id>
+bob agent events <agent-id> [--limit 30] [--offset 0]
+```
+
+## Service gates
+
+```bash
+bob gate create <agent-id> --name "premium-api" --price 1000 --currency BTC
+bob gate list <agent-id>
+bob gate get <agent-id> <gate-id>
+bob gate update <agent-id> <gate-id> --status disabled
+bob gate unlock <owner-agent-id> <gate-id> --intent-id <intent-id>
+bob gate unlocks <agent-id> <gate-id>
+bob gate my-unlocks <agent-id>
+bob gate discover <agent-id>
+```
+
+## Operator commands
+
+```bash
+bob operator credit summary
+bob operator credit refresh
+bob operator credit enforcement set --enabled=true
+bob address create --handle ops
+bob address list
+bob address add-endpoint <address-id> --currency BTC --rail lightning --destination-type raw --destination-ref <dest>
+bob address set-endpoint-status <address-id> <endpoint-id> --status disabled
+bob address resolve --address ops@bankofbots.ai --currency BTC
+```

package/references/errors.md

@@ -0,0 +1,38 @@
+# BOB CLI — Error Recovery
+
+Every failed command returns `ok: false` with `data.error` and `next_actions`. Always follow `next_actions` before retrying.
+
+## Hard stops — do not retry
+
+| Error | Action |
+|---|---|
+| Kill switch active | **STOP all transactions immediately.** Run `bob policy list <agent-id>` to confirm. Do not retry until operator lifts the freeze. |
+| 403 Forbidden | Run `bob auth me`. Key may be invalid or agent not approved. |
+| Policy violation (tx denied) | Do not retry with same parameters. Read `data.error` — change amount, endpoint, or rail. |
+
+## Recoverable errors
+
+| Error | Action |
+|---|---|
+| Insufficient balance | Run `bob wallet list <agent-id>` to check available funds. Wait for incoming payment or ask operator to fund. |
+| Spend/rate limit exceeded | Run `bob spend list <agent-id>` to see usage vs limits. Wait for window reset or request limit increase. |
+| 409 Conflict | Resource already exists. Do not retry — run `bob agent get <agent-id>` or `bob intent get` to confirm current state. |
+| Wallet not provisioned | Agent has no wallet for requested currency/rail. Contact operator to provision. |
+| Wallet not ready | Wallet exists but is pending. Run `bob wallet list <agent-id>` and wait for status=ready. |
+| Lightning invoice expired | Re-request a fresh invoice from the payee and retry. |
+| Proof already submitted | Duplicate proof ref — already counted. Check `bob agent credit-events`. |
+
+## Output format
+
+```json
+{
+  "ok": true | false,
+  "command": "bob <subcommand>",
+  "data": { ... },
+  "next_actions": [
+    { "command": "bob ...", "description": "..." }
+  ]
+}
+```
+
+`ok: false` → `data.error` has the reason. `next_actions` always present — execute them in order.

package/references/proofs.md

@@ -0,0 +1,45 @@
+# BOB Score — Proof Submission
+
+Submitting payment proofs verifies settlement on-chain and awards BOB Score credit. Stronger proof types earn more credit.
+
+## Proof types
+
+| Type | Command flag | What it proves |
+|---|---|---|
+| `btc_lightning_preimage` | `--preimage <hex> --proof-ref <payment-hash>` | SHA256(preimage) == payment hash — cryptographically irrefutable |
+| `btc_onchain_tx` | `--txid <txid>` | On-chain transaction confirmed |
+
+## Submit proof against a payment intent
+
+```bash
+# On-chain
+bob intent submit-proof <agent-id> <intent-id> --txid <txid>
+
+# Lightning preimage (add invoice for amount verification)
+bob intent submit-proof <agent-id> <intent-id> \
+  --preimage <hex> \
+  --proof-ref <payment-hash> \
+  [--invoice <lnbc...>]
+```
+
+## Import historical proofs (credit building)
+
+For payments that happened before BOB tracking was set up:
+
+```bash
+bob agent credit-import <agent-id> \
+  --preimage <hex> \
+  --proof-ref <payment-hash> \
+  --amount <sats> \
+  --direction inbound \
+  --invoice <lnbc...>
+```
+
+Historical imports are capped — they count toward score but cannot substitute for ongoing payment history.
+
+## How proofs affect BOB Score
+
+- Verified proofs emit `payment.proof_imported.btc` credit events
+- Preimage proofs bound to a BoP (Bound Ownership Proof) attestation earn the highest confidence tier
+- Amount thresholds: floor is 1,000 sats; $10+ payments earn 2× credit delta; $100+ earn 3×
+- Duplicate proof refs are deduplicated — submitting the same txid/hash twice doesn't double-count

package/references/scoring.md

@@ -0,0 +1,43 @@
+# BOB Score — Tiers, Credit Events, and Building History
+
+## Score tiers (0–1000)
+
+| Tier | Range | Spend multiplier |
+|---|---|---|
+| Legendary | 925+ | — |
+| Elite | 800+ | — |
+| Trusted | 650+ | 1.5× limits |
+| Established | 500+ | 1.2× limits |
+| Verified | 400+ | 1.0× limits |
+| New | 300+ | 1.0× limits |
+| Unverified | 150+ | 0.6× limits |
+| Blacklisted | 0+ | 0.6× limits |
+
+New agents start at 350 (Verified tier). Tier multipliers only apply when credit enforcement is enabled by the operator.
+
+## Credit events
+
+Positive events:
+- `agent.activated` +10 — first activation
+- `tx.completed` +1 — successful spend
+- `transfer.sent` / `transfer.received` +1 — agent-to-agent transfer
+- `payment.proof_imported.btc` — varies by proof type and amount
+- `wallet.funded` +1 — wallet received funds
+
+Negative events:
+- `tx.denied` −2 to −3 — policy violation or insufficient balance
+- `payment.denied` −2 — payment blocked
+
+## How to build score fast
+
+1. **Submit payment proofs** — historical and ongoing Lightning/onchain proofs are the highest-signal path
+2. **Complete transactions** — every successful spend adds credit
+3. **Use preimage proofs** — strongest proof type, highest confidence tier
+4. **Consistent counterparty diversity** — varied endpoints/recipients signals healthy economic activity
+
+## Check your score
+
+```bash
+bob agent credit <agent-id>          # score, tier, multiplier, enforcement status
+bob agent credit-events <agent-id>   # full event timeline with deltas
+```