@metalntwx/metal-agent 0.2.0 → 0.3.0

package/dist/commands/pay.js

@@ -59,7 +59,7 @@ export async function pay(target, account, url, limit, print, request = {}) {
  */
 export async function payUnderMandate(target, payer, url, print, request = {}) {
     const mandate = await loadMandate(payer.credentialPath);
-    const signDigest = await mandateAgentSigner(mandate, payer.agentKeyPath);
+    const signDigest = await mandateAgentSigner(mandate, payer.credentialPath, payer.mandateKeyFile);
     const paying = createMandatePaymentClient({ credential: mandate.credential, signDigest, network: target.network });
     print(`mandate ${paying.reference}`);
     await paidRequest(target, { ...paying, payer: paying.principal }, url, print, request);

package/dist/help.js

@@ -18,8 +18,8 @@ const COMMANDS = [
     },
     {
         name: "pay",
-        usage: `metal-agent pay <url> ${NETWORK} [--key <file>] [--max <usdz>]\n                  [--method <method>] [--body <text>] [--header 'name: value']...\nmetal-agent pay <url> --mandate <credential> ${NETWORK} [--agent-key <file>]`,
-        about: "Requests the URL and pays its x402 offer in *USDZ. With --key, the agent pays from its own key and refuses, before signing, any offer above --max (1 *USDZ by default). With --mandate, it pays from the owner's account within the mandate's limits, signed by the agent's mandate key, the <credential>.agent-key.json beside the credential unless --agent-key names another. --method (GET by default, POST with a --body), --body (application/json unless a --header names a content type) and each --header are sent again with the payment.",
+        usage: `metal-agent pay <url> ${NETWORK} [--key <file>] [--max <usdz>]\n                  [--method <method>] [--body <text>] [--header 'name: value']...\nmetal-agent pay <url> --mandate <credential> ${NETWORK} [--mandate-key-file <file>]`,
+        about: "Requests the URL and pays its x402 offer in *USDZ. With --key, the agent pays from its own key and refuses, before signing, any offer above --max (1 *USDZ by default). With --mandate, it pays from the owner's account within the mandate's limits, signed by the .key.json file in the credential's directory whose key the credential names, unless --mandate-key-file names another. --method (GET by default, POST with a --body), --body (application/json unless a --header names a content type) and each --header are sent again with the payment.",
     },
     {
         name: "status",
@@ -28,23 +28,23 @@ const COMMANDS = [
     },
     {
         name: "mcp",
-        usage: "metal-agent mcp [--key <file>] [--max <usdz>]\nmetal-agent mcp --mandate <credential> [--agent-key <file>]",
+        usage: "metal-agent mcp [--key <file>] [--max <usdz>]\nmetal-agent mcp --mandate <credential> [--mandate-key-file <file>]",
         about: "Serves pay, fund and status as MCP tools over stdio. What pay spends is fixed here, by whoever starts the server: its key and --max, or one mandate. The model calling the tools reads pages and offers anyone can write, so it can choose no other key, no mandate and no higher limit; under a key, a max it passes can only lower the server's.",
     },
     {
         name: "account create",
-        usage: `metal-agent account create --out <owner key file to create> | --key <owner key file> ${NETWORK}`,
-        about: "Names the owner's Metal account, a smart account the owner's key controls, and prints its address, the --principal of the owner's credentials. It sends nothing: the owner's first bind creates the account on chain. Keep the owner's key where no agent can read it.",
+        usage: `metal-agent account create --out <owner key file> | --key <owner key file> ${NETWORK}`,
+        about: "Creates the owner's Metal account, a smart account the owner's key controls, and prints its address, the --principal of the owner's credentials. The owner's key pays the gas; one that holds none is funded first, from the faucet on testnet. An account that exists is named, and nothing is sent. Keep the owner's key where no agent can read it.",
     },
     {
         name: "mandate credential create",
-        usage: `metal-agent mandate credential create --principal <address> --cap <usdz> --budget <usdz> --out <file>\n                  --key <owner key file> | --issuer-key <file> ${NETWORK}\n                  [--payee <address>[,<name>[,<website>]]]... [--expires-in <seconds>] [--max-occurrences <n>]\n                  [--description <text>] [--agent-key <file>]`,
-        about: "Writes the limits an agent pays within into a credential file: the most per payment (--cap), the most in total over the mandate's whole life (--budget, which never resets), an expiry (--expires-in, 30 days by default) and, when --payee names any, the addresses it may pay, each with an optional name and website. Amounts are in *USDZ, to the cent. The agent's mandate key and the gas key for its pulls are written beside the credential unless --agent-key names a mandate key the agent already has. The keys that sign the credential are the owner's: they live beside the owner's key file, <key>.issuer.json, created on first use, unless --issuer-key names their file.",
+        usage: `metal-agent mandate credential create --principal <address> --cap <usdz> --budget <usdz> --out <file>\n                  --key <owner key file> | --issuer-key <file> ${NETWORK}\n                  [--payee <address>[,<name>[,<website>]]]... [--expires-in <seconds>] [--starts-in <seconds>] [--max-occurrences <n>]\n                  [--description <text>] [--mandate-key-file <file>]`,
+        about: "Writes the limits an agent pays within into a credential file: the most per payment (--cap), the most in total over the mandate's whole life (--budget, which never resets), an expiry (--expires-in, 30 days by default), a start (--starts-in, at once by default) and, when --payee names any, the addresses it may pay, each with an optional name and website. Amounts are in *USDZ, to the cent. The mandate key the agent signs with is written beside the credential, mandate.key.json for --out mandate.json, unless --mandate-key-file names one that exists, as for a replacement. The keys that sign the credential are the owner's: they live beside the owner's key file, <key>.issuer.json, created on first use, unless --issuer-key names their file.",
     },
     {
         name: "mandate bind",
         usage: `metal-agent mandate bind --credential <file> --key <owner key file> ${NETWORK} [--issuer <file>]... [--signer-key <file>]...`,
-        about: "Binds the credential on the owner's account, which then pays under it. The account's quorum signs: --key pays the gas and is the sole signer unless repeated --signer-key names the quorum's keys. --issuer names the issuers whose credentials the owner accepts, the <key>.issuer.public.json beside the owner's key by default.",
+        about: "Binds the credential on the owner's account, which then pays under it. The account's owners sign: --key pays the gas and is the sole signer unless repeated --signer-key names the owners' keys. --issuer names the issuers whose credentials the owner accepts, the <key>.issuer.public.json beside the owner's key by default.",
     },
     {
         name: "mandate replace",
@@ -68,21 +68,22 @@ const COMMANDS = [
     },
     {
         name: "mandate pull",
-        usage: `metal-agent mandate pull --credential <file> --to <address> --amount <usdz> ${NETWORK}\n                  [--key <file>] [--agent-key <file>] [--record-refusal]`,
-        about: "Pays an address the mandate allows, with no seller. The --key account, the agent's gas key by default, submits it and pays its gas. A payout the mandate would refuse is reported and not sent, and the command exits 1; --record-refusal sends it so the refusal is recorded on chain. It prints the transaction as soon as it is sent; if the receipt never arrives, check it with metal-agent status before pulling again.",
+        usage: `metal-agent mandate pull --credential <file> --to <address> --amount <usdz> ${NETWORK}\n                  [--key <file>] [--mandate-key-file <file>] [--record-refusal]`,
+        about: "Pays an address the mandate allows, with no seller. The facilitator submits it and pays its gas, unless --key names a funded key to submit it. A payout the mandate would refuse is reported and not sent, and the command exits 1; with --key, --record-refusal sends it so the refusal is recorded on chain. The outcome is read from the chain: paid, refused, held in the payee's escrow, or pending. A pending pull is kept beside the credential, and running the same command again sends that same pull, which pays at most once.",
     },
     {
         name: "mandate verify",
         usage: `metal-agent mandate verify --credential <file> --issuer <file>... ${NETWORK} [--tx <hash> [--signed-offer <text>]]`,
-        about: "Checks the mandate and every payment under it from the chain alone, or one --tx: the binding, the credential against it and under an --issuer you trust, and each payment as the agent key's signed per-payment mandate. With --signed-offer, the order the agent signed for that payment, as pay printed it. A check that fails exits 1.",
+        about: "Checks the mandate and every payment under it from the chain alone, or one --tx: the binding, the credential against it and under an --issuer you trust, and each payment as the mandate key's signed per-payment mandate. With --signed-offer, the order the agent signed for that payment, as pay printed it. A check that fails exits 1.",
     },
 ];
-const SHARED = `Chain commands also take --rpc-url and --faucet-url, which override
-METAL_RPC_URL and METAL_FAUCET_URL, which override each network's defaults.
+const SHARED = `Chain commands also take --rpc-url and --faucet-url, and mandate pull
+--facilitator-url, which override METAL_RPC_URL, METAL_FAUCET_URL and
+METAL_FACILITATOR_URL, which override each network's defaults.
 On testnet, status, account create and the mandate commands other than
 credential create need an RPC endpoint of your own:
-sign up in the Metal console and create one. account create and the mandate
-commands take --factory <address> when the network's MetalAccountFactory is
+sign up in the Metal console and create one. account create and mandate bind,
+replace, renew, revoke, status and verify take --factory <address> when the network's MetalAccountFactory is
 not the one metal-agent knows.
 
 metal-agent <command> --help explains one command.`;

package/dist/index.js

@@ -9,7 +9,7 @@ import { credentialCreate, accountCreate, mandateBind, mandatePull, mandateRenew
 import { parseHeaders, parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.js";
 import { helpFor } from "./help.js";
-import { DEFAULT_KEY_PATH, agentKeyPath, gasKeyPath, issuerKeyPath, publicKeyPath, readKey } from "./keystore.js";
+import { DEFAULT_KEY_PATH, issuerKeyPath, publicKeyPath, readKey } from "./keystore.js";
 import { mcpAuthority, serveMcp } from "./mcp.js";
 const print = (line) => console.log(line);
 async function main(argv) {
@@ -20,6 +20,7 @@ async function main(argv) {
             network: { type: "string" },
             "rpc-url": { type: "string" },
             "faucet-url": { type: "string" },
+            "facilitator-url": { type: "string" },
             key: { type: "string" },
             factory: { type: "string" },
             "signer-key": { type: "string", multiple: true },
@@ -33,13 +34,14 @@ async function main(argv) {
             credential: { type: "string" },
             replaces: { type: "string" },
             issuer: { type: "string", multiple: true },
-            "agent-key": { type: "string" },
+            "mandate-key-file": { type: "string" },
             "issuer-key": { type: "string" },
             principal: { type: "string" },
             payee: { type: "string", multiple: true },
             cap: { type: "string" },
             budget: { type: "string" },
             "expires-in": { type: "string" },
+            "starts-in": { type: "string" },
             "max-occurrences": { type: "string" },
             tx: { type: "string" },
             "signed-offer": { type: "string" },
@@ -50,6 +52,10 @@ async function main(argv) {
         },
     });
     const [command, sub] = positionals;
+    const extra = positionals.slice(argumentCount(command, sub));
+    if (extra.length > 0) {
+        throw new Error(`unexpected argument${extra.length > 1 ? "s" : ""} ${extra.map((a) => JSON.stringify(a)).join(" ")}; quote a value that holds a space`);
+    }
     if (values.help || command === undefined || command === "help") {
         print(helpFor(command === "help" ? positionals.slice(1) : positionals.slice(0, 3)));
         return command === undefined && !values.help ? 2 : 0;
@@ -57,6 +63,7 @@ async function main(argv) {
     const on = () => target(values.network, {
         rpcUrl: values["rpc-url"],
         faucetUrl: values["faucet-url"],
+        facilitatorUrl: values["facilitator-url"],
     });
     switch (command) {
         case "key":
@@ -74,12 +81,14 @@ async function main(argv) {
             const request = { method: values.method, body: values.body, headers: parseHeaders(values.header, "--header") };
             if (values.mandate !== undefined) {
                 if (values.max !== undefined || values.key !== undefined) {
-                    throw new Error("pay --mandate takes neither --max nor --key: the mandate sets the limit, and the agent's key is --agent-key");
+                    throw new Error("pay --mandate takes neither --max nor --key: the mandate sets the limit, and the agent signs with its mandate key");
                 }
-                const payer = { credentialPath: values.mandate, agentKeyPath: values["agent-key"] ?? agentKeyPath(values.mandate) };
+                const payer = { credentialPath: values.mandate, mandateKeyFile: values["mandate-key-file"] };
                 await payUnderMandate(on(), payer, sub, print, request);
                 return 0;
             }
+            if (values["mandate-key-file"] !== undefined)
+                throw new Error("--mandate-key-file goes with --mandate");
             const limit = { maxAmount: parseMax(values.max, "--max"), raise: "pass --max to allow it" };
             await pay(on(), await readKey(values.key ?? DEFAULT_KEY_PATH), sub, limit, print, request);
             return 0;
@@ -88,7 +97,7 @@ async function main(argv) {
             if (sub !== "create")
                 throw new Error(`unknown account subcommand "${sub ?? ""}"; try: account create`);
             if ((values.key === undefined) === (values.out === undefined))
-                throw new Error("account create needs --out, the owner key file to create, or --key, one that exists");
+                throw new Error("account create needs --out, the owner key file, created when it does not exist, or --key, one that exists");
             const factory = accountFactoryFor(on().network, values.factory === undefined ? undefined : parseAddress(values.factory, "--factory"), "pass --factory");
             await accountCreate(on(), { accountFactory: factory, ...(values.key === undefined ? { out: values.out } : { keyPath: values.key }) }, print);
             return 0;
@@ -116,10 +125,11 @@ async function main(argv) {
                     cap: parseCents(values.cap, "--cap"),
                     budget: parseCents(values.budget, "--budget"),
                     expiresIn: parseCount(values["expires-in"], "--expires-in") ?? 30 * 86_400,
+                    startsIn: parseCount(values["starts-in"], "--starts-in"),
                     maxOccurrences: parseCount(values["max-occurrences"], "--max-occurrences"),
                     description: values.description ?? "A mandate issued by metal-agent",
                     out: need(values.out, "--out"),
-                    agentKeyPath: values["agent-key"],
+                    mandateKeyFile: values["mandate-key-file"],
                     // The keys that sign the owner's credentials are as private as the owner's key: they live beside it.
                     issuerKeyPath: values["issuer-key"] ?? issuerKeyPath(need(values.key, "--key, the account owner's key file, beside which the keys that sign its credentials live, or --issuer-key")),
                 }, print);
@@ -145,14 +155,12 @@ async function main(argv) {
                 await mandateStatus(on(), need(values.credential, "--credential"), accountFactory(), print);
             }
             else if (sub === "pull") {
-                const credentialPath = need(values.credential, "--credential");
-                const agentKey = values["agent-key"] ?? agentKeyPath(credentialPath);
                 const args = {
-                    credentialPath,
-                    agentKeyPath: agentKey,
+                    credentialPath: need(values.credential, "--credential"),
+                    mandateKeyFile: values["mandate-key-file"],
                     to: parseAddress(values.to, "--to"),
                     amount: parsePullAmount(values.amount, "--amount"),
-                    keyPath: values.key ?? gasKeyPath(agentKey),
+                    keyPath: values.key,
                     recordRefusal: values["record-refusal"] === true,
                 };
                 return (await mandatePull(on(), args, print)) === "paid" ? 0 : 1;
@@ -181,6 +189,14 @@ async function main(argv) {
             throw new Error(`unknown command "${command}"\n\n${helpFor([])}`);
     }
 }
+/** How many words a command takes before its options: `key import <file|hex>` and `mandate credential create` three, `mcp` one, the other commands two; any number for `help` and for a command the dispatch then names unknown. */
+function argumentCount(command, sub) {
+    if ((command === "key" && sub === "import") || (command === "mandate" && sub === "credential"))
+        return 3;
+    if (command === "mcp")
+        return 1;
+    return ["key", "fund", "pay", "account", "mandate", "status"].includes(command ?? "") ? 2 : Infinity;
+}
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
     // An endpoint's URL can carry its credential, and this output often lands in an agent's transcript.
     console.error(`error: ${redactUrls(error instanceof Error ? error.message : String(error))}`);

package/dist/keystore.js

@@ -14,16 +14,12 @@ function beside(path, suffix) {
     const ext = extname(path);
     return `${path.slice(0, path.length - ext.length)}.${suffix}${ext}`;
 }
-/** The P-256 key an agent signs payments with under the mandate at `credentialPath`: `mandate.json` to `mandate.agent-key.json`. */
-export const agentKeyPath = (credentialPath) => beside(credentialPath, "agent-key");
+/** The mandate key `credential create` writes beside the credential at `credentialPath`: `mandate.json` to `mandate.key.json`. */
+export const mandateKeyPath = (credentialPath) => beside(credentialPath, "key");
+/** The directory of pulls `mandate pull` sent without an outcome yet, beside the credential at `credentialPath`: `mandate.json` to `mandate.pulls`. */
+export const pendingPullsPath = (credentialPath) => `${credentialPath.slice(0, credentialPath.length - extname(credentialPath).length)}.pulls`;
 /** The keys that sign the owner's credentials, beside the owner's key file and as private as it: `owner-key.json` to `owner-key.issuer.json`. */
 export const issuerKeyPath = (ownerKeyPath) => beside(ownerKeyPath, "issuer");
-/** The funded key that submits the agent's direct pulls and pays their gas, beside its mandate key: `mandate.agent-key.json` to `mandate.gas-key.json`, `shared.json` to `shared.gas-key.json`. */
-export function gasKeyPath(agentKeyPath) {
-    const ext = extname(agentKeyPath);
-    const stem = agentKeyPath.slice(0, agentKeyPath.length - ext.length);
-    return `${stem.endsWith(".agent-key") ? stem.slice(0, -".agent-key".length) : stem}.gas-key${ext}`;
-}
 /** The secp256k1 key at `path`, generated and written there first when the file does not exist. */
 export async function readOrCreateKey(path) {
     if (await exists(path))

package/dist/mcp.js

@@ -7,19 +7,19 @@ import { fund } from "./commands/fund.js";
 import { parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.js";
 import { loadMandate, mandateAgentSigner } from "./commands/mandate.js";
-import { DEFAULT_KEY_PATH, agentKeyPath, readKey } from "./keystore.js";
+import { DEFAULT_KEY_PATH, readKey } from "./keystore.js";
 import { USDZ, formatUsdz } from "@metalntwx/metal-pay";
 import { redactUrls } from "@metalntwx/metal-pay/mandates";
 /** The authority `metal-agent mcp` serves under, from its options. */
 export function mcpAuthority(options) {
     if (options.mandate !== undefined) {
         if (options.key !== undefined || options.max !== undefined) {
-            throw new Error("mcp --mandate takes neither --key nor --max: the mandate sets the limit, and the agent's key is --agent-key");
+            throw new Error("mcp --mandate takes neither --key nor --max: the mandate sets the limit, and the agent signs with its mandate key");
         }
-        return { kind: "mandate", credentialPath: options.mandate, agentKeyPath: options["agent-key"] ?? agentKeyPath(options.mandate) };
+        return { kind: "mandate", credentialPath: options.mandate, ...(options["mandate-key-file"] !== undefined && { mandateKeyFile: options["mandate-key-file"] }) };
     }
-    if (options["agent-key"] !== undefined)
-        throw new Error("--agent-key goes with --mandate");
+    if (options["mandate-key-file"] !== undefined)
+        throw new Error("--mandate-key-file goes with --mandate");
     return { kind: "key", keyPath: options.key ?? DEFAULT_KEY_PATH, maxAmount: parseMax(options.max, "--max") };
 }
 const usdz = (units) => `${formatUsdz(units)} ${USDZ.symbol}`;
@@ -43,7 +43,7 @@ export function createMcpServer(authority) {
     const BUY_RPC = "To buy Metal RPC, POST a JSON-RPC body to the RPC URL; the rpc-aas-endpoint header is the endpoint the payment bought, so send further RPC calls there without paying again.";
     if (authority.kind === "mandate") {
         server.registerTool("pay", {
-            description: `Request a URL and pay its x402 challenge in *USDZ on Metal under this server's mandate: the payment comes from the mandate's account, signed by the agent's key, within the limits its owner set, and a payment outside them is refused with the limit named. Only the owner can change the limits. Returns the settlement transaction hash, the response headers and the body. ${BUY_RPC}`,
+            description: `Request a URL and pay its x402 challenge in *USDZ on Metal under this server's mandate: the payment comes from the mandate's account, signed by the mandate key, within the limits its owner set, and a payment outside them is refused with the limit named. Only the owner can change the limits. Returns the settlement transaction hash, the response headers and the body. ${BUY_RPC}`,
             // Strict: a key or limit the model names is refused, not dropped.
             inputSchema: z.object(request).strict(),
         }, ({ url, network: net, method, body, headers }) => collect((print) => payUnderMandate(target(net), authority, url, print, { method, body, headers })));
@@ -97,10 +97,10 @@ async function collect(run) {
         return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
     }
 }
-/** Serves over stdio. A mandate and its agent key are checked first, so a wrong path fails the host's launch; a key is read when pay needs
+/** Serves over stdio. A mandate and its mandate key are checked first, so a wrong path fails the host's launch; a key is read when pay needs
  * it, so fund and status work without one. */
 export async function serveMcp(authority) {
     if (authority.kind === "mandate")
-        await mandateAgentSigner(await loadMandate(authority.credentialPath), authority.agentKeyPath);
+        await mandateAgentSigner(await loadMandate(authority.credentialPath), authority.credentialPath, authority.mandateKeyFile);
     await createMcpServer(authority).connect(new StdioServerTransport());
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metalntwx/metal-agent",
-  "version": "0.2.0",
-  "description": "The `metal-agent` CLI and MCP server: create or import an agent key, fund it on Metal devnet or testnet, pay x402 offers in *USDZ, look up a settlement, and set spending limits for an agent that Metal enforces.",
+  "version": "0.3.0",
+  "description": "The `metal-agent` CLI and MCP server: create or import the agent's key, fund it on Metal devnet or testnet, pay x402 offers in *USDZ, look up a settlement, and set spending limits for an agent that Metal enforces.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,14 +19,14 @@
   ],
   "dependencies": {
     "@metalntwx/metal-ts": "^0.3.2",
-    "@metalntwx/metal-pay": "^0.2.0",
-    "@modelcontextprotocol/sdk": "1.31.0",
-    "@x402/core": "2.21.0",
+    "@metalntwx/metal-pay": "^0.3.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@x402/core": "2.28.0",
     "viem": "^2.54.6",
     "zod": "^3.25.76"
   },
   "dependencyRationale": {
-    "@metalntwx/metal-ts": "Funds the agent key with a MIP20 transfer, decodes settled transfers, and sends the EIP-7702 delegation a mandate needs.",
+    "@metalntwx/metal-ts": "Funds a key on devnet with a MIP20 transfer.",
     "@metalntwx/metal-pay": "The one-call x402 payment clients, mandates, and the Metal network constants.",
     "@modelcontextprotocol/sdk": "The stdio MCP server behind `metal-agent mcp`.",
     "@x402/core": "Decodes the `payment-response` header a paid request returns.",

package/skills/metal-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metal-agent
-description: "Set up and use the metal-agent CLI to pay x402 sellers on Metal: install it, create or import the agent's account, fund it, pay a URL that answers 402, pay under a mandate from an account the agent does not own, and look up a settlement. Use when a task needs an agent to pay for an HTTP resource in *USDZ on Metal, to pay with a mandate credential the user gives it, to set up metal-agent, or to check what a Metal payment settled."
+description: "Set up and use the metal-agent CLI to pay x402 sellers on Metal: install it, create or import the agent's key, fund it, pay a URL that answers 402, pay under a mandate from an account the agent does not own, and look up a settlement. Use when a task needs an agent to pay for an HTTP resource in *USDZ on Metal, to pay with a mandate credential the user gives it, to set up metal-agent, or to check what a Metal payment settled."
 ---
 
 `metal-agent` is the CLI and MCP server of the `@metalntwx/metal-agent` npm
@@ -71,7 +71,7 @@ Run the steps in order. After each step, show the user its output.
    The tools appear after the host reloads. If you cannot reload it, tell
    the user to, and carry on with the CLI.
 
-5. Get the agent's account. Ask the user whether they have a funded key file. If they do,
+5. Get the agent's key. Ask the user whether they have a funded key file. If they do,
    ask for its path and run `metal-agent key import <path>`. Otherwise run
    `metal-agent key create`. Tell the user the address. If `key create`
    answers that the key file already holds a key, keep that key and ask the
@@ -112,12 +112,12 @@ the user; the limits bind you only while it is not.
 
 ## key create
 
-Generate the agent's account and write its key file. Prints the address
+Generate the agent's key and write its key file. Prints the address
 and the key file's path. It does not overwrite an existing key file; `--out` writes
 another.
 
 ```bash
-metal-agent key create --out ./agent-key.json
+metal-agent key create --out ./key.json
 ```
 
 ## key import
@@ -149,7 +149,7 @@ named network, sign the authorization with the key file, retry, and print
 the settlement, the response headers and the body.
 
 ```bash
-metal-agent pay https://x402-demo-testnet.metalntwx.com/quote --network testnet --key ./agent-key.json
+metal-agent pay https://x402-demo-testnet.metalntwx.com/quote --network testnet --key ./key.json
 ```
 
 Read `transaction <hash>` from the output for the settlement,
@@ -208,14 +208,16 @@ when the mandate names them, the payees.
 metal-agent pay https://example.com/report --mandate ./mandate.json --network testnet
 ```
 
-`--agent-key <file>` names your agent key when it is not the
-`mandate.agent-key.json` beside the credential; `--max` and `--key` do not
+`pay` signs with the mandate key beside the credential, `mandate.key.json`
+for `mandate.json`; `--mandate-key-file <file>` names it when it is
+elsewhere. Never show the key file's contents. `--max` and `--key` do not
 apply. A payment outside the mandate exits 1 with
 `error: payment refused: <reason> (…)`, a reason starting `mandate_`. Tell
 the user which limit it was; only the owner can change a mandate. After
 `mandate_revoked`, ask the user for the credential that replaced it, and
-pay with that. If the error says there is no agent key, pass the
-`--agent-key` it names.
+pay with that. If the error says no key beside the credential is this
+mandate's, ask the user where the key file is, and pass it as
+`--mandate-key-file`.
 
 A seller that asks for your signed order gets it with the payment, and
 `pay` prints it as `signed-offer <text>`. Keep it, and pass it to
@@ -229,13 +231,18 @@ together.
 metal-agent mandate status --credential ./mandate.json --network testnet --rpc-url <endpoint>
 ```
 
-`mandate pull` pays an address the mandate allows, with no seller. The gas
-key beside the credential, `mandate.gas-key.json`, submits it and pays the
-gas, so ask the user to fund its `gas-key-address` first. `outcome paid`, or `outcome refused, not sent` with `reason` and `recorded no` lines,
-says what happened; a pull refused when checked sends nothing and costs no gas. Pass
-`--record-refusal` only when the user asks for the refusal to be recorded
-on chain. If a pull fails after printing `transaction <hash>`, run
-`metal-agent status <hash>` before pulling again; it may have paid.
+`mandate pull` pays an address the mandate allows, with no seller. The
+facilitator submits it and pays the gas. The `outcome` line says what
+happened: `paid`; `refused, not sent` with `reason` and `recorded no`, for
+a pull refused when checked, which sends nothing; `refused` with `reason`,
+for one the account refused and recorded; `refused, not paid`, for a sent
+pull that can no longer land; `held`, for one the payee's
+receive policy sent to escrow, so the payee was not paid; or `pending`. Pass
+`--record-refusal`, with `--key` naming a funded key to send it, only when
+the user asks for the refusal to be recorded on chain. On `outcome pending`,
+run the same command again, with the same `--to` and `--amount`: it sends
+the same pull, which pays at most once, or reports how it ended. Never
+change the amount to pay a pending pull again.
 
 ```bash
 metal-agent mandate pull --credential ./mandate.json --to <payee address> --amount 2.50 --network testnet --rpc-url <endpoint>