Makeables Wallet

Apply or switch the artwork of an existing iPhone Wallet card, or remove a custom design by restoring its original issuer artwork. This changes artwork, not payment credentials or enrollment. It uses experimental, unofficial device services; compatibility depends on iOS. Apply and restoration have been tested on a Wallet card. On September 30, 2026, companion 0.2.0 restored one card using its original one-shot transport; backup hashes were verified and the user confirmed the appearance. The optimized persistent/batched restore path still needs device validation. This single case does not establish broad compatibility.

Load this guide when the user chooses installation after a card preview, asks to change an existing Wallet skin, or asks to restore it. Speak their language. Creating or approving a design alone does not authorize a phone write. A request to apply that exact design authorizes the write once its target is established; do not add a redundant confirmation.

Install with the fewest steps

Wallet work requires macOS and an iPhone connected over USB, unlocked and trusted. Design/rendering still work on other platforms. Ask only for a missing image or target; never request full payment numbers, credentials or raw resource IDs.

Load this guide directly for an existing artwork installation; no core/cards guide, editor or browser session is needed. Use wallet install --help for command-specific syntax. Reuse the artwork, confirmed target and original-backup receipt from this conversation. Do not rediscover them or ask again.

For a public Makeables card link and an already confirmed saved target:

makeables wallet install --submission "https://makeables.dev/make/card?submission=UUID" --target mercury-4535 --yes --json

--submission accepts the UUID, /make/card?submission=UUID, or /submissions/UUID on makeables.dev. It downloads the complete package directly, validates its manifest and every file hash, and keeps the editable ZIP locally. The source receipt contains a real path, bytes, sha256 and downloadVerified: true. Do not open the browser to export the same public card, wait for browser downloads, or dump inline image bytes into the conversation.

For an unknown target, start the command before asking the user to tap:

makeables wallet install --submission UUID --json# Or use --file card.json, wrapped {design: ...} JSON, portable JSON/ZIP,# complete SVG, or a flat PNG.

This checks and sets up the companion, prepares the complete artwork once, then scans for the card. It does not apply artwork without a target and --yes. The receipt contains a persistent assets directory, preview, local selection handles and a structured next command. Use those exact returned values:

• needs-target: show the saved labels, e.g. “Mercury ••••4535” and “Travel ••••9876”, and ask which one. Continue with returned --assets, --target <alias> --yes. For a different card, use --scan without --yes. Never choose the only/first saved label unless it matches the user's established target.
• needs-device: connect/unlock/trust the iPhone, or choose a listed device. Continue with --assets <returned-path> --device d-SELECTION.
• needs-card: continue the returned selection command. Wait for the live selection-ready progress phase, then ask the user to open Wallet and tap the exact card. If they already opened it, ask them to return to the card list and tap it again while listening. No re-render or second download is necessary.
• needs-selection: inspect preview, establish which detected card the user intended, then install:

makeables wallet install --assets "/returned/prepared/assets" --card c-SELECTION --yes --json

The same readiness rule applies to the initial scan: tell the user to tap only after selection-ready, not after “connecting” or before starting the process. Use the host's asynchronous input capability while that process is alive.

To remember a newly confirmed card, add --remember mercury-4535 --label Mercury --last4 4535 to the selection or apply command. Use only the label and optional four digits the user supplied/confirmed. After a verified successful apply, the alias is bound to that exact original backup. For an established backup, register it without writing to the iPhone:

makeables wallet targets add --target mercury-4535 --backup b-BACKUP --label Mercury --last4 4535 --yes --jsonmakeables wallet targets list --jsonmakeables wallet targets remove --target mercury-4535 --json

Removing an alias preserves its backup. Duplicate aliases are rejected before installation; they never overwrite an existing binding. If the receipt says status: complete and targetSaved: false, the artwork succeeded. Save the label with targets add; do not repeat the write.

If the same card already has an established original backup, skip the scan. For artwork whose complete rendered composition has already been inspected:

makeables wallet install --file next-card.json --backup b-BACKUP --yes --json

Prefer --assets when that exact design is already prepared. Choose the matching backup explicitly when several exist. A reissued card needs a fresh selection and original backup. --yes records the user's request for this design and target, not permission for a different card or future design.

install sets up the checksum-verified macOS companion when needed. It includes Python, native bridges and the image exporter; no source checkout, Python installation or Xcode is needed. wallet doctor is diagnostic, not a mandatory extra step before every install. wallet setup, prep, list and apply remain available for individual steps.

Complete artwork and target identity

Use the saved card JSON, complete package, SVG, or flat PNG. The CLI renders the entire composition to opaque 1536 × 969, then prepares two PNGs and a PDF. Never extract an SVG's embedded background and discard its vectors. Keep chip/logo/details the user requested, check Wallet's lower-left number area, and omit account numbers or cardholder names from the artwork. Use --side back only if that is the selected face. Wallet uses a static image; live shader animation belongs to the studio. To inspect a new composition separately, prepare it once and reuse the resulting directory:

makeables wallet prep --file card.json --out wallet-previewmakeables wallet install --assets wallet-preview --backup b-BACKUP --yes

Open wallet-preview/cardBackgroundCombined@3x.png before that write if the complete render has not yet been inspected. Choose exactly one of --submission, --file or --assets. Choose exactly one of --target, --card or --backup. --device and --seconds are selection flags; do not combine them with a bound target.

Selection handles such as c-... expire after ten minutes. They identify an observed card, not its bank, name or last four digits. If the receipt only says “Observed card 1” (or “Tapped card 1” on older companions), use the user's established target or ask once whether the card they tapped is that target. Never infer bank identity from tap order. If several candidates appear in one event, establish the target or repeat selection; never silently pick the first.

Saved labels and optional four digits have identitySource: user-confirmed. They are local descriptions, not information read from iOS and not live verification. Never infer them from digits printed in the submitted artwork. The helper rechecks the saved backup and device binding during installation.

With a capable companion, install stops scanning after the first identifiable selection event; background cache activity and redacted selections cannot trigger early completion. All candidates from that event are preserved. wallet list --first does the same. wallet list without --first still scans for up to 45 seconds; use it when an exhaustive scan is needed or iOS exposes no identifiable selection event. --seconds changes the maximum. Older companions fall back to the full scan; doctor.capabilities reports first-selection, persistent-media and timed-progress when available. Newer companions also report restore-progress, batched-restore, transport-timing, transaction-timing and saved-receipts. A CLI-only update does not upgrade the companion transport; use its reported capabilities.

The helper verifies device identity, backs up issuer artwork, checks hashes and saves a private visible copy before applying the design. A backup-copy failure stops the artwork write. Existing verified originals are reused instead of backing up the custom skin. Unresolved earlier operations require recovery. Device operations are serialized locally.

Progress and agent execution

Run installation or restoration as one live process with a generous tool timeout. If the host returns a session, wait on that same session in 30–60-second intervals; do not poll every second, restart the command or launch a parallel scan. Forward actual wallet_progress phases and elapsed times: download, setup, prepare, selection, selection-ready, preflight, backup, write, restore, remove-added, refresh, verify. Avoid invented percentages and fixed completion promises. Device time varies; connection reuse reduces overhead but does not establish a sub-30-second guarantee.

CLI JSON receipts are {ok, version, data}: read data.status, not a root status. Only status: complete means the artwork operation finished. New companions also return backupVerified, reusedOriginal, timing, mediaRequests, nextAction: reopen-wallet, a private receipt path and a structured restore handoff with the selected backupId. Keep those returned values for a later user-requested restore. Backup verification is not visual verification of the phone. Ask the user to reopen Wallet and check the appearance.

A selection failure returns reusable assets/preview when preparation finished. deviceWriteAttempted: false allows repeating selection after fixing the connection. If true, or absent on an old companion, preserve backups and inspect the failure before another write. Never turn a timeout into an automatic apply retry.

timing.phases measures helper phases. timing.transports measures AFC, ZIP and AirTraffic work inside those phases; do not add it to the total again. AFC connectionMs and operationMs are parts of AFC elapsed time. ZIP and AirTraffic include their subprocess lifetimes. timing.transactions separates Books snapshots and staging/Books cleanup; these durations overlap with AFC and phase timings too. Failed calls are counted; missing native timings after a failed startup or on an older bridge do not mean zero connection cost. CLI elapsedMs also includes orchestration.

Restore and preserve backups

When the user requests the original artwork, use the established backup from the successful apply receipt directly. Its device/card binding replaces a new selection scan. The existing request authorizes that restore; do not ask the same confirmation again or run doctor/backups as extra mandatory steps.

makeables wallet restore --backup b-BACKUP --yes --json

Restore verifies the original files and the connected device before writing. It restores issuer artwork, not an intermediate custom design. It does not delete the bank card from Wallet. Use this command for “remove skin” or “restore original artwork”; there is no separate uninstall command.

With a capable companion, restore reuses one Media session, removes added artwork in one batch and refreshes each cache directory sequentially. Never parallelize these transactions: they share temporary Books state. Progress follows preflight → restore → remove-added → refresh → verify; phases with no work can be absent. A successful status: restored receipt includes backupVerified, counts of original assets restored/added assets removed/cache files removed, timing, a saved receipt and nextAction: reopen-wallet.

If the target receipt is unavailable or the previous operation is uncertain, inspect the known backup, or list backups and establish the intended target:

makeables wallet backups --backup b-BACKUP --jsonmakeables wallet backups --json

Inspection returns the current backup status and, when available, lastCompletedOperation with its private receipt path. The saved receipt is historical: it does not prove that a later operation did not fail. Check the current backup status before using an old success as evidence. No command automatically chooses the last card or authorizes a future restore.

Original copies live in ~/Documents/Makeables/Wallet Backups/, with private operational state under ~/Library/Application Support/Makeables/Wallet/. They survive CLI updates and companion reinstalls. Keep both locations private and retain originals until the user no longer needs restore. Do not attach backups, IDs, device logs or their contents to chat, public issues or the repo.

Old makeables or drawr-helper installations may have originals under their own backups/cards/ directory. Use an explicit verified path with --backup; do not assume that a new install owns the old backup. A missing original is not permission to invent one or treat the current custom skin as issuer artwork.

Check the result and stop on uncertainty

Only a receipt with status: complete or status: restored is success. Check the returned backup path, then ask the user to force-close/reopen Wallet and confirm the visible result. Keep the design document for future iterations.

A timeout, disconnect or failed command may have changed the device. Preserve every backup and inspect wallet backups plus the private diagnostic path in the error receipt. Do not blindly retry a write. The installed companion includes recovery notes. For a verified transaction snapshot from this version, makeables wallet recover --backup "/absolute/path/to/transaction" --device d-SELECTION --yes restores recorded staging/Books state on the matching device. Inspect the private snapshot and use this only for requested recovery, before another artwork write. Legacy transactions without device binding require their original helper. Report what completed and what remains uncertain.