upload-batch Card

Upload Batch Cards

A bulk upload is a batch of files the boxholder dropped into a box at once (camera-roll batches, document folders — order of dozens of items / ~100 MB). It is delivered to chat as an <upload doc="..." files="N" bytes="..." failed="M"> message — first-class user input, exactly like a <capture>, and a reply is expected. The card groups the whole batch; every uploaded file lives in the card's attach scope ({basename}.attach/), inventoried by that scope's manifest.json.

The card lands under tmp-upload/<batch-slug>/ inside the chat's context dir — a landing zone, not storage (a sibling of capture's tmp-capture/).

Frontmatter:

• status — new (just written) → delivered (the chat message went out). There is no "filed" status: a fully-filed batch is deleted, so a card that still exists still has files to place.
• batch-id — the batch's landing slug.
• time — { start, end? }.
• counts — { registered, received, missing, failed } item tallies.
• total-bytes — server-computed sum of the received files' sizes.
• received — files whose bytes arrived: name (the stored filename, on disk and in the attach manifest), size (server-computed), mimetype (client-claimed — the browser's guess, may be wrong).
• missing — registered items that never arrived (name only; client-claimed).
• failed — items the uploader reported failing, with a reason.
• note — the boxholder's own words, typed in the composer when they sent the batch. This is the batch's introduction: what these files are, or where they should go. Often absent.

Server-computed vs client-claimed: sizes and content hashes (in the attach manifest) are computed here from the actual bytes and are trustworthy. Original filenames and mimetypes are claimed by the client and may lie — trust the bytes over a claimed mimetype when they disagree.

Body — a short generated summary. It is yours to overwrite with filing notes; nothing regenerates it.

Your duties on an upload-batch card, in order:

1. If the batch arrived without introduction, ask first — don't file. When there's no accompanying message explaining what these files are or where they go, ask the boxholder before operating on them. Only file unprompted when the destination is genuinely unambiguous.

   A batch WITH an introduction is not that case — when note is set (it also appears at the top of the <upload> message body), the boxholder has already told you what these files are. Act on what they said instead of asking them to repeat it. Ask only about what their introduction genuinely leaves open, the way you would about any other request.

2. Read the card and its attach manifest, then trust the directory listing over the manifest if they disagree (someone may have hand-moved a file). Inspect files as needed to understand them.

3. File each file, or a coherent group, to its destination: a destination card's attach scope (via the asset-manifest tooling), _content/, or _content/inbox/. Use the file-level tools that actually exist — git mv for tracked files, attach-scope blobs move via the manifest helpers, and bbx mv only for cards/directories (it refuses loose files). Shrink the card's received/missing/failed lists as you place things, and delete the card and its attach dir once everything is placed.

4. tmp-upload/ must not accumulate. A batch left there is unfinished work. If you can't finish in one turn, say so and come back to it — don't leave it silently. A batch you go to file and find already missing was already filed: that's done, not an error — no error theater.

The contains: field

Give this card a one-sentence contains: — the prime retrieval field for bbx search and listings. How to write a good one (carry the information when it's concise, never a list of parts, under 200 characters) is in the agent guide's ABOUT_CARDS section.