# Satswarm — Agent playbook

Copy-paste commands for LLM/agent runners.

**Clone first (Gitkey):**

```bash
./bin/gitkey clone \
  https://www.gitkey.dev/r/satswarm/announce.json \
  ./satswarm
cd ./satswarm
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export BASE=http://127.0.0.1:8765
export LUD16=YOU@lexe.app
# optional NWC for paying (never commit / echo the URI):
# export OPEN_SWARM_NWC_FILE=/path/to/nwc.json
```

Exit codes (thick CLI): `0` ok · `1` error · `2` usage/blocked · `3` pay/claim failed.

**Legal:** allowlisted SPDX fixtures only on the site catalog. Local magnets stay local.

---

## 1) Catalog poll (JSON)

```bash
python thick-client/seed_cli.py catalog --api "$BASE" | jq '{count,allowlist,ids:[.items[].id]}'
curl -sS "$BASE/api/catalog" | jq '.items[]|{id,spdx,piece_count}'
```

---

## 2) Seed-to-earn (register lud16 + BT seed)

```bash
python thick-client/seed_cli.py seed \
  --api "$BASE" \
  --fixture legal-torrent-seed \
  --lud16 "$LUD16" \
  --seconds 12 \
  --json | jq '{ok,payee,bittorrent,license_spdx}'
```

Register only (no listen):

```bash
python thick-client/seed_cli.py seed --register-only --fixture legal-torrent-seed --lud16 "$LUD16" --json
```

---

## 3) Pay-per-piece (model stub)

Invoice only (agent shows QR / bolt11 to user):

```bash
python thick-client/seed_cli.py get \
  --api "$BASE" \
  --fixture tiny-lm-demo \
  --piece 0 \
  --invoice-only --json | jq '{ok,invoice_id,amount_sats,payee,memo,bolt11_prefix}'
```

Pay with NWC + claim + save bytes (agent wallet path):

```bash
python thick-client/seed_cli.py get \
  --api "$BASE" \
  --fixture tiny-lm-demo \
  --piece 0 \
  --nwc-file "$OPEN_SWARM_NWC_FILE" \
  --pay --save /tmp/oswarm-piece0.bin --json | jq '{ok,paid,claimed,verified,saved,payee,amount_sats}'
```

Whole-file:

```bash
python thick-client/seed_cli.py get --fixture tiny-lm-demo --whole --invoice-only --json
```

---

## 4) Prove no illegal index

```bash
python thick-client/seed_cli.py seed-local \
  --magnet 'magnet:?xt=urn:btih:deadbeefdeadbeefdeadbeefdeadbeefdeadbeef' \
  --lud16 "$LUD16" --prove-blocked --json | jq '{ok,local_only,site_blocked}'
```

---

## 5) Web UI paths (human / browser agent)

| Path | Demo |
|------|------|
| `/` | Get file · Seed & earn |
| `/stats` | Live catalog + seeders + payments |
| `/tos` | Allowlist + user responsibility |

See [`DEMOS.md`](./DEMOS.md) for evidence paths and expected outcomes.