Make a kit

A kit is one editable collection of cards, badges, stickers and optional print sheets. A brand is a name, identity and page that groups one or more kits: /brands/<slug>.

Step 0: preflight, for any named brand or event

Run this before the first new, every time the request names a brand, a company, a community or an event (a Luma, Eventbrite or Meetup URL counts):

makeables preflight --json

imageGeneration.ready means ai-cli and a key are present; add --probe to make one small image and catch an invalid key before the run. When it is not ready, use your host's own image tool if you have one and say which. If neither exists, offer npm install --global ai-cli plus an AI Gateway key, and install only with consent. Then ask, in one message, before designing:

1. Art source: official assets only, generated art, or a mix (default: mix).
2. How many stickers (default 6 to 10).

Record the answers in brand.json plan (source, generator, stickers) and list every generated file in plan.generated.

Collect the brand before designing

makeables brand from-url --url https://luma.com/<event> --out lovable-meetupmakeables brand from-url --url https://<brand-site-or-brand-kit> --file lovable-meetup/brand.jsonmakeables brand add-logo --file lovable-meetup/brand.json --ref supplied-logo.svg --id logo-dark

from-url reads public metadata only: the event cover (schema.org image, not the share card), the event date and place, logos and icons, and a starting palette. An event platform's icons are its own, not the brand's: run it again on the brand's site or brand kit page. Script-rendered pages are read through agent-browser when it is installed. Open refs/refs-proof.png and confirm the assets with the user before any piece. If a logo is missing, ask for official files; never redraw a logo or substitute catalog art.

Branded kit recipe

For a named brand or event, the default pack is:

• The event cover as one sticker, when there is a cover.
• At least three logo stickers in different variants (mark, lockup, light, dark).
• Generated art reused across the card and at least one sticker.
• 6 to 10 stickers in total, or the number the user chose; one card.
• One sheet that fits every sticker: sheet pack and sheet check before export.

Start every branded piece blank: new sticker --blank --name <title> or new card --file <art.png>. Catalog styles are structure for unbranded requests only; their artwork, credits, event name and liner never enter a brand's kit. Generated art carries no lettering; place logos as image layers from refs/.

makeables kit check --file kit.json --brand brand.json

Stop on ok:false. It fails when a piece uses images outside the brand refs and plan.generated, uses catalog art, misses the cover or every logo, or has fewer pieces than the plan.

Brand page and publication

makeables brand add-kit --file brand.json --ref kit.json --id meetup-aqp --family meetupsmakeables brand preview --file brand.jsonmakeables submit --file brand.json --dry-runmakeables submit --file brand.json --yes

brand preview serves the local brand to the standard /brands/preview page; nothing is uploaded. brand.json sets name, tagline, description, language (en or es), palette, layout (editorial, poster or grid), logos, cover and families. Every brand uses the same template; there is no custom code. Submitting a brand first submits each unsubmitted kit and records its ID in brand.json, then submits the brand. A Makeables admin approves each kit and then the brand; only then is /brands/<slug> public. The first creator to submit a slug keeps it; later versions from that creator replace the page. Ask the user before --yes. Show a first contact proof early, then a native material mockup and one portable ZIP. Creating, rendering, checking, exporting and reopening require no account.

From supplied artwork

Inspect the source first. Preserve the artwork, colors, proportions and attribution. If it is a raster contact sheet, extract without upsampling:

makeables kit extract --file reference.png --out kit-work --params '{"name":"Friends kit"}' --compact

Open the returned preview before polishing the pieces. The importer removes only background connected to a region boundary; enclosed whites stay intact. Lettering remains raster artwork, not editable vector type. Automatic groups are suggestions: adjust gap (0–40), tolerance, minArea, or supply measured regions: {"regions":[{"x":40,"y":50,"w":300,"h":220,"name":"Friends"}]}. Use a new output directory when revising the extraction. Do not fill every hole in the artwork to create a cut silhouette: the cut renderer handles that separately.

Explain source-quality limits at this first proof. Keep assets.*.sourcePixels when resizing known originals. A previously enlarged image with no provenance cannot reveal its original detail; request masters when the print needs them. New lettering, color blocks and decorative shapes belong in native design layers. Never paint new card text into a bitmap just to make the preview.

Assemble existing pieces

makeables kit new --name "Friends kit" --out friends.kit.jsonmakeables kit add --file friends.kit.json --ref sticker.json --id friendsmakeables kit add --file friends.kit.json --ref card.json --id cardmakeables kit add --file friends.kit.json --ref badge.makeables.json --id badgemakeables kit sheet --file friends.kit.json --ref friends.sheet.json --id a5makeables kit inspect --file friends.kit.json --compact

--ref resolves from the current working directory. Stored kit references resolve beside the kit JSON. Each add validates before saving; stop on ok:false. Kits contain 1–24 pieces and up to four sheets, under 24 MB total. Personalized badges need complete packages containing the agreed portrait and participant. No placeholder person is required for a portrait-free collectible. Preserve creator credits.

Load cards, stickers or sheets only for the piece being made. For image layers, layer add preserves its historical document-relative path default; use --relative-to cwd or an absolute asset path to avoid ambiguity.

Native preview and handoff

makeables render --file sticker.json --appearance material --out sticker-preview.pngmakeables kit render --file friends.kit.json --out friends-preview.pngmakeables sheet check --file friends.sheet.json --compactmakeables kit export --file friends.kit.json --out friends.makeables.zipmakeables kit import --file friends.makeables.zip --out reopened-kit

Static material renders use the same sticker border, glitter and coating as Studio. Do not simulate replacement finishes in Python. Cards and badges use flat artwork in the kit cover; animated lighting, bending and peel remain in Studio.

render --appearance flat is artwork for print; material PNGs are presentation. Sheet cutValid/printable describe geometry, not a guarantee of source quality. Read qualityWarnings: effective DPI uses source dimensions and layer scale, and a sheet's stock/laminate applies to the entire sheet. A mixed digital kit does not instruct a printer to manufacture different substrates on one sheet. Keep the printer's preflight requirements with the PDF.

Deliver the visual mockup, editable ZIP and quality notes together. The ZIP has a validated manifest, member packages, native previews and any included sheet JSON, proof and print PDF. Reopening preserves editable layers and embedded images. Do not substitute an ad hoc ZIP of disconnected files.

Submit the complete kit

makeables submit --file friends.makeables.zip --dry-run --compactmakeables submit --file friends.makeables.zip --title "Friends kit" --credit "Creator" --yes --no-openmakeables submit status --file friends.makeables.zip --title "Friends kit" --credit "Creator"

Publish only after the user approves sharing this exact kit, including every portrait, participant, image and credit it contains. One submission covers all members and sheets, with one review in /admin. pending is awaiting review; approved is public at /kits/<id>. A lost response is recoverable by status or retrying the same package and metadata. Do not submit each member separately.

For opt-in diagnostics, append --trace ./session.jsonl to commands and set MAKEABLES_TRACE_SESSION to an opaque run ID. Traces stay local and contain command names, timing and result codes, never argument values or artwork. --compact returns receipts without flooding the conversation with embedded image bytes.