# 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):

```sh
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

```sh
makeables brand from-url --url https://luma.com/<event> --out lovable-meetup
makeables brand from-url --url https://<brand-site-or-brand-kit> --file lovable-meetup/brand.json
makeables 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/`.

```sh
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

```sh
makeables brand add-kit --file brand.json --ref kit.json --id meetup-aqp --family meetups
makeables brand preview --file brand.json
makeables submit --file brand.json --dry-run
makeables 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:

```sh
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

```sh
makeables kit new --name "Friends kit" --out friends.kit.json
makeables kit add --file friends.kit.json --ref sticker.json --id friends
makeables kit add --file friends.kit.json --ref card.json --id card
makeables kit add --file friends.kit.json --ref badge.makeables.json --id badge
makeables kit sheet --file friends.kit.json --ref friends.sheet.json --id a5
makeables 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

```sh
makeables render --file sticker.json --appearance material --out sticker-preview.png
makeables kit render --file friends.kit.json --out friends-preview.png
makeables sheet check --file friends.sheet.json --compact
makeables kit export --file friends.kit.json --out friends.makeables.zip
makeables 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

```sh
makeables submit --file friends.makeables.zip --dry-run --compact
makeables submit --file friends.makeables.zip --title "Friends kit" --credit "Creator" --yes --no-open
makeables 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.