@link.me/cli-darwin-x64 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@link.me/cli-darwin-x64",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"description": "Platform binary for @link.me/cli (darwin-x64)",
 	"license": "UNLICENSED",
 	"os": [

package/skills/{agents/cli → linkme-cli}/SKILL.md

@@ -1,11 +1,20 @@
 ---
-name: linkme_cli
-description: Canonical reference for using the Linkme CLI (`linkme`) to manage Linkme profile editing, AP (Post on All Platforms) publishing, analytics, links, forms, gallery, automations, email, and commerce workflows. Other agent-specific skills point back to this file.
+name: linkme-cli
+description: Set up and operate the local `linkme` CLI. Use when MCP tools are unavailable, the binary must be installed, local authentication is needed, a command shape must be discovered, or structured shell output is required.
 ---
 
 # Linkme CLI
 
-This is the canonical skill for operating the Linkme platform through the `linkme` CLI. The per-agent skills under `agents/` (`claude-code`, `codex`, `cowork`, `openclaw`) are thin pointers to this file — read this one for install, auth, output contracts, and the full area reference, then check the per-agent file only for sandbox-specific notes.
+Use this skill for local installation, authentication, output contracts, and command discovery. The client-specific `linkme-cli-*` skills add only sandbox-specific notes.
+
+Route domain work to the focused skill when available:
+
+- profile presentation: `$linkme-polish-profile`
+- social publishing: `$linkme-publish-content`
+- media and attachments: `$linkme-manage-media`
+- traffic reporting: `$linkme-review-analytics`
+- products and orders: `$linkme-manage-commerce`
+- login or connector recovery: `$linkme-recover-auth`
 
 ## Install
 
@@ -65,7 +74,37 @@ Rules of thumb:
 - Use `--json` whenever the output will be parsed, filtered, or fed into another step (`| jq ...`).
 - Use `--quiet` when you only need one id, count, or status value.
 - Use human output for the final summary shown to the user.
-- Discover flags and subcommands with `--help` before acting on anything unfamiliar — do not guess a command shape.
+- Start discovery with `linkme agent schema --areas --json`, then narrow with
+  `linkme agent schema "<area or command>" --json`; do not guess a command
+  shape or scrape formatted help.
+
+## Structured Agent API
+
+Prefer a direct typed command with `--json` for a simple call. When an agent
+control loop wants a single request/response boundary, send a strict request to
+stdin:
+
+```bash
+linkme agent schema --areas --json
+linkme agent schema "analytics overview" --json
+
+printf '%s' \
+  '{"id":"step-1","command":"analytics overview","inputs":{"from":"2026-07-01","to":"2026-07-31"}}' \
+  | linkme agent exec --json
+```
+
+The response always includes `contractVersion`, `ok`, `command`, and
+`exitCode`, then either `data` or `error`. `agent exec` validates unknown
+fields, never evaluates a shell command, never prompts, and preserves the
+underlying CLI exit code. A command whose schema reports
+`safety.approvalRequired: true` is rejected before execution unless the request
+includes `"approval":{"destructive":true}`. Add that approval only after the
+user approves the exact destructive call; also include the command's `force`
+input when its command schema requires one.
+
+Default schema discovery omits internal commands, the advanced raw API escape
+hatch, and product areas outside the current agent scope. Use `--all` only when
+the user explicitly needs one of those existing surfaces.
 
 ## Areas
 
@@ -73,25 +112,27 @@ The authoritative command surface is always `linkme --help`. The table below is
 
 | Area | Covers |
 |------|--------|
+| `agent` | Versioned command schemas and strict JSON execution |
 | `auth` | Login (browser or manual), resume, logout, sessions, profile switching |
 | `ap` | Post on All Platforms: `accounts`, `connect`/`disconnect`, `upload`, `limits`, `analytics` |
 | `ap post` | `create`, `list`, `calendar`, `status`, `watch`, `insights`, `comments`, `publish`, `cancel`, `retry`, `reschedule` |
-| `profile` | View/edit profile, `theme`, `sections`, `contact`, `forms`, `events`, `bands-in-town`, `video`, `pixels`, `linkme-icon`, `deeplink`, `add-to-contacts` |
+| `profile` | View/edit profile, `theme`, `sections`, `contact`, `forms`, `events`, `bands-in-town`, `video`, `pixels`, `linkme-icon`, `link-style`, `deeplink`, `add-to-contacts`, `age-gate`, `vcard` |
 | `links` | Custom + platform links: `list`, `add`, `edit`, `delete`, `reorder`, `set <platform> <url>` / `unset <platform>`, `schedule` |
 | `featured` | Featured links, `headers`, `multilinks` |
 | `gallery` | Upload, list, delete, reorder gallery media |
 | `automations` | Instagram automations: connection, authorize, config, posts, create/update/publish, metrics/analytics/monitor |
-| `courses` | Author courses and lesson video uploads |
+| `courses` | Browse `catalog`, use enrolled `learning`, author courses, and upload local `assets` or lesson `videos` |
 | `contacts` | Collected contacts and stats |
 | `search` | Search Linkme users by username or name |
 | `username` | Check username validity/availability |
 | `waitlist` | Check/join gated feature waitlists |
 | `email` | Templates, sending domains, send/test, history, detail, cancel, upload-image |
-| `analytics` | Overview, visits, links, geo, realtime |
-| `commerce` | Digital products/orders (`products`), print-on-demand merch (`merch`) |
+| `analytics` | Overview, visits, links, geo, realtime, audience demographics, and local-only JSON export |
+| `commerce` | Seller digital products/orders, buyer `purchases`, and print-on-demand `merch` catalog, authoring, AI, mockups, and orders |
+| `creator-finance` | Tips, wallet, payouts, referrals, ambassador status, and billing |
+| `ads` | Permission-scoped campaign/creative reads plus approval-gated ads-admin mutations |
 | `shop` | Physical/storefront products and categories |
-| `agency` | Create agencies, invite/manage members, switch managed-user context |
-| `feeds` | Subscribe to and poll provider feeds |
+| `feeds` | Subscribe to connected provider feeds or a public YouTube channel, then list, poll, or unsubscribe |
 | `reviews` | Subscribe to and inspect review sources |
 | `upgrade` | Generate Linkme Pro upgrade links |
 | `config` | Show/set/reset CLI configuration and profiles |
@@ -100,6 +141,19 @@ The authoritative command surface is always `linkme --help`. The table below is
 
 Note: there is no top-level `social` area. Social network links live under `links` (`links set <platform> <url>`, `links unset <platform>`, and `links list` shows both custom and platform links).
 
+Chat, shouts, notifications, and agency management are outside the current
+agent product scope. Do not infer a content API from a generic profile section
+key. Existing agency CLI commands are compatibility-only and appear in
+`agent schema --all`, not default discovery.
+
+Local-only boundaries:
+
+- Use the local CLI or local stdio MCP for `analytics export`,
+  `courses assets upload`, `courses videos upload`, and file-backed
+  `commerce products create`.
+- On hosted MCP, call `linkme_capabilities` and use only file sources declared
+  by the selected tool. Do not pass a local or sandbox path.
+
 ## Discovery Pattern
 
 ```bash
@@ -115,4 +169,5 @@ Start broad, then drill into the specific area for the task at hand rather than
 - **Read before you write.** For profile-improvement tasks, inspect current state first: `profile`, `links list`, `featured list`, `gallery list`, `profile sections`, `profile theme`, `profile forms`.
 - **Publishing flow.** Connect accounts (`ap connect <provider>`) → create the post (`ap post create`) → confirm with `ap post status <id>` or stream with `ap post watch <id>`.
 - **Reporting flow.** Request `--json`, extract fields with `jq`, and summarize the numbers for the user in human language.
+- **Financial and ads flow.** Inspect state and units first. Require user approval before a billing, payout, credit-consuming, download-allowance, or ad mutation.
 - **Re-read after high-impact writes** (deletes, publishes, schedule changes) to confirm the change landed.

package/skills/linkme-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Linkme CLI"
+  short_description: "Operate Linkme from an agent or script"
+  default_prompt: "Use $linkme-cli to inspect my Linkme account and choose the right command."

package/skills/{agents/claude-code → linkme-cli-claude-code}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: linkme_cli_claude_code
-description: Use the Linkme CLI from Claude Code for Linkme profile editing, AP publishing, analytics, links, forms, gallery, automations, email, and merch workflows.
+name: linkme-cli-claude-code
+description: Configure Linkme access in Claude Code. Use when choosing the bundled MCP server versus local CLI, installing the Claude plugin, handling sandbox file limits, authenticating, or selecting structured output.
 ---
 
 # Linkme CLI for Claude Code
 
-See the canonical **`agents/cli`** skill (`linkme_cli`) for install, authentication, output contracts (`--json`/`--quiet`/human), and the full command-area reference. This file only covers what's specific to running the CLI from Claude Code.
+See the canonical **`linkme-cli`** skill for install, authentication, output contracts (`--json`/`--quiet`/human), and command discovery. This file only covers what's specific to Claude Code.
 
 ## Claude Code Specifics
 
 - This repo ships a Claude Code plugin (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`) that bundles this whole `skills/` tree and an MCP server (`@link.me/mcp`, binary `linkme-mcp`). If the plugin/MCP server is already installed and enabled, prefer its MCP tools over shelling out to `linkme` — they cover the same commands with structured input/output and no subprocess overhead.
-- If the MCP server is not available, fall back to installing and shelling out to the CLI as described in `agents/cli`.
+- If the MCP server is not available, fall back to installing and shelling out to the CLI as described in `linkme-cli`.
 - Use the `Bash` tool for CLI invocations and prefer `--json` output when you intend to parse the result programmatically in the same turn.

package/skills/linkme-cli-codex/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: linkme-cli-codex
+description: Configure Linkme access in Codex. Use when choosing the bundled MCP server versus local CLI, handling local paths or unsupported remote tools, authenticating, or selecting structured output.
+---
+
+# Linkme CLI for Codex
+
+See the canonical **`linkme-cli`** skill for install, authentication, output contracts (`--json`/`--quiet`/human), and command discovery. This file only covers what's specific to Codex.
+
+## Codex Specifics
+
+- Prefer the Linkme MCP tools when the plugin connection is available; they provide structured schemas without shell parsing.
+- Fall back to the local CLI when the task needs a local path, a command is unavailable remotely, or the MCP capability tool says the upload is unsupported.
+- Prefer non-interactive CLI flags: use `linkme auth login --manual` plus `linkme auth resume`, and request `--json` for programmatic reads.

package/skills/linkme-cli-codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Linkme in Codex"
+  short_description: "Operate Linkme safely from Codex"
+  default_prompt: "Use $linkme-cli-codex to choose the right Linkme connection path for this Codex task."

package/skills/{agents/cowork → linkme-cli-cowork}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: linkme_cli_cowork
-description: Use the Linkme CLI from Cowork to manage Linkme profiles, links, publishing, analytics, forms, gallery, email, automations, and shop workflows.
+name: linkme-cli-cowork
+description: Configure Linkme access in Cowork. Use when choosing the bundled MCP server versus local CLI, installing without root, handling ephemeral paths, authenticating, or verifying a remote mutation.
 ---
 
 # Linkme CLI for Cowork
 
-See the canonical **`agents/cli`** skill (`linkme_cli`) for install, authentication, output contracts (`--json`/`--quiet`/human), and the full command-area reference. This file only covers what's specific to running the CLI from Cowork.
+See the canonical **`linkme-cli`** skill for install, authentication, output contracts (`--json`/`--quiet`/human), and command discovery. This file only covers what's specific to Cowork.
 
 ## Cowork Specifics
 
-- Cowork sandboxes usually do not have root, so always install to a local prefix (`npm config set prefix /tmp/npm-global`) as described in `agents/cli`. The executable is `linkme`, not `link.me`.
+- Cowork sandboxes usually do not have root, so always install to a local prefix (`npm config set prefix /tmp/npm-global`) as described in `linkme-cli`. The executable is `linkme`, not `link.me`.
 - Cowork sessions may not persist `PATH` changes across separate task invocations — call `/tmp/npm-global/bin/linkme` directly if a fresh task can't find `linkme` on `PATH`.
 - For publishing workflows, always verify the final state with `linkme ap post status <id>` or `linkme ap post watch <id>` before reporting success to the user.

package/skills/{agents/openclaw → linkme-cli-openclaw}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: linkme_cli_openclaw
-description: Use the Linkme CLI from OpenClaw to manage profiles, publishing, analytics, links, forms, gallery, automations, email, and commerce workflows.
+name: linkme-cli-openclaw
+description: Configure Linkme access in OpenClaw. Use when installing or locating the local CLI, completing manual browser authentication, selecting structured output, or verifying a state-changing Linkme command.
 ---
 
 # Linkme CLI for OpenClaw
 
-See the canonical **`agents/cli`** skill (`linkme_cli`) for install, authentication, output contracts (`--json`/`--quiet`/human), and the full command-area reference. This file only covers what's specific to running the CLI from OpenClaw.
+See the canonical **`linkme-cli`** skill for install, authentication, output contracts (`--json`/`--quiet`/human), and command discovery. This file only covers what's specific to OpenClaw.
 
 ## OpenClaw Specifics
 

package/skills/{email/lists → linkme-email-campaigns}/SKILL.md

@@ -1,12 +1,14 @@
 ---
-name: linkme_email_lists
-description: Use when you need to manage contact-backed email lists, templates, assets, test sends, and campaigns from the Linkme CLI.
+name: linkme-email-campaigns
+description: Create and send Linkme email campaigns backed by collected contacts. Use for audience inspection, templates, image assets, test sends, scheduling, delivery history, or campaign cancellation.
 ---
 
 # Email Lists And Campaigns
 
 Use `linkme email` for templates, assets, test sends, and campaign delivery. Use `linkme contacts` to inspect the audience behind campaigns.
 
+Prefer connected Linkme MCP tools. Their names mirror CLI paths with underscores; use the shell commands below as fallback and discovery examples.
+
 ## Quick checks
 
 - `linkme whoami`

package/skills/linkme-email-campaigns/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Linkme Email Campaigns"
+  short_description: "Build and send Linkme email campaigns"
+  default_prompt: "Use $linkme-email-campaigns to prepare this campaign for my Linkme contacts."

package/skills/{automations/instagram → linkme-instagram-automations}/SKILL.md

@@ -1,12 +1,14 @@
 ---
-name: linkme_automations_instagram
-description: Use when you need to connect Instagram, inspect posts and automations, or create, update, publish, and monitor Linkme Instagram automations from the CLI.
+name: linkme-instagram-automations
+description: Create, inspect, publish, and monitor Linkme Instagram comment and DM automations. Use for Instagram connection, keyword triggers, replies, DMs, activation, metrics, or automation troubleshooting.
 ---
 
 # Instagram Automations
 
 Use `linkme automations` for Instagram comment and DM automations.
 
+Prefer connected Linkme MCP tools. Their names mirror CLI paths with underscores; use the shell commands below as fallback and discovery examples.
+
 ## Quick checks
 
 - `linkme whoami`

package/skills/linkme-instagram-automations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Instagram Automations"
+  short_description: "Build Instagram DM automations"
+  default_prompt: "Use $linkme-instagram-automations to build an Instagram reply and DM workflow."

package/skills/linkme-manage-commerce/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: linkme-manage-commerce
+description: Manage Linkme digital products, storefront products, buyer purchases, and seller orders. Use when creating, editing, pricing, publishing, organizing, inspecting, downloading, or deleting something sold from Linkme outside the print-on-demand merch workflow.
+---
+
+# Manage Commerce
+
+Route the request to the correct catalog before changing anything.
+
+Prefer connected Linkme MCP tools. Their names mirror CLI paths with underscores; use the shell commands below as fallback and discovery examples.
+
+## Choose the catalog
+
+- Digital download or pay-to-unlock content: `linkme commerce products`
+- Seller-side digital sales orders: `linkme commerce products orders`
+- PII-safe seller revenue across digital and physical products:
+  `linkme commerce sales summary`
+- Buyer-side purchases, downloads, or unlocks: `linkme commerce purchases`
+- Physical or print-on-demand storefront item: `linkme shop products`
+- Storefront organization: `linkme shop categories`
+- Print-on-demand catalog, templates, AI designs, or mockups:
+  `$linkme-manage-merch`
+
+Do not represent a merch template as a live storefront product. Do not use `shop` for digital delivery.
+
+## Inspect first
+
+```bash
+linkme commerce products list --json
+linkme commerce products orders --json
+linkme commerce sales summary --json
+linkme commerce purchases list --json
+linkme shop products list --json
+linkme shop categories list --json
+```
+
+Run only the reads relevant to the request. Preserve ids from structured output.
+
+## Create and edit
+
+Create a digital product as a draft:
+
+```bash
+linkme commerce products create \
+  --name "Creator eBook" \
+  --description "A practical launch guide" \
+  --price 19.99 \
+  --file ./ebook.pdf
+```
+
+Publish only after the user has approved the title, description, price, file, and thumbnail:
+
+```bash
+linkme commerce products edit <product-id> --publish
+```
+
+Create a storefront product:
+
+```bash
+linkme shop products add \
+  --name "Tour Poster" \
+  --price 25 \
+  --category "Prints" \
+  --link https://example.com/poster \
+  --image ./poster.jpg
+```
+
+Use `$linkme-manage-media` whenever a product needs a file, thumbnail, or image. Hosted MCP may omit file-backed product creation; check `linkme_capabilities` and use the local CLI when required.
+
+`commerce products create` is available only through the local CLI or local
+stdio MCP because it reads a local product file. Hosted MCP can use only file
+objects explicitly declared by an available tool; never pass it a local or
+sandbox path.
+
+## Purchased content
+
+Inspect an order before requesting access:
+
+```bash
+linkme commerce purchases show <order-id> --json
+```
+
+Create a download or unlock URL only when the user asks to access that
+purchase:
+
+```bash
+linkme commerce purchases download <product-id> <order-id> --json
+linkme commerce purchases unlock <product-id> <order-id> --json
+```
+
+These calls record access, downloads may consume an allowance, and their URLs
+are short-lived and private. Do not fetch, print, or share the URL beyond the
+requested handoff.
+
+## Verify and protect
+
+- Re-read the product or catalog after create, edit, reorder, publish, draft, or delete.
+- Confirm currency and price rather than inferring them from prose.
+- Treat publish and delete as high-impact changes.
+- Treat purchase download and unlock calls as side effects, not harmless reads.
+- Never invent fulfillment URLs, inventory details, customer information, or product files.
+- Summarize orders without exposing unnecessary buyer personal data.
+- Prefer `commerce sales summary` for revenue questions because its DTO omits
+  buyer details and keeps currencies separate. It aggregates unpaginated order
+  feeds locally; do not describe it as conversion attribution or a server-side
+  analytics export.

package/skills/linkme-manage-commerce/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manage Linkme Commerce"
+  short_description: "Manage Linkme products and purchases"
+  default_prompt: "Use $linkme-manage-commerce to manage this Linkme product or purchase safely."

package/skills/linkme-manage-media/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: linkme-manage-media
+description: Upload and reuse media safely across Linkme profiles, galleries, AP posts, email, courses, and products. Use when a task includes an image, video, document, local path, attachment, hosted file, or Linkme object reference.
+---
+
+# Manage Media
+
+Choose the transfer path before invoking a media command. Local CLI and hosted MCP have different access to files.
+
+Prefer connected Linkme MCP tools when their schema supports the asset source. Use the local CLI for same-machine paths and capabilities that the hosted server intentionally omits.
+
+## Determine the runtime
+
+For hosted MCP, call `linkme_capabilities` first and follow its declared file sources, size limit, and video-upload support. Never assume the server can read the agent's local or sandbox path.
+
+For the local CLI, pass a readable local path to the relevant command. Discover accepted types and flags with the command's `--help`.
+
+## Route the asset
+
+| Goal | Local CLI |
+|---|---|
+| Reusable AP video | `linkme ap upload <file>` |
+| Create AP post | `linkme ap post create --video <file-or-ap-key> ...` |
+| Gallery image | `linkme gallery upload <file>` |
+| Profile image | `linkme profile edit --image <file>` |
+| Profile video | `linkme profile video set --file <file>` |
+| Email image | `linkme email upload-image <file>` |
+| Digital product file | `linkme commerce products create --file <file> ...` |
+| Product thumbnail | `linkme commerce products create --thumbnail <file> ...` |
+| Shop product image | `linkme shop products add --image <file> ...` |
+| Course cover | `linkme courses assets upload --kind cover --file <file> --json` |
+| Course attachment | `linkme courses assets upload --kind attachment --file <file> --json` |
+| Course lesson video | `linkme courses videos upload --file <mp4> --json` |
+| AI merch model image | `linkme commerce merch mockups generate <template-id> --model-image <file>` |
+
+Prefer a reusable Linkme or AP object reference when the same asset will be used more than once.
+
+## Hosted MCP rules
+
+- Supply an attachment only through the strict file field exposed by the tool schema.
+- Supply an HTTPS URL only when that tool exposes a URL companion field.
+- Supply an existing Linkme object key only when that tool exposes a reference field.
+- Provide exactly one source for a media input.
+- Treat local paths, `file:` URLs, `data:` URLs, and arbitrary public URLs as unsupported unless capabilities and the tool schema explicitly allow them.
+- For hosted video workflows with proxy uploads disabled, ask for an existing Linkme/AP reference or switch to the local CLI.
+- Course cover, attachment, and lesson-video upload commands are local-only. Do not offer them through hosted MCP.
+- File-backed digital-product creation is local-only. AI merch mockup generation is hosted-capable only through its declared JPEG, PNG, or WebP file field and 8 MiB limit.
+
+## Validate and verify
+
+Before upload:
+
+- confirm the asset belongs to the user and matches the requested destination
+- keep the original filename and MIME type when the host provides them
+- avoid unnecessary re-encoding or quality loss
+- check command help rather than guessing format or size limits
+
+After upload, retain the returned id, key, or URL and re-read the destination. Do not report success until the resulting gallery item, profile field, post, template, or product points to the expected asset.
+
+## Guardrails
+
+- Never turn a sandbox path into a hosted-MCP argument.
+- Never bypass an unsupported video upload by sending an arbitrary URL.
+- Never log attachment download URLs, access tokens, or signed upload URLs.
+- Do not delete or replace existing media without inspecting it and confirming the intended target.

package/skills/linkme-manage-media/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manage Linkme Media"
+  short_description: "Route Linkme uploads safely"
+  default_prompt: "Use $linkme-manage-media to choose the safe upload path for this asset."

package/skills/linkme-manage-merch/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: linkme-manage-merch
+description: Build and manage Linkme print-on-demand merch. Use when browsing the base catalog, opening Design Maker, saving or publishing templates, setting prices, organizing categories, inspecting orders, or generating credit-backed AI designs and mockups.
+---
+
+# Manage Merch
+
+Use `linkme commerce merch` for Printful-backed catalog discovery, creator
+templates, categories, orders, AI designs, and mockups.
+
+Prefer connected Linkme MCP tools. Their names mirror CLI paths with underscores; use the shell commands below as fallback and discovery examples.
+
+Do not use this skill for digital downloads (`$linkme-manage-commerce`) or for
+ordinary physical storefront links (`linkme shop`).
+
+## Browse before authoring
+
+Inspect the base product, variants, stock, sizing, and current creator catalog
+before creating or repricing anything:
+
+```bash
+linkme commerce merch catalog categories --json
+linkme commerce merch catalog products <category-id> --json
+linkme commerce merch catalog show <product-id> --json
+linkme commerce merch catalog sizes <product-id> --json
+linkme commerce merch list --json
+linkme commerce merch show <external-product-id> --json
+linkme commerce merch pricing <external-product-id> --json
+linkme commerce merch orders --json
+```
+
+## Design Maker and publication
+
+For a new base product, create a short-lived Design Maker handoff:
+
+```bash
+linkme commerce merch nonce <external-product-id> \
+  --product-id <catalog-product-id> \
+  --json
+```
+
+For an existing creator template, use `nonce <external-product-id> --edit`.
+The returned URL requires user interaction. After the user completes Design
+Maker and supplies the resulting template id, save it:
+
+```bash
+linkme commerce merch save <external-product-id> <template-id> \
+  --description "Soft heavyweight tee" \
+  --json
+```
+
+Review the exact title, USD price, description, and draft/public state with the
+user before publication:
+
+```bash
+linkme commerce merch publish <external-product-id> \
+  --name "Creator Tee" \
+  --price 29.00 \
+  --description "Heavyweight cotton tee" \
+  --draft \
+  --json
+```
+
+Omit `--draft` only after explicit approval to publish. Re-read `show` and
+`pricing` afterward. Retiring a template is destructive; inspect it first and
+use `retire <template-id> --force` only after explicit approval.
+
+## Categories and ordering
+
+Use `categories`, `category-edit`, `category-reorder`, `assign`, and `reorder`
+to organize existing templates. Read the current order first. Category deletion
+prompts unless `--force` is provided; never bypass that prompt without the
+user's approval.
+
+## AI designs
+
+Check credits and existing designs before starting a job:
+
+```bash
+linkme commerce merch ai credits --json
+linkme commerce merch ai designs --json
+```
+
+`ai generate`, `ai edit`, and `ai upscale` consume credits and run
+asynchronously. Confirm the prompt/source, expected operation, and user
+approval before starting one. Keep the returned job id, poll its matching
+status command, and do not claim success until the job reports completion.
+Treat source URLs and durable generated-image URLs as private user data.
+
+## Mockups and media boundaries
+
+Inspect the current images before generating or selecting replacements:
+
+```bash
+linkme commerce merch mockups list <template-id> --json
+linkme commerce merch mockups ai-list <template-id> --json
+```
+
+A local CLI or local stdio MCP can use a local image:
+
+```bash
+linkme commerce merch mockups generate <template-id> \
+  --model-image ./model.webp \
+  --json
+```
+
+Hosted MCP accepts a declared JPEG, PNG, or WebP attachment up to 8 MiB for
+this tool. It cannot read a local or sandbox path. Call `linkme_capabilities`
+before choosing the source. Generation consumes credits and is asynchronous;
+require approval, preserve the job id, poll `mockups status <job-id>`, and
+verify the selected mockups with `mockups list`.
+
+## Guardrails
+
+- Confirm IDs, variant availability, USD pricing, and current publication state.
+- Do not expose buyer details from merch orders beyond what the task requires.
+- Treat handoff URLs and generated media URLs as short-lived or private.
+- Re-read after save, publish, retire, category, ordering, or mockup mutations.

package/skills/linkme-manage-merch/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manage Linkme Merch"
+  short_description: "Build and manage Linkme merch safely"
+  default_prompt: "Use $linkme-manage-merch to build or update this merch item safely."