# Copied preset previews

Source: https://holofolder.com/app/docs/preset-previews

Authenticated discovery and bounded previews of independent ordered target lists.

Preset discovery and previews use the trusted developer key/OAuth boundaries. They return detached goals and never save a collection.

## Discover a starting list

Use `list_storage_presets` through REST `GET /app/api/v1/storage/presets` or the same-named MCP tool. Both require `catalog:read`, `binders:read`, current owner/partner membership and Premium or lifetime access. REST uses a personal API key; MCP uses OAuth. A developer credential is never a first-party cookie session. Read-only credentials can preview without write permission.

Discovery returns stable preset IDs, version `1`, names, supported scope, limitations and explicit finite limits. Use `limit` from 1 to 100 and follow `nextCursor` with the unchanged limit. These are public preset definitions behind authenticated developer access; the operation reads no private inventory, owner planning snapshot, history, certificates or assets.

Supported previews are `blank`, `national-dex`, `generation-1` through `generation-9`, `selected-species` and `selected-printings`. Discovery also lists `set` and `master-set` as unsupported, with the durable checklist-scope limitation. Neither is silently approximated with a species checklist or partial card search.

## Preview ordered targets

`preview_storage_preset` uses REST `POST /app/api/v1/storage/presets/preview` or MCP. It is a read-only operation despite the REST POST body. Supply `presetId` and `version: "1"`. Only `selected-species` accepts `speciesIds`; only `selected-printings` accepts `printings`. Other selection fields are rejected.

Synthetic request example:

```json
{
  "presetId": "selected-species",
  "version": "1",
  "speciesIds": [925, 924, 143]
}
```

Blank returns zero stored entries. National Dex uses the bundled 1,025 species in Dex order; generation presets use the same boundaries as the app. Selected species retain caller order and reject duplicates, unknown IDs and separate form identifiers. An explicit empty selection is valid. The species limit is 1,025. No form-specific or printing expansion is implied.

For selected printings, supply up to 100 ordered `{ cardId, language, finish? }` selections with at most 25 unique exact mirrored row IDs. Repeated printings become separate target requirements with distinct preset entry IDs. Trainers and Energy use the same exact-card contract as Pokémon. Find real IDs with catalog operations; do not invent cards from names, rarity, anniversary labels or species forms. Alias-only identifiers are unsupported; ambiguous direct/alias/canonical evidence fails closed. Language requires a nonempty localized name on that exact row. A requested finish is supported only when its `normal`, `holo`, `reverse` or `jumbo` catalog flag is explicitly true; `reverse_holo` maps to `reverse`. False, missing and unknown flags are unavailable. Rarity and grading do not establish finish availability. Omitted finish stays unconstrained and is disclosed in `unknowns`.

Every preview returns `projection: "copied-preset-preview-v1"`, `completeSnapshot: false`, the selected preset ID/version, detached `manifest`, exact selected `scope`, `targetCount`, `freeSlotCount: 0`, `ownershipCreated: false`, `exclusions` and `unknowns`. Manifest entry order is target order. Its copied `source` and entry IDs supply provenance. Targets are locked goals, not owned items or explicit wants. Free slots may later be inserted anywhere. Completion counts the actual current targets after editing, without an original-preset denominator or automatic catalog subscription.

## Creation and identity boundaries

Copy only `manifest` into the existing immutable creation draft. The outer preview `scope`, exclusions and unknowns are read-time disclosure, not fields persisted by creation. This server preview does not generate set/master-set checklists. Separately, migration 101 enables reviewed `manifest.setScope` persistence through `create_storage_collection`, with saved reads returning `presetManifest`. See [Set checklists](https://holofolder.com/app/docs/markdown/set-checklist-drafts).

Preset entry IDs are provenance labels. They are not collection UUIDs, stable slot IDs or operation IDs. Preview allocates none of those identities and does not return owner attribution. The client must create and retain its operation identity once, then obtain the real current authority/revisions and allocate collection/slot identities once when adapting the draft into the existing canonical creation command. Keep the original command across retries. A preview grants no creation entitlement and is not atomic acceptance, a terminal result, complete planner evidence or a fresh-read queue acknowledgement. See [native storage](https://holofolder.com/app/docs/markdown/native-storage) and [native reads](https://holofolder.com/app/docs/markdown/native-reads).

## Limits and failure

Requests are at most 64 KiB; responses are at most 1 MiB. Each invocation has a 5-second deadline and at most 192 checked requests across current-authority fences and catalog reads, with a cumulative 2 MiB catalog budget. Mirror reads use real 10-row keyset pages, including ambiguity checks, and selected printing targets are revalidated before return. No provider purchase, refresh or sync is triggered. Incomplete, oversized, missing or changed catalog evidence produces no partial manifest. Offline clients may retain a detached preview; fresh discovery/printing evidence requires a connection and preview never saves offline.

Unknown presets return `404 not_found`. Unsupported set/master-set scopes return `422 unsupported_preset_scope`; unavailable or ambiguous printing/language/finish evidence returns `422 preset_catalog_unavailable`. Invalid selections/version/extra fields return `400 invalid_input`; more than 25 unique printings returns `400 preset_scope_too_large`. Budget/deadline exhaustion returns `503 preset_read_unavailable`. Current credential revocation, owner/membership change and entitlement loss remain authoritative. No request flag bypasses current authority checks.