ONE NPUB v2.1 — Agent/LLM Setup Guide
======================================

This file tells you how to unpack, build, and run the ONE NPUB demo.
The tar.gz is self-contained. No external repos needed.

REQUIREMENTS
------------
- Linux (tested on Ubuntu 24.04 arm64 and amd64)
- Docker + Docker Compose v2
- Node.js 22+ (required for native WebSocket)
- pnpm (install via: corepack enable && corepack prepare pnpm@latest --activate)
- python3 (for CLI demo output parsing)
- curl, jq (for CLI demo)

STEP 1: UNPACK
--------------
tar xzf one-npub-v2.1.tar.gz
cd one-npub

STEP 2: INSTALL & BUILD
------------------------
pnpm install
pnpm build

This builds all 8 packages (frost, protocol, nostr, coordinator, signer, dashboard, cli, cold-storage).

STEP 3: BUILD DOCKER IMAGES
----------------------------
docker compose build coordinator agent-a agent-b agent-c agent-d agent-e

This builds the shared Docker image for coordinator and agents.

STEP 4: START RELAY + COORDINATOR
----------------------------------
docker compose up -d relay coordinator

Wait ~15 seconds for both to be healthy.

Verify: curl http://localhost:3333/status | jq .
Expected: {"ok":true,"role":"coordinator","epoch":0,...}

STEP 5: START DOCKER PROXY (on host, not in Docker)
----------------------------------------------------
node docker-proxy.mjs &

This runs on port 3334 and manages agent containers from the browser/CLI.

Verify: curl http://localhost:3334/ps | jq .

STEP 6: OPEN THE DEMO
----------------------
Option A — Browser UI/UX Demo:
  Open http://localhost:3333/demo
  Click through 23 steps.

Option B — CLI Demo:
  bash cli-demo/start.sh          # interactive (press Enter between steps)
  AUTO=1 bash cli-demo/start.sh   # non-interactive (runs all steps)

Option C — Dashboard only:
  Open http://localhost:3333/dashboard

STEP 7: RUN E2E TEST (optional)
--------------------------------
npx playwright install chromium
npx playwright test demo-e2e

Records video. All 23 steps must pass with 0 errors.

PORTS
-----
3333  Coordinator API + Dashboard + Demo UI
3334  Docker Proxy (host-side, for container management)
7777  strfry Relay (WebSocket, NIP-01)

RESET
-----
To reset everything (wipe keys, stop agents, restart coordinator):
  curl -X POST http://localhost:3334/reset

Or from the demo UI: click "Reset Demo" button.

TROUBLESHOOTING
---------------
Problem: "Agent X did not come online"
Fix: Check Docker is running: docker ps
     Check proxy is running: curl http://localhost:3334/ps
     Agent containers need ~15s to boot and register.

Problem: "Coordinator not responding"
Fix: docker compose up -d coordinator
     Wait 15 seconds.

Problem: Build fails with WebSocket errors
Fix: Ensure Node.js 22+. Check: node --version

Problem: Docker permission denied
Fix: Add your user to the docker group: sudo usermod -aG docker $USER
     Then re-login or use: sg docker -c "docker compose ..."

FILE STRUCTURE
--------------
one-npub/
├── packages/           Core code (8 packages)
│   ├── frost/          FROST cryptography (pure math)
│   ├── protocol/       Shared types
│   ├── nostr/          NIP-01 WebSocket transport
│   ├── coordinator/    Coordinator server + API
│   ├── signer/         Agent process (runs in Docker)
│   ├── dashboard/      UI (guided.html + index.html)
│   ├── cli/            CLI tool
│   └── cold-storage/   Backup/recovery
├── cli-demo/           CLI demo (23 bash scripts)
│   ├── start.sh        Main script
│   └── step-XX-*.sh    One script per step
├── tests/              Playwright E2E test
├── report/             PDFs (FAQ, Demo Guide, Report)
├── docker-compose.yml  Docker orchestration
├── Dockerfile          Shared image
├── docker-proxy.mjs    Host container manager
└── README.md           Full documentation

API QUICK REFERENCE
-------------------
GET  /status                    Coordinator status
GET  /signers                   List agents
POST /genesis {"tier":2}        Create 1/1 FROST key
POST /fleet-reshare             Reshare to agents
     {"agentIds":["a","b","c","d"],"k":2}
POST /action/sign               Threshold sign
     {"message":"hello","kind":1}
POST /emergency-lockdown        Revoke all shares
POST /docker/start-agent        Start agent container
     {"agentId":"a"}
POST /docker/stop-agent         Stop agent container
     {"agentId":"a"}
POST /docker/reset              Full reset

LICENSE: MIT — Thomas+Agent21