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

# 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

# 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

# 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:

# 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:

{
  "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

npm.cmd run check
npm.cmd run build

2. Validate CLI

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

3. Release verification

npm.cmd run release:verify

Publish Flow

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

Post-publish smoke test:

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