StablePay Agent Bootstrap

Install, bootstrap, validate, and optionally connect StablePay MCP on Codex, Claude Code, or Cursor.

StablePay Setup Skill

Use this file as the only required entrypoint. Do not ask for extra docs before starting.

Success Condition

Leave the environment in one of these states:

1. StablePay is installed and doctor works.
2. onboarding is complete and at least one follow-up command works.
3. onboarding is paused on a real external step, and the exact resume command is provided.

Surface Model

• CLI is the bootstrap, repair, and release-validation surface.
• MCP is the ongoing in-agent runtime surface.
• First-time setup: use CLI first.
• After CLI succeeds: optionally add MCP.

First Step: Detect OS

Detect the shell environment before choosing commands.

• Windows PowerShell: prefer npm.cmd and npx.cmd when npm or npx are blocked by execution policy.
• Linux/macOS/WSL: use npm and npx.

Rules

• Use OS-native commands.
• Prefer published-package flow unless the user explicitly wants local-repo validation.
• For published-package flow, prefer npx stablepay-agentpay-dev ....
• For local-repo flow, prefer node ./dist/cli.cjs ....
• Treat onboard --interactive as a loop. Do not stop after the first prompt.
• When onboarding reaches browser-based X verification, stop and wait for the user. This is a human-in-the-loop step.
• Do not try to bypass X verification by searching local source, replaying hidden endpoints, or using mock verification paths.
• Keep user-facing wording focused on meaningful choices, not internal runtime jargon.
• Do not claim MCP is active until config is written or the server is confirmed connected.
• Do not claim the package is release-ready until release verification succeeds.

Platform Notes

• Windows: the npm package and CLI can work even when the local in-process wallet SDK path is unavailable. Do not assume "installed" means "full local wallet runtime is ready".
• Linux/macOS/WSL: standard CLI bootstrap path is expected to work directly.

Published-Package Flow

1. Install or update

bash

# Windows
npm.cmd install -g stablepay-agentpay-dev

# Linux/macOS/WSL
npm install -g stablepay-agentpay-dev

If global install is unnecessary, skip this and use npx directly.

2. Verify CLI

bash

# Windows
npx.cmd stablepay-agentpay-dev doctor

# Linux/macOS/WSL
npx stablepay-agentpay-dev doctor

If this fails because the entrypoint is missing or broken, report it as a packaging failure.

3. Run onboarding

bash

# Windows
npx.cmd stablepay-agentpay-dev onboard --interactive

# Linux/macOS/WSL
npx stablepay-agentpay-dev onboard --interactive

Expected question types:

• create a new wallet or bind an existing one
• wallet identity details
• payment limits
• X verification
• reward status follow-up

Important:

• If X verification is still pending, treat it as a pause point, not a successful completion.
• If the CLI gives a resume session ID or resume command, preserve it and tell the user exactly how to continue.
• At that point, stop autonomous execution. Wait for the user to complete the browser step and return with the verification result or tweet URL.

4. Validate post-onboarding behavior

Run at least one:

bash

# Windows
npx.cmd stablepay-agentpay-dev status
npx.cmd stablepay-agentpay-dev balance
npx.cmd stablepay-agentpay-dev merchant list

# Linux/macOS/WSL
npx stablepay-agentpay-dev status
npx stablepay-agentpay-dev balance
npx stablepay-agentpay-dev merchant list

Balance semantics:

• balance is the StablePay gateway balance for the active DID.
• It is not the wallet app's total asset value.
• It is not the native SOL balance.

5. Optionally configure MCP

Only after CLI bootstrap works:

json

{
  "mcpServers": {
    "stablepay": {
      "command": "npx",
      "args": ["stablepay-agentpay-dev", "mcp"]
    }
  }
}

Local-Repo Flow

Use this only when the user wants to validate the working tree before publish.

1. Build

bash

npm.cmd run check
npm.cmd run build

2. Validate CLI

bash

node ./dist/cli.cjs doctor
node ./dist/cli.cjs onboard --interactive
node ./dist/cli.cjs status

3. Release verification

bash

npm.cmd run release:verify

Publish Flow

bash

npm.cmd version patch
npm.cmd run release:verify
npm.cmd publish --access public

Post-publish smoke test:

bash

npx stablepay-agentpay-dev doctor
npx stablepay-agentpay-dev onboard --interactive
npx stablepay-agentpay-dev status

Failure Classification

Packaging failure

Examples:

• npx cannot find the command
• bin entry is missing
• dist/cli.cjs is missing from the package

Report:

• failed command
• concrete packaging symptom
• whether the local repo path still works

Runtime failure

Examples:

• wallet runtime unavailable
• onboarding cannot continue because no usable wallet path exists

Report:

• CLI is installed or not
• which layer is blocked
• OS context

Backend or network failure

Examples:

• doctor reaches local runtime but remote APIs fail
• balance, reward, registration, or merchant calls fail

Report:

• local CLI state
• failing remote-facing step
• exact command that failed

External-verification pause

Examples:

• X verification must be completed in the browser before onboarding can continue
• user must manually open the verification page and finish the external step

Report:

• onboarding reached a real pause point
• what the user must do next
• exact resume command

Completion Format

Report in compact operator style:

1. OS detected
2. flow used: published package or local repo
3. whether onboarding completed or paused
4. which validation command succeeded
5. whether MCP was configured
6. remaining step, if any

Example:

OS: Linux / WSL2
Flow: published package
Onboarding: paused at X verification
Validation: status works
MCP: not configured
Next step: complete X verification, then resume onboarding with the saved session