# Create and operate a Product

Use the Product's own discovery documents and pinned operation set. Global
catalogs describe what Hyperscale can generate. They do not prove what one
Product can call.

## Credentials and planes

The founder CLI uses a user session for control-plane work such as listing
Blueprints and creating Products. It stores that session outside command
arguments. Product operations, MCP, SDKs, and the create launcher use a Product
API key.

```bash
export HYPERSCALE_API_KEY=<Product API key>
export HYPERSCALE_ENVIRONMENT=sandbox
```

Sandbox and live keys are not interchangeable. Put keys in environment
variables or a secret manager. Do not commit them. Reuse the same idempotency
key when retrying one mutation.

## Mint a Product and SDK project

The published founder CLI can mint a Product from a public Blueprint:

```bash
bunx @hyperscale0/cli auth login --email founder@example.com
bunx @hyperscale0/cli blueprint list --json
bunx @hyperscale0/cli blueprint show vehicle-escrow-marketplace --json
bunx @hyperscale0/cli product create \
  --blueprint vehicle-escrow-marketplace \
  --name "Vehicle Escrow" \
  --json
bunx @hyperscale0/cli key create --name "Founder agent" --json
```

The published CLI checks, plans, and applies a local HSX file through the
Composer contract:

```bash
bunx @hyperscale0/cli compose check company.hsx
bunx @hyperscale0/cli compose plan company.hsx
bunx @hyperscale0/cli compose apply company.hsx --confirm
```

`compose apply` changes the selected Product. An agent may pass `--yes` as the
explicit confirmation form. Check and plan are read-only. Apply runs the same
contract checks again before it creates the new Product build.

After a Product and key exist, scaffold a minimal project against its hosted
TypeScript SDK:

```bash
export HYPERSCALE_API_KEY=<Product API key>
bunx @hyperscale0/create my-product --json
```

The launcher reads the authenticated Product document, pins the hosted SDK
version, writes the Product registry configuration, stores the key in a
gitignored `.env`, and writes `hello.mjs`. It does not create the Product.

## Discover the frozen public surface

First ask the selected Product for its frozen public verbs:

```bash
bunx @hyperscale0/cli product verbs --json
```

Then describe one exact verb when an agent needs its complete schema and
policies:

```bash
bunx @hyperscale0/cli product verbs escrow.release --json
```

The result carries the Build id, Product operation-set digest, Product surface
version, and each public verb's noun, input schema, and idempotency policy. A
legacy Product reports that it has no frozen public verbs. Do not substitute
the legacy catalog for a frozen operation set.

The Product's authenticated `GET /v1/llms.txt` document gives executable
coordinates for the exact Build. It identifies callable operations, routes,
idempotency, MCP reachability, and the hosted TypeScript SDK package. OpenAPI
and the SDK package are machine contracts for the same Build.

Use `ops list --json` to inspect the broader Product operation catalog. Use
`product verbs --json` when the question is which authored business verbs this
Build froze.

## Operate through the CLI

Run a frozen business verb by its discovered name:

```bash
bunx @hyperscale0/cli product run escrow.release \
  --input '{"saleId":"sale_sandbox_..."}' \
  --idempotency-key release-sale-42 \
  --json
```

Run another Product operation by its discovered operation name or id:

```bash
bunx @hyperscale0/cli ops list account --json
bunx @hyperscale0/cli call account.list --input '{"limit":5}' --json
```

The CLI accepts JSON through `--input`, `--input-file`, or standard input.
Pass `--json` for machine-readable output. A mutation gets a generated
idempotency key unless the caller supplies one.

## Connect MCP

The hosted tenant server uses stateless Streamable HTTP at
`https://hyperscale0.ai/v1/mcp`. Send the Product key as a bearer token and the
environment in `x-hyperscale-environment`:

```json
{
  "mcpServers": {
    "hyperscale-product": {
      "type": "http",
      "url": "https://hyperscale0.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${HYPERSCALE_API_KEY}",
        "x-hyperscale-environment": "sandbox"
      }
    }
  }
}
```

The authenticated Product's capability closure determines discovery. Follow
every `nextCursor` from `tools/list` until it is absent.

MCP lists the tools allowed by the authenticated Product's frozen contract,
including eligible mutations. When an operation requires idempotency, its tool
schema adds an optional `idempotencyKey`. Choose one for the first attempt and
reuse it after a lost or uncertain response. If the caller omits it, the server
generates one. If policy requires explicit confirmation, the schema requires
`confirmation` with the exact MCP tool name. Use discovery output instead of
guessing either field or the callable operation set.

## Operate through the SDK

Use the SDK package and version named by the Product's authenticated
`/v1/llms.txt` document or the project created by `@hyperscale0/create`. Do not
guess a package name from the Product title.

The generated SDK contains the callable operations for that Build, typed input
and output models, declared error codes, scopes, idempotency facts, and receipt
expectations. Use the method name recorded beside the operation id in the
Product document. Keep the same idempotency key across retries of one request.

When SDK, MCP, CLI discovery, and an old document disagree, stop. Re-read the
Product's current frozen operation set and authenticated `/v1/llms.txt`, then
bind every call to that Build.