@moonpay/cli 1.79.1 → 1.81.0

package/skills/moonpay-automation-builder/SKILL.md

@@ -1,148 +0,0 @@
----
-name: moonpay-automation-builder
-description: Author new automations for the MoonPay Agents app. Use when the user wants to schedule a recurring task — a daily portfolio email, an hourly price check, a weekly rebalance, a cron-triggered prompt. Automations are JSON entries that fire a prompt or skill on a cron schedule via either the Claude Code or Codex backend. This skill defines the JSON schema, where to write it, and how to pick a sensible cron.
----
-
-# MoonPay Automation Builder
-
-An automation is a saved prompt that the MoonPay Agents app fires on a cron schedule. The first fire spawns a fresh agent session; every subsequent fire `--resume`s the same session so the agent keeps its memory across runs. This is how "every morning, summarize my portfolio" or "every Monday at 9am, run my DCA strategy" actually run.
-
-This skill is how new automations get authored.
-
-## When to use this skill
-
-- The user wants something to run on a schedule, not just one-shot.
-- The user already has a skill or a prompt that works once and wants to run it on repeat.
-- The user describes the trigger with words like "every day", "every Monday", "hourly", "twice a week", "at 9am".
-
-If the user wants a one-shot future action ("remind me at 3pm"), suggest the `schedule` skill instead — that's cloud-side and one-time.
-
-## On-disk format
-
-All automations live in a single file:
-
-```
-~/.moonpay-agents/automations.json
-```
-
-It's a JSON array of automation objects. Each object:
-
-```json
-{
-  "id": "<uuid v4>",
-  "name": "Morning portfolio check",
-  "body": "Run mp portfolio retrieve --json, summarize the top movers since yesterday, and Slack me a 3-bullet update.",
-  "cron": "0 9 * * *",
-  "backend": "claude",
-  "enabled": true,
-  "sessionId": null,
-  "lastRun": null,
-  "lastStatus": null,
-  "lastOutput": null,
-  "createdAt": "2026-05-14T17:00:00Z"
-}
-```
-
-| field | required | notes |
-|---|---|---|
-| `id` | required | UUID v4. Generate one if creating new. |
-| `name` | required | Short label shown in the Automations view. |
-| `body` | required | The prompt the agent runs on each fire. Write it like a normal user message — the agent sees this verbatim. |
-| `cron` | required | 5-field cron: `min hour dom month dow`. See "Picking a cron" below. |
-| `backend` | required | `"claude"` or `"codex"`. Default to `"claude"` unless the user prefers Codex. |
-| `enabled` | optional | Defaults to `true`. Set `false` to author the automation without firing it. |
-| `sessionId` | optional | Leave `null` — the app fills this in after the first fire. |
-| `lastRun`, `lastStatus`, `lastOutput` | optional | Leave `null` — written by the app after each fire. |
-| `createdAt` | required | ISO-8601 timestamp. Use the current time. |
-
-The app reloads `automations.json` on every save, so writing directly to disk works — no IPC needed.
-
-## Picking a cron
-
-The format is the standard 5-field Unix cron: `minute hour day-of-month month day-of-week`. **Day-of-week is 0–6 with 0 = Sunday.**
-
-| Cadence | Cron | Notes |
-|---|---|---|
-| Every minute | `* * * * *` | Don't. Almost always a bug. |
-| Every 5 minutes | `*/5 * * * *` | Polling. Fine for cheap checks. |
-| Every hour on the hour | `0 * * * *` | |
-| Daily at 9am | `0 9 * * *` | Local time of the device running the app. |
-| Every weekday at 9am | `0 9 * * 1-5` | Mon–Fri. |
-| Every Monday at 9am | `0 9 * * 1` | |
-| First of the month at 9am | `0 9 1 * *` | |
-
-The MoonPay Agents app uses a 6-field internal form (`sec min hour dom month dow`) — it prepends `0 ` automatically. Always write 5-field cron in the JSON.
-
-### Cron gotchas
-
-- **Day-of-month + day-of-week are OR'd**, not AND'd. `0 9 1 * 1` fires on the 1st of the month AND every Monday — usually not what people want.
-- **App must be running.** The scheduler is in-process; if the app is closed, the automation doesn't fire. (No launchd integration today.)
-- **Time zone** = local machine time. If the user moves time zones, the cron fires at the same local time, not the same UTC time.
-
-## Writing the `body`
-
-The body is the prompt the agent gets on every fire. Two things to get right:
-
-### 1. Write it like a normal user message
-
-```
-Pull my Polymarket positions with mp polymarket positions list --json. For each position
-where the current price has moved >5% from entry, draft a Slack message to #me with the
-position name, entry price, current price, and PnL.
-```
-
-Not:
-
-```
-Execute polymarket position summary procedure
-```
-
-The agent reads the body the same way it reads a chat message. Be specific about what data to pull, what to do with it, and where to deliver the result.
-
-### 2. Don't recreate skills inline
-
-If the workflow already exists as a skill (`mp skill list`), invoke the skill instead of describing its steps:
-
-> "Use the moonpay-portfolio skill. Compute drift from my target allocation and Slack me a one-line summary if drift > 5%."
-
-This keeps the automation small and lets skill improvements propagate automatically.
-
-### 3. Pick the right backend
-
-- **`"claude"`** for anything that needs nuanced judgment, web research, or long-form output. Default.
-- **`"codex"`** if the workflow is heavily code-modifying (e.g. "regenerate this report HTML and write it to disk") and you want Codex's editing harness.
-
-## Authoring flow (what the agent should do)
-
-When the user invokes you:
-
-1. **Ask three things**:
-   - What should this automation do? (the body)
-   - How often? (the cron — in plain English, you'll convert)
-   - Backend? (default to claude unless they specify)
-2. **Convert the cadence to a 5-field cron** and read it back to the user in plain English ("Every weekday at 9am — `0 9 * * 1-5`") to confirm.
-3. **Read `~/.moonpay-agents/automations.json`** (create the file as `[]` if missing).
-4. **Append a new automation object** with a freshly generated UUID v4, the current ISO-8601 timestamp for `createdAt`, the user's body, the cron, the backend, `enabled: true`, and `null` for `sessionId`/`lastRun`/`lastStatus`/`lastOutput`.
-5. **Write the updated array back** to `~/.moonpay-agents/automations.json`. Pretty-print (2-space indent) — the user may edit it by hand.
-6. **Tell the user**: when the next fire is, the name + cron, and that they can disable/edit it from the Automations view.
-
-## Important rules
-
-- **Never write to `automations.json` without reading it first.** Read → modify → write. Don't blow away other automations.
-- **Always use UUID v4 for `id`** — incrementing IDs collide on import/export.
-- **Use `null`, not `""` or `undefined`**, for the lifecycle fields the app fills in (`sessionId`, `lastRun`, etc).
-- **Don't enable an automation that fires every minute** without warning the user. `*/5 * * * *` is usually the right floor.
-- **Validate the cron** by running it through `cron --validate <expr>` or noting in the response that the app's scheduler will reject invalid expressions on save.
-
-## Common pitfalls
-
-- **Cron means local time.** Users who travel get surprises. Mention it on creation if the cadence is time-sensitive.
-- **First fire is at the next match.** A 9am daily automation created at 10am won't fire until 9am tomorrow. Tell the user the expected next-fire time.
-- **Body is too vague.** "Check my portfolio" produces wildly different output each fire. "Run mp portfolio retrieve --json and Slack me a 3-bullet summary of changes since yesterday" produces consistent output.
-- **App-closed silence.** If a user complains an automation didn't fire, first thing to check: was the app actually running at the scheduled time?
-
-## Related
-
-- **moonpay-skill-builder** — author the underlying skill before scheduling it. Most good automations are "run this skill on a cron".
-- **moonpay-artifact-builder** — for visual recurring reports, pair an automation that updates a JSON file with an artifact that reads it.
-- **`schedule` skill** (cloud-side) — for one-shot future runs ("at 3pm tomorrow, do X"). Different system, persists across app closure.

package/skills/moonpay-onboarding/SKILL.md

@@ -1,171 +0,0 @@
----
-name: moonpay-onboarding
-description: First-run walkthrough for new MoonPay Agents users — sets up a Solana wallet, recommends funding via USDC (fee-free onramp) and SOL (deposit-from-elsewhere), guides the first swap into a tokenized stock (TSLAX, NEURALINK, SPACEX, ANTHRP, OPENAI), then takes them through authoring their first skill, automation, and artifact so they touch every surface of the product in one guided session. Use when the user has just installed the desktop app, says "I just got started", "help me get set up", "what should I do first", or when an empty-state CTA fires this skill.
----
-
-# MoonPay Agents — Onboarding
-
-The user just installed the app and doesn't know what to do first. Walk them through one happy path that touches every surface: wallet → funding → swap → author a skill → schedule an automation → build an artifact. End state: they can describe what each piece does and they have at least one durable thing of their own in each catalog.
-
-**Solana only for v1.** Most of the artifact catalog and the xstock catalog live on Solana — focusing keeps the funnel short.
-
-**Don't dump all six steps on them up front.** Walk one at a time, check in between, let them skip ahead if they want.
-
-## Step 1 — Wallet
-
-```bash
-mp wallet list --json
-```
-
-- **At least one wallet has a Solana address** → surface the name + truncated address (`main-sol · 5Cy8…CGCB`). Skip to Step 2.
-- **No wallets** → ask what to name it (default `main`), then:
-
-```bash
-mp wallet create --name main
-```
-
-The output includes the BIP39 mnemonic. **Surface it once, then tell the user clearly**: write it down or store it in a password manager — anyone with this phrase controls the wallet, MoonPay can't recover it for them.
-
-Pause until they confirm they've saved it.
-
-## Step 2 — Funding
-
-```bash
-mp token balance list --wallet <name> --chain solana --json
-```
-
-Note the response includes native SOL at the top of `items[]` when present (the address is `So11111111111111111111111111111111111111111`, symbol `SOL`).
-
-Branch on what they have:
-
-| State | What to say |
-|---|---|
-| Empty wallet | Two paths: **(a)** Onramp USDC via MoonPay buy link — **this is fee-free right now**, so leading with USDC is the cheapest first dollar in. **(b)** SOL is not fee-free to onramp; if you specifically want SOL, deposit it from an existing wallet or exchange via `mp deposit create --chain solana`. SOL is needed for gas on every transaction, so plan to get at least some. |
-| Some USDC, no SOL | They've got the trading capital but no gas. Generate a SOL deposit link with `mp deposit create --chain solana` and explain SOL is needed for every tx. |
-| Some SOL, no USDC | Funded for gas; recommend onramping USDC (fee-free) for swap capital, OR swap a bit of SOL → USDC right now via the `moonpay-swap-tokens` skill. |
-| Both SOL + USDC | Skip to Step 3. |
-
-For the fiat onramp, hand off to the `moonpay-buy-crypto` skill — it generates the right MoonPay buy URL and opens it in a browser. **Always mention the USDC fee-free angle** when the user is buying stablecoins.
-
-## Step 3 — First position
-
-The point here is to show the agent can do interesting trades, not just hold stablecoins. Start small ($10-50) and **give the user a choice** between a single position and a pre-built portfolio. Don't pick for them.
-
-### Option A — Single tokenized stock
-
-A focused bet on one company. Surface this list and let them pick one:
-
-- **TSLAX** — Tesla
-- **NEURALINK** — Neuralink
-- **SPACEX** — SpaceX
-- **ANTHRP** — Anthropic PreStock
-- **OPENAI** — OpenAI PreStock
-
-Once they choose:
-
-```bash
-mp token search --query <SYMBOL> --chain solana --limit 3 --json
-```
-
-Pluck the address, then hand off to `moonpay-swap-tokens` skill with `from` = USDC and `to` = their pick.
-
-### Option B — Frontier Lab Portfolio
-
-A pre-baked 50/50 split between the two leading frontier AI labs:
-- 50% **ANTHRP** (Anthropic PreStock)
-- 50% **OPENAI** (OpenAI PreStock)
-
-If the user picks this, halve their chosen USD amount and run two swaps via `moonpay-swap-tokens`:
-
-```bash
-# First leg
-mp token swap --wallet <name> --chain solana \
-  --from-token <USDC> --from-amount <HALF> \
-  --to-token <ANTHRP-mint>
-
-# Second leg
-mp token swap --wallet <name> --chain solana \
-  --from-token <USDC> --from-amount <HALF> \
-  --to-token <OPENAI-mint>
-```
-
-After both land, surface the combined position summary: "You now hold $X of ANTHRP and $Y of OPENAI — a Frontier Lab basket on Solana."
-
-### Caveats to call out for either path
-
-These are SPV-wrapped fractional exposure: owning the token gives you price exposure but not voting rights, dividends, or direct ownership in the underlying company. Settlement and price discovery happen on-chain, on Solana.
-
-### After the swap(s) land
-
-Point them at the **Token Deep Dive** artifact in the app — they can search for any of the tokens they just bought and see the chart + market data + their position.
-
-## Step 4 — Author their first skill
-
-Their first user-authored skill. Suggest a portfolio-rebalance skill since it's useful and read-only (no irreversible actions):
-
-Invoke `moonpay-skill-builder`. Walk them through naming it (`my-portfolio-rebalance` is fine) and writing the description. The skill body should:
-
-- Run `mp portfolio retrieve --json` to get the current allocation.
-- Compare against a target allocation the user defines (e.g. 60% USDC, 20% SOL, 20% xstocks).
-- Surface drift per position: which ones are over target (sell candidates), which are under (buy candidates).
-- **Read-only** — don't actually trade. List recommendations only.
-
-After save, the skill lands at `~/.moonpay-agents/.agents/skills/my-portfolio-rebalance/SKILL.md`. Tell the user it'll show up in the **Skills view → Yours** filter on next refresh.
-
-## Step 5 — Schedule it as an automation
-
-Now they have a useful skill — show them how to make it recurring.
-
-Invoke `moonpay-automation-builder`. Recipe:
-
-- **Name**: "Weekly portfolio check"
-- **Body**: "Use the my-portfolio-rebalance skill. Run the drift report for my main-sol wallet."
-- **Cron**: `0 9 * * 1` (Monday 9am local)
-- **Backend**: `claude` (default)
-
-The builder writes the entry into `~/.moonpay-agents/automations.json`. Tell the user it'll show up in the **Automations view** with an inline Switch they can flip if they want to pause it later.
-
-## Step 6 — Build the visualization artifact
-
-Last step — show them the artifact runtime by building a portfolio pie chart.
-
-Invoke `moonpay-artifact-builder`. Recipe:
-
-- **Slug**: `my-portfolio-pie`
-- **Title**: "Portfolio"
-- **What it does**: On load, call `mp portfolio retrieve --json` via `window.mp.run`. Render a Chart.js doughnut chart of holdings by USD value. Use the design-system tokens from the skill (color palette, font-mono for numbers, tabular-nums alignment). Add a refresh button that re-pulls the balances.
-
-The artifact-builder skill has all the design system + bridge contract in its body — let it drive the authoring.
-
-After save it lands at `~/.moonpay-agents/artifacts/my-portfolio-pie.html`. Tell the user it'll show up in the **Artifacts view → Yours** filter.
-
-## Wrap-up recap
-
-End the session with a one-shot summary listing exactly what they now have:
-
-> You're set. Here's what you've got:
-> - **Wallet**: `<name>` (`<truncated-address>`) — your mnemonic is safely stored
-> - **Funded with**: $X USDC + Y SOL
-> - **Position**: $X of <SYMBOL>
-> - **Skill**: `my-portfolio-rebalance` (Skills view → Yours)
-> - **Automation**: "Weekly portfolio check" runs Mondays at 9am (Automations view)
-> - **Artifact**: `my-portfolio-pie` (Artifacts view → Yours)
->
-> From here, try the **Token Deep Dive** artifact for any token, or ask me to set up a price alert, a trailing stop, or another recurring task. Run `mp skill list` to see every skill the agent knows.
-
-## Important rules
-
-- **Never auto-create a wallet without asking** — the mnemonic is a one-time-show secret, the user has to be ready to record it.
-- **USDC fee-free is the only fiat onramp angle worth leading with right now** — don't promise fee-free SOL onramp; it isn't.
-- **Don't skip steps** because you think they're obvious — the whole point is the user touches every surface.
-- **Pause between steps** to let the user ask questions or peel off if they want to dig into one piece.
-- **End with the recap** so the user remembers what they made.
-
-## Related
-
-- `moonpay-auth` — runs before this if the user isn't signed in yet.
-- `moonpay-buy-crypto` — fiat onramp link generation (use this for the USDC-fee-free path).
-- `moonpay-deposit` — crypto deposit links (use this for SOL from existing wallets).
-- `moonpay-swap-tokens` — the actual swap execution in Step 3.
-- `moonpay-skill-builder`, `moonpay-automation-builder`, `moonpay-artifact-builder` — Steps 4, 5, 6.
-- **Token Deep Dive** artifact (in the desktop app) — recommended post-onboarding for exploring tokens.

package/skills/moonpay-skill-builder/SKILL.md

@@ -1,157 +0,0 @@
----
-name: moonpay-skill-builder
-description: Author new agent skills for the MoonPay Agents app. Use when the user wants to teach the agent a new workflow, encode a procedure they keep repeating, or wrap a CLI sequence as a single invokable skill. Skills are markdown files with YAML frontmatter that both Claude Code and Codex pick up natively. This skill defines the contract, the save location, and how to write skills that don't suck.
----
-
-# MoonPay Skill Builder
-
-A skill is a markdown file the agent reads when it decides the user's request matches the skill's description. It's not a function call — it's an instruction set the agent follows. Used well, skills turn a 12-step chat into one prompt; used badly, they're just untested documentation.
-
-This skill is how new skills get authored.
-
-## When to use this skill
-
-- The user has a procedure they've walked the agent through more than twice.
-- The user wants to share an agent workflow with their team.
-- The user wants to wrap a `mp` CLI command sequence (or any other tool sequence) as a single invocable thing.
-
-Don't use this skill for one-off requests or things that are already a single `mp` command — those don't need a skill.
-
-## On-disk format
-
-A skill is a directory. The directory name is the skill slug (kebab-case, must match the frontmatter `name`).
-
-```
-<slug>/
-├── SKILL.md          # Required. Frontmatter + body.
-├── scripts/          # Optional. Helper scripts the skill body calls.
-├── references/       # Optional. Long-form docs the body links to.
-└── templates/        # Optional. Reference files the agent can read or copy.
-```
-
-Only `SKILL.md` is required. Most useful skills stop there.
-
-### `SKILL.md` frontmatter
-
-Both Claude Code and Codex are strict — only **two fields** are portable across both engines:
-
-```yaml
----
-name: my-skill-slug
-description: One paragraph explaining (a) WHEN the agent should invoke this skill, and (b) WHAT it does. The description is the matching surface — write it like a router, not a summary.
----
-```
-
-| key | required | notes |
-|---|---|---|
-| `name` | required | kebab-case slug, matches the directory name |
-| `description` | required | The matching text. See "Writing the description" below — this is the highest-leverage part of the skill |
-
-**Do not add other fields** (`tags`, `category`, `version`, `author`, etc). Codex's docs explicitly state "Do not include any other fields in YAML frontmatter." Claude has its own optional fields (`allowed-tools`, `disable-model-invocation`, `model`, `effort`, `paths`, etc.) but those are Claude-specific — using them breaks portability.
-
-For app-side metadata that the MoonPay Agents app might want (filter chips, icons, etc.), the app derives those from the skill's filesystem location, not from frontmatter. Built-in skills come from the plugin path; user-authored skills come from `.agents/skills/`. No metadata required from the skill itself.
-
-### Save location
-
-Write user-authored skills here:
-
-```
-~/.moonpay-agents/.agents/skills/<slug>/SKILL.md
-```
-
-(The `.agents/skills/` path is Codex-native. The MoonPay Agents app symlinks `.claude/skills` → `.agents/skills` on startup so Claude Code picks them up too.)
-
-Built-in MoonPay skills live under `~/.moonpay-agents/plugins/moonpay/skills/` and are managed by `mp plugin install/update` — don't write there.
-
-## Writing the description
-
-The description is the only thing the agent sees when deciding whether to invoke your skill. Write it like routing logic, not like documentation.
-
-**Good** (specific triggers, concrete verbs, says what it does):
-> Trade on Polymarket — search markets, buy/sell outcome shares, track positions and PnL. Use when the user names Polymarket explicitly, or wants politics, crypto, news, or general-events markets.
-
-**Bad** (vague, no trigger words):
-> Helps with prediction markets.
-
-**Bad** (says what NOT to do without saying what to do):
-> Don't use for Kalshi. Don't use for sports betting. Don't use for…
-
-A good description answers two questions in one paragraph:
-1. **When should the agent pick this skill?** (Specific triggers, user phrases, concrete situations.)
-2. **What will the agent do once it picks it?** (One verb-led sentence: "search…, buy/sell…, track…")
-
-If your description doesn't have at least two trigger phrases the user would actually say, rewrite it.
-
-## Writing the body
-
-The body is what the agent reads after picking the skill. It's read-only context, not executable — the agent decides what to actually do based on what the body says.
-
-### Structure that works
-
-```markdown
-# <Skill Title>
-
-One sentence: what this skill does and the one thing it's good for.
-
-## When to use
-
-Bullet list of concrete situations. Be specific. "When the user mentions X" beats "When relevant."
-
-## Setup (if any)
-
-Commands to run once before the skill's main flow. Skip the section entirely if there's no setup.
-
-## The flow
-
-Numbered steps. Each step:
-- States the goal of the step in one line
-- Shows the exact command(s) with example argv
-- Says what to surface to the user between steps
-
-## Important rules
-
-Bullets of must / never. Use these for things that look optional but aren't (e.g. "Always pass --json", "Never click Pay Now").
-
-## Related
-
-Links to other skills the agent should bounce to.
-```
-
-### Body rules
-
-- **Write commands literally**, with realistic example arguments. The agent will copy-paste them. `mp wallet list` is useful; `mp <whatever wallet command>` is not.
-- **Don't paraphrase tool output.** If the skill processes the output of `mp foo --json`, name the actual fields (`data.items[0].balance`, not "the balance field").
-- **Surface intermediate state to the user.** Between steps, the agent should tell the user what just happened in one line. Write that line in the skill body so the agent doesn't have to invent it.
-- **Pause for confirmation before irreversible actions** — send money, sign tx, push to remote, click Pay. Spell out the pause in the body.
-- **Bail to another skill** if pre-flight fails. Example: `moonpay-card-checkout` bails to `moonpay-card-onboarding` if there's no card yet.
-
-### Body anti-patterns
-
-- **"This skill is helpful for…"** — that's the description's job. The body is for the agent, not the user.
-- **Explaining concepts at length.** If you find yourself writing two paragraphs of background, move it to `references/<topic>.md` and link to it.
-- **Branching trees.** If the skill has 6 if/else paths, it's probably 2 skills.
-- **No examples.** Every command needs at least one concrete example argv.
-
-## Authoring flow (what the agent should do)
-
-When the user invokes you:
-
-1. **Ask what the skill should do** — one paragraph from the user describing the workflow, including the triggers ("when I say X").
-2. **Propose the slug + description back to the user** for confirmation. The description is the highest-leverage part; don't move past this until the user says yes.
-3. **Draft the body** following the structure above. Use real `mp` commands where possible — search `mp --help` if you're unsure.
-4. **Save** to `~/.moonpay-agents/.agents/skills/<slug>/SKILL.md` (create the directory if needed).
-5. **Show the user the saved path** and remind them they may need to restart the chat for the agent to pick up the new skill.
-
-## Common pitfalls
-
-- **Skill is too broad.** "moonpay-helper" with description "helps with MoonPay stuff" will never be selected reliably. Each skill should do one thing.
-- **Skill is too narrow.** "moonpay-buy-eth-on-monday" should just be an automation, not a skill.
-- **Skill description is the same as an existing skill.** Run `mp skill list` first; if there's overlap, edit the existing skill instead of adding a new one.
-- **Skill calls `mp` commands that don't exist.** Run them in a shell first to confirm flags + output shape.
-- **Skill body is a wall of prose.** The agent will read it, but the user won't review it. Keep it tight.
-
-## Related
-
-- **moonpay-artifact-builder** — sibling skill for authoring HTML artifacts (the visual side; this one is the procedural side).
-- **moonpay-automation-builder** — sibling skill for scheduling existing skills on a cron.
-- **`mp skill list`** — see what's already installed before authoring a new one.