docs: lead Step 1 with WebAuth + seed-to-K1 extraction (everyone, not just CLI users)

create-xpr-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-xpr-agent",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Create an autonomous AI agent on XPR Network",
   "type": "module",
   "bin": "./create.mjs",

create-xpr-agent/template/QUICKSTART.md

@@ -25,47 +25,60 @@ Your blockchain private key is **not** a flag. It lives in the proton CLI's encr
 
 ---
 
-## Step 1: Create a XPR Network Account
+## Step 1: Create the agent account at webauth.com
 
-Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots).
+Account names are 1-12 characters (lowercase a-z, digits 1-5, and dots). Create a **fresh, dedicated** account for your agent — don't reuse your personal account.
 
-**Option A: Proton CLI (recommended — gives you a private key directly)**
+1. Go to [webauth.com](https://webauth.com) → create an XPR Network account → pick a name
+2. WebAuth gives you a **12-word seed phrase**. Save it offline (paper, password manager). You'll need it in Step 2.
+3. WebAuth installs a biometric key on the account so you can sign from your phone. The biometric key can't be exported and the agent can't use it for autonomous signing — that's what Step 2 fixes.
+
+> **Tip:** If you already control a funded XPR account on chain, you can create the agent account via the proton CLI instead: `proton account:create myagent`. Skip Step 2 — you already have the `PVT_K1_`. This is uncommon for first-time operators.
+
+---
+
+## Step 2: Extract the K1 private key from your seed phrase
+
+The seed phrase encodes a K1 keypair registered on the agent account's `owner` permission. The agent needs that `PVT_K1_` in plain form so the proton CLI can use it for signing. Pick one path:
+
+**Path A — Explorer utility (desktop)**
+
+1. Open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys)
+2. Find the **"Mnemonic to Private Key"** section
+3. Paste your 12-word seed phrase
+4. Copy the resulting `PVT_K1_...`
+
+**Path B — WebAuth mobile app**
+
+1. Open the WebAuth Wallet app
+2. Select the agent account you just created
+3. Open **Backup Wallet** → reveal / export private key
+4. Authenticate (Face ID / fingerprint) and copy the `PVT_K1_...`
+
+> **Treat the seed phrase and the `PVT_K1_` as equally sensitive** until they're in the proton CLI keychain. Don't paste them into chat, logs, or screenshots. The Pillar 2 lockdown in `./setup-security.sh` (run after `./start.sh`) makes both recoverable if one leaks — but only after that step completes.
+
+---
+
+## Step 3: Load the private key into the proton CLI keychain
 
 ```bash
 npm install -g @proton/cli
 # If `proton: command not found` after install, npm's global bin isn't on PATH:
 #   export PATH="$(npm config get prefix)/bin:$PATH"
-proton chain:set proton-test          # testnet (or proton for mainnet)
-proton account:create myagent         # creates account + key pair
-proton key:list                       # shows the public key + account binding
-
-# Load the private key into the encrypted keychain (interactive)
-proton key:add                        # paste the PVT_K1_ here
+proton chain:set proton              # mainnet (or proton-test for testnet)
+proton key:add                       # paste the PVT_K1_ from Step 2
 
 # Or, if you're running on a hosted/web console that can't drive a TTY:
 echo "no" | proton key:add PVT_K1_yourkey
-```
 
-**Option B: WebAuth Wallet**
-
-1. Go to [webauth.com](https://webauth.com) and create an account
-2. Your account name appears in the wallet (e.g. `myagent`)
-3. WebAuth uses biometrics (Face ID / fingerprint) — the keys can't be exported. To get a `PVT_K1_` key for autonomous agent signing:
-   ```bash
-   npm install -g @proton/cli
-   proton key:generate                  # creates a new PVT_K1_ / PUB_K1_ pair
-   ```
-4. In WebAuth Wallet → **Settings > Keys** → add the `PUB_K1_` public key to your `active` permission
-5. Load the matching `PVT_K1_` into the CLI keychain:
-   ```bash
-   proton key:add                       # paste the PVT_K1_ here
-   ```
+proton key:list                      # verify: shows public key + account binding
+```
 
-> **Security tip:** Create a **dedicated account** for your agent. Don't use your personal account. With the proton CLI keychain, the key lives encrypted on disk (or in plaintext if you run `proton key:unlock` for non-interactive signing) — it never enters the agent process's memory either way.
+The key now lives encrypted on disk. The agent process never reads it — every signed transaction shells out to `proton transaction:push`.
 
 ---
 
-## Step 2: Create Your Agent Project
+## Step 4: Create Your Agent Project
 
 ```bash
 npx create-xpr-agent my-agent
@@ -74,7 +87,7 @@ cd my-agent
 
 ---
 
-## Step 3: Start Your Agent
+## Step 5: Start Your Agent
 
 ```bash
 ./start.sh --account myagent --api-key sk-ant-xxx
@@ -86,7 +99,7 @@ On first run, this downloads the agent runner from GitHub, installs dependencies
 
 ---
 
-## Step 4: Verify It Works
+## Step 6: Verify It Works
 
 ```bash
 # Check agent health

create-xpr-agent/template/README.md

@@ -80,31 +80,29 @@ Get an Anthropic API key at [console.anthropic.com](https://console.anthropic.co
 
 ### Creating an Account & Loading the Signing Key
 
-**Option A: Proton CLI (recommended)**
+The canonical flow:
 
-```bash
-npm install -g @proton/cli
-proton chain:set proton-test          # testnet (or proton for mainnet)
-proton account:create myagent         # creates account + key pair
-proton key:add                        # paste the private key — stored encrypted
-```
-
-The key now lives in the proton CLI's encrypted keychain. The agent will shell out to `proton transaction:push` for every signed action — the key never enters the agent process's memory.
+1. **Create the agent account at [webauth.com](https://webauth.com)** — pick a 1-12 char name (`a-z`, `1-5`, dots). WebAuth gives you a 12-word seed phrase. Save it offline.
+2. **Extract the K1 private key from the seed phrase.** Two paths:
+   - **Explorer utility:** open [`explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys) → "Mnemonic to Private Key" → paste seed → copy `PVT_K1_...`
+   - **WebAuth mobile app:** open the account → "Backup Wallet" → reveal / export private key → copy `PVT_K1_...`
+3. **Load the private key into the proton CLI keychain:**
 
-**Option B: WebAuth Wallet + a separate signing key**
-
-1. Create an account at [webauth.com](https://webauth.com) (biometric login, supports KYC)
-2. WebAuth keys can't be exported. Generate a new key for autonomous signing:
    ```bash
    npm install -g @proton/cli
-   proton key:generate                  # generates a new PVT_K1_ / PUB_K1_ key pair
-   ```
-3. In WebAuth Wallet, go to **Settings > Keys** and add the `PUB_K1_` public key to your account's `active` permission
-4. Load the matching private key into the CLI keychain:
-   ```bash
-   proton key:add                       # paste the PVT_K1_ here
+   proton chain:set proton              # mainnet (or proton-test for testnet)
+   proton key:add                       # paste the PVT_K1_ from step 2
+   # Or for hosted consoles without a TTY:
+   #   echo "no" | proton key:add PVT_K1_yourkey
+   proton key:list                      # verify
    ```
 
+The key now lives encrypted on disk. The agent shells out to `proton transaction:push` for every signed action — the key never enters the agent process's memory.
+
+> **Already have a funded XPR account?** You can create the agent account from the proton CLI instead: `proton account:create myagent`. You'll get the `PVT_K1_` directly — skip step 2. This path only works if you already control a funded creator account; most operators come through the webauth.com path.
+
+> **Pillar 2 lockdown after first boot:** once the agent is running, run `./setup-security.sh` to delegate the agent's `owner` permission to a separate human account. Even if the keychain key ever leaks, an attacker can't rotate you out of the account. See [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md).
+
 > **Security tip:** Create a **dedicated account** for the agent. With the proton CLI keychain, the chain key never enters your `.env` file or the agent process — even if the agent is fully compromised, the attacker cannot leak the key directly.
 
 ## Architecture

docs/SECURITY.md

@@ -89,13 +89,19 @@ permissions:
   active:   threshold 1, keys: [PUB_WA_yyy]          ← WebAuth biometric key
 ```
 
-The K1 key on `owner` is your exportable backup key (Settings → Backup in WebAuth). The `PUB_WA_` key on `active` is biometric — **it cannot be exported**, can only be used from your phone with Face ID / fingerprint, and is therefore **unusable for autonomous signing**.
+The K1 key on `owner` is your exportable backup key. The seed phrase WebAuth gave you during account creation encodes the matching private key. The `PUB_WA_` key on `active` is biometric — **it cannot be exported**, can only be used from your phone with Face ID / fingerprint, and is therefore **unusable for autonomous signing**.
 
-The setup moves the K1 from owner to active so the agent can sign with it via the proton CLI keychain, and replaces owner with your human account's active permission. One atomic transaction so the agent is never in an unsignable mid-state:
+The setup moves the K1 from owner to active so the agent can sign with it via the proton CLI keychain, and replaces owner with your human account's active permission. One atomic transaction so the agent is never in an unsignable mid-state.
+
+First, extract the `PVT_K1_` from your seed phrase via either of these paths:
+
+- **Explorer utility:** open [`https://explorer.xprnetwork.org/wallet/utilities/format-keys`](https://explorer.xprnetwork.org/wallet/utilities/format-keys), find the "Mnemonic to Private Key" section, paste your 12-word seed phrase, copy the resulting `PVT_K1_...`.
+- **WebAuth mobile app:** open the account → "Backup Wallet" → reveal / export private key. Copy the `PVT_K1_...`.
+
+Both paths produce the same K1 — the one currently on `owner`.
 
 ```bash
-# 1. Load the K1 (the one currently on owner) into the proton CLI keychain.
-#    WebAuth → Settings → Backup → reveal your private key, then:
+# 1. Load the K1 (the one currently on owner) into the proton CLI keychain:
 proton key:add                  # paste PVT_K1_yourkey
 
 # 2. Sign one transaction with two updateauth actions: