[aicayzer]

Summary

A new Build guide, Keep files on a device, says how a working copy fetches, keeps, resumes and refuses file bytes, for the CLI and the Swift SDK. Handle files keeps the server side and links to it. Five Build guides come under the 1,500-word limit and lose their ceilings. It also settles the Build parts that batch 4a left from its Catalog issues.

Closes #697
Closes #705
Closes #706
Closes #715
Closes #732
Closes #721

Part of #698: the connector examples' status words are here, status_group is in #754, and the Catalog parts in #755.

Part of #710: Define a type and Change a type are here; the Swift and Raycast tutorials follow in the tutorials pull request.

Changes

• Keep files on a device (new, 966 words): reading bytes through marfa device blobs get and withFile; the file budget; keeping attachments with fetch-kept/fetchKept(); a stopped fetch kept as a partial file and resumed with Range on a new link; the seven-day removal of partial files when the copy is opened, except an attachment's; the refusal codes no_room, storage_full, bytes_absent and decoding; and the attachments-not-held reasons that marfa device status reports, with their JSON values and CLI text. Wired into build/meta.json after Handle files.
• Handle files (1,373, was 1,741): the device material moves to the new guide; the Web Page extraction detail is shortened to what a reader acts on, pointing to Settings for the limits; the TypeScript and Swift examples stay.
• Receive webhooks (1,486, was 1,607), Pull and push (1,498, was 1,609), Holds and retries (1,499, was 1,631) and Keep a copy in sync (1,494, was 1,511): tightened sentence by sentence, with no task or example removed.
• Devices and the Swift SDK's Files page link to the new guide.
• page-limits.json: five ceilings removed.
• Build a connector: the type's icon is the Iconify ID lucide:bookmark-plus, not the bare name the server now refuses.
• Pull and push: the task examples write not_started; core.task no longer declares pending.
• Read a calendar: a task can carry the same recurrence rule, checked and stored but never unfolded, so the listing answers events only.
• Define a type: the receipt's currency field uses the currency format in the definition and the response; the scaffold can't set a field's format; a connector's type reads as a core type through parent, not compatible_with; the icon is an Iconify ID; a link to the naming rule and displays(of:); what metadata.types:write alone may change now includes plural and the labels of kept fields and their entries' members.
• Change a type: the owner's icon links to its own section, and a change to title_field or body_field changes how items are named.

Testing

• pnpm test: 770 passed, including the search test that "attach a file to a note" finds Handle files.
• pnpm build and pnpm exec vite preview: the new guide looked at at 375 px and at the pane's desktop width, tables rendering as cards with no sideways scroll; its .md copy and Handle files' copy read whole.
• Checked against marfa v0.0.50: the fetch rules in conformance/spec/device.md (device/blob-fetch-*, device/bytes-absent, device/blob-hash-checked, device/file-trim-*, device/attachment-kept); the seven-day sweep in core/marfa-core/src/blob.rs (PARTIAL_KEPT, sweep_incoming), run when a writer opens the copy (lib.rs, Core::swept); the reason text in core/marfa-cli/src/device.rs; the device blobs commands in COMMANDS.md; and the Swift calls and error cases in marfa-swift's WorkingCopy.swift and Values.swift.

Notes for reviewers

• Rebased on docs(catalog): describe status words, ranges, entries, labels and names #755; the naming links in Define a type and Change a type now point at /catalog/type-rules#names-and-previews.
• Describe Marfa v0.0.49's type definition keys and icon IDs across the docs #721's other parts are in docs(run): bring deploy, folder and export guides under their limit #756 (Export and restore) and docs(catalog): describe status words, ranges, entries, labels and names #755. Merge docs(run): bring deploy, folder and export guides under their limit #756 with or before this one.
• The Catalog parts of Describe type icons as Iconify IDs from two pinned sets #697, The Task page describes recurrence, and the calendar guide says a task's rule is not unfolded #705, Type rules and Field kinds describe ranges, the currency format and list entry members #706 and Describe field labels, a type's plural and the phone format #715 are in docs(catalog): describe status words, ranges, entries, labels and names #755 and docs(connectors): describe v0.0.8 status words and core fields #757; merge those first or alongside.
• The device reasons were planned as a section of Handle files, but with them the page was 1,750 words, and the device cache is a task of its own. Once docs(content): document type and state lists, the bin and clears #754 merges, the "Its files" line in Write in a working copy should link to the new guide instead of Handle files.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.