# Product authoring guide

This guide walks through the founder operations for authoring, composing, and
recomposing a Product. The design rationale for program generators, journeys,
and surface generation lives in the internal surfaces design canon.

## 1. Authoring a program

A founder or agent authors a Product as an HSX program:

```hsx
program vehicle_marketplace "Vehicle marketplace"
use vehicle_listing
use vehicle_escrow
expose vehicle_listing.create as publishVehicle
expose vehicle_escrow.release as releaseSellerPayout
```

- `use` selects an instrument from the published catalog.
- `expose` assigns a public operation name to a selected action.

Authoring text is always HSX. JSON authoring text is rejected at the parser
boundary.

The founder CLI submits source directly to the server:

```bash
hyperscale compose check program.hsx
hyperscale compose plan program.hsx
hyperscale compose apply program.hsx --confirm
```

An agent passes `--yes` instead of `--confirm`. The CLI never compiles
locally. The server compiles against the selected catalog, validates canonical
UDL, and creates the plan.

## 2. What compose freezes

`product.blueprint.compose` creates the sandbox Product and records its first
Product Build. The build is an immutable, digest-addressed snapshot that freezes:

- The tenant catalog revision and program version IDs.
- The HSX source digest, admitted canonical UDL, UDL digest, and origin map.
- The adopted instrument IDs and action projections.
- The resolved capability graph, excluded sandbox capabilities, and surface
  coordinates.
- The plan pricing snapshot.

Compose records the Product Build directly without provisioning runtime
fixtures. Published catalog IDs are immutable reuse points: an authored
instrument reusing a published ID with a conflicting body fails with
`udl_published_instrument_conflict`.

### Key delivery

When the founder session has API-key permission, compose delivers the initial
sandbox API key:

- `key_delivery: "minted"`: the response provides `startKeyId` and `shown_once`
  containing the raw secret. Store it immediately; replays and receipts omit it.
- `key_delivery: "unavailable"`: key minting was omitted, and the response
  provides `shown_once_unavailable_reason: "missing_key_mint_authority"`.

These two states are mutually exclusive in the response contract.

## 3. Recomposing a product

A Product evolves through `product.recompose`. The build history is
append-only: recompose appends a new Product Build and never overwrites an
existing build.

### Adding capabilities

Tenants add features as extensions rather than bare instruments. An extension
bundles instruments with their required references, aggregate conditions, and
prerequisite edges. Adding an extension resolves its dependency closure and
merges the new instruments into the Product.

### Removing capabilities

Subtraction follows a two-phase retire-then-remove rule:

1. **Retire**: The tenant marks the capability retired. New create actions
   refuse with `instrument_retired`. Existing instances continue executing and
   scheduled maintenance continues firing until instances complete.
2. **Remove**: Once all instances reach terminal states and all associated
   accounts hold zero settled and reserved balances, recomposition removes the
   instrument. Recomposition short of a drained state refuses with
   `product_instrument_not_drained`.

The platform never force-closes instances or sweeps balances on its own
authority.

### Standing capability floor

Recomposition preserves standing non-business capabilities. A capability the
Product holds in a standing status (such as deposits, payouts, or beneficiary
verification) survives recomposition even if not explicitly present in the
requested instrument closure. Retired grants, revoked grants, and business
instruments are excluded from this floor.

## 4. Continuing references

- Read the [HSX language reference](https://hyperscale0.ai/agents/references/hsx.md)
  to author source.
- Read the [UDL admission reference](https://hyperscale0.ai/agents/references/udl.md)
  for ABI and document rules.
- Read the [Product operation reference](https://hyperscale0.ai/agents/references/operate.md)
  for CLI, MCP, and generated SDK commands.