Ucp

# ucp

When a buyer expresses commercial intent — wanting to find, buy, or track products — this is your toolkit. You can search across thousands of merchants via a bundled global catalog, build carts and complete checkouts against any UCP-supporting merchant, and follow up on orders. For merchants that don't support direct transactions, hand off gracefully to the merchant's own flow.

## How to decide what to do

| Buyer says...                                                                 | Do this                                                                                                                                                                      |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Find me X", "I need X for Y", "what's a good X under $Z" — no merchant named | `ucp catalog search` against the global catalog. Each result names its merchant via `seller.domain`.                                                                         |
| "Buy this from \<merchant>" — buyer names a specific merchant                 | `ucp discover --business <url>` first; if it succeeds, transact via `--business <url>`. If it fails, the merchant doesn't speak UCP — tell the buyer and offer alternatives. |
| "Track my order"                                                              | `ucp order get <order_id> --business <url>`                                                                                                                                  |

**Rule of thumb:** broad product discovery → global catalog (no `--business` needed). Business-scoped operations — cart, checkout, order, or catalog scoped to a specific merchant — → pass `--business <url>`. Reach for one or the other based on the buyer's intent.

## Required local setup

Before any merchant-scoped flow — `discover`, cart, checkout, order, or catalog requests with `--business` — ensure a local profile exists.

**If you return a merchant-scoped command to the user, include a profile-init step first unless the user explicitly told you a local profile already exists and is healthy. The profile name is just a local label — `agent` is a fine default, not a required magic value.**

```sh
ucp profile init --name <local-profile-name>
```

`ucp profile init` is idempotent, so prefer doing this before merchant flows instead of waiting for `PROFILE_NOT_FOUND`.

When the user explicitly asks to set up or troubleshoot UCP, or when profile state seems broken, return and run this sequence even if the local profile already looks healthy:

```sh
ucp doctor
ucp profile init --name <local-profile-name>
ucp doctor
```

Do not collapse a setup request into only “you’re already set up” — surface the diagnostic commands in the final response so the user can rerun them later.

Global catalog discovery (`ucp catalog search`) can work without this local setup, so don't block broad search on it unless the user asked for setup.

## Journey heuristics

- **Broad shopping request** → search immediately with useful context. Don't ask clarifying questions first unless the request is impossible or unsafe.
- **Refinement** ("cheaper", "different br