# Documents and papers A document is anything you keep with the boat's record: a manual, a receipt, a survey, the insurance certificate, a photo of a serial plate, a link to a supplier's page. This chapter covers what a document holds, how it is attached to the records it concerns, how the boat's papers are shown, and what happens to a file between your phone and the server. Checklists, which sit beside documents in the Boat area, close the chapter. ## What a document is {#what-a-document-is} A document is a record with a title and a type. It holds one of three things: - **A file** uploaded from the device: a PDF, a photo, a spreadsheet, anything up to 25 MB. - **A link** to something kept elsewhere, an `http` or `https` address. - **Nothing yet**, only its details. A file can be added later. A document never holds a file and a link at once. When the add form is given both, the file is kept and the link dropped. The edit form offers Link only while the document has no file. A document also has an optional date it was captured or issued, an optional **expiry** (reported on Today as it approaches, see [Expiry on Today](#expiry-on-today)), **tags** typed comma separated, a **description**, and the records it is **attached to** (see [Attaching](#attaching)). The Documents search looks at the title, the type, the tags, the description and the names of what it is attached to. ### The types {#types} Photo, Manual, Receipt, Warranty, Certificate, Registration, Insurance, Ownership, Licence, Survey, Inspection, Service record, Link, Note and Other. A new document is Other until you choose. Registration, Insurance, Ownership and Licence are the boat's papers; Certificate and Survey can be (see [The boat's papers](#papers)). The add and edit forms' Type list spells the first one "Photograph"; every other screen says "Photo". ## Adding a document {#adding} Three ways in, one form, **Add document**: - **The Documents page** in the Boat area: Add document beside the title, or the empty page's button. - **The Record menu** in the top bar: Add a document. The search box has the same action under the same name. - **A record's Documents section**: Attach a document. The new document is already attached to that record. The form asks **Title**, **Type** and **Upload file** first, because that is what a capture at the boat needs. **More details** holds Attach to, Captured / issued, Expires, Link, Tags and Description, and stays open for the rest of the session once opened. The button says "Save & upload" with a file and "Add document" without one. Offline, the form says the file is kept on the device until it can upload. ### Size and photos {#size-and-photos} | Limit | Value | |---|---| | Largest file | 25 MB | | A photo's longer side, after shrinking | 2,560 px | | The boat's photo's longer side | 1,600 px | | Records one document can be attached to | 50 | **A photo is made smaller on the device before it is saved.** A phone camera's picture is often over 25 MB, so the app redraws it as a JPEG with its longer side at most 2,560 px, still readable for a receipt or a manual page. A photo already that small, or one that would not get smaller, is kept as it is. - **A HEIC photo** (an iPhone's own format) is always made a JPEG, because most browsers cannot show one. Chrome and Firefox need a decoder, which the app downloads the first time you add one. - **A large photo or a HEIC** shows "Preparing the photo…" while it is redrawn, which can take several seconds. - **A GIF and an SVG** are never redrawn. - **A photo the browser cannot read** (a RAW `.dng`) is kept as it is; over 25 MB, the save is refused with a message naming the kind of file and saying to save it as a JPEG, and the form stays open. - **Any other file over 25 MB** is refused: "That file is larger than 25 MB. Choose a smaller one." ## Attaching {#attaching} One document can be attached to many records, and a record can have many documents. The engine manual is attached to the engine; the invoice for an impeller change to the job, the engine and the expense. A document attaches to the boat, equipment, an item, a plan, a job, a trip, a problem, a project, an expense or a person. **A document attached to nothing is one of the boat's own documents.** Its row on the Documents page names no record, and its page says "Nothing: it is one of the boat's own documents." Attaching it to the boat means the same. - **In the document's form**, Attach to (inside More details when adding) shows each attached record as a chip naming its kind and name; the chip's × removes it. The search field below finds any active record by name. - **On a record's page**, the **Documents** section offers **Attach a document** (a new one) and **Attach existing…**, a search over the documents not attached yet, by title or type. - **Detach** is in each document row's More menu in a record's Documents section, and in the document page's Attached to list. It removes the link; the document stays. A record can be attached to a document only once. A newly attached record must be active; one archived after it was attached stays attached, marked archived. **An attached document keeps its record from being deleted.** Deleting equipment that a manual is attached to is refused until the manual is detached. Archiving is not affected. ## The boat's papers {#papers} Boat details (opened from the boat's name at the top of the sidebar or the phone's header) has a **Papers** section. It is a view of your documents: a paper is a document. - **Four fixed slots**, Registration, Insurance, Ownership and Licence. Every active document of one of those types fills its slot, whatever it is attached to. An empty slot says "Not added" with **Add**, which opens Add document with that type chosen. - **Other papers**: every certificate and survey attached to nothing but the boat. A certificate attached to the life raft is the life raft's and is not listed. - **Add a paper** opens Add document with Registration chosen. - **Each row** shows the type and the expiry ("Expires 3 May 2027", or "Expired …" in the attention colour), sorted soonest first, and opens the document's page. ### Expiry on Today {#expiry-on-today} Today reports **any** active document with an expiry, a paper or not. | Expiry | On Today | Says | |---|---|---| | Passed | Do first | "Document has expired" | | Within 30 days | Do first | "Expires 3 Oct" | | Within 90 days | Soon | "Expires 3 Oct" | An expiry date is stored as 09:00 on that day, and the document counts as expired from that moment. The row opens the document's page. ## A document's page {#document-page} Every way to a document opens its page: the Documents list, a Documents section, Papers, Today, the search and the activity list. - **The header**: "Document · ", the title and one line ("Expires 3 May 2027 · Dated 1 May 2025"). **Open** is the main action when there is a file, **Add a file** when there is none. The pencil edits the details. More holds **Replace file** and **Remove file** while there is a file, then Archive or Delete. - **File**: an image is shown; any other file is named with its size. **Link** takes its place for a web address, with its own Open. - **Details**: the type, the tags and the description. - **Attached to**: one row per record, opening it, with Detach in More. With nothing attached, **Attach** opens the edit form. The edit form changes the details only; the file is changed from the page. **Replace file** removes the current file and uploads the new one in one change. **Remove file** asks first, then removes the file and keeps the document, its details and its attachments; the page then says "The file was removed." and offers Add a file. ## Open {#open} **Open** fetches the file from the server and then shows it or saves it: | File | What Open does | |---|---| | PDF; PNG, JPEG, GIF or WebP image; plain text | Shows it in a new tab, in the browser's own viewer | | Anything else (Word, a spreadsheet, a ZIP, HTML, SVG) | Saves it to the device | The browser has nothing to show a Word file or a spreadsheet with, so those are saved and opened from the device's files. A web page or an SVG is saved on purpose: shown inside LazyJack it could run as part of the app. A phone behaves the same way. Open needs a connection: the file is fetched each time and not kept for offline use. A link's Open goes to the address in a new tab. ## Files and sync {#files-and-sync} A file travels apart from its document. The document syncs like any change; the file waits on the device until it is uploaded. - **Captured files survive closing the app.** They stay in the browser's storage until the upload succeeds. A browser that cannot keep them says to keep the app open until they upload. - **Uploads retry by themselves**, on reconnecting and every 30 seconds while files wait. - **Files belong to the signed-in person.** Another account on the same browser has its own queue. - **Files waiting are listed on the Account page**, under the Sync card. A file the server refused shows its reason and **Try again**. **Discard** is in each row's More menu. - **Today's Syncing line** counts them ("3 changes and 2 files waiting to sync"). | What you see | What it means | What to do | |---|---|---| | "Waiting to sync" on the row, "Waiting to upload" on the page | The file is on this device, not uploaded yet | Nothing; it uploads when it can | | "Upload failed" on the row; "File upload failed and needs a retry" in Do first | The server refused the file, or it was discarded | Try again on the Account page if it is listed there; otherwise Add a file on the document's page | | "Asset removed" on the row, "The file was removed." on the page | The file was removed | Add a file to have one again | | "Image not available offline." | An image viewed offline | Look again online | **Discarding a queued file** removes it from the device. The document stays, marked as a failed upload, so Today reports it until the document has a file again or is archived. ## Photos as documents {#photos} Photos taken elsewhere in the app are documents too: - **The boat's photo**: Add a photo on Boat details; Change photo and Remove photo in the photo's More menu. It is a Photo document titled with the boat's name. Changing it keeps the previous photo in Documents; Remove photo keeps the document; archiving the document hides the photo and restoring it brings it back. It is not kept for offline use. - **An item's photo**: the item form's "Attach a document". It becomes a document attached to the item, and to its equipment when the item fits exactly one piece, saved as a Photo whatever the file is. - **A receipt on Received**: "Attach a receipt or photo", saved as a Receipt or a Photo (Save it as) and attached to the item. - **A job's photo**: Did the job's "Attach a photo", saved as a Service record, a Receipt or a Photo, attached to the job and its equipment and titled with the job and the day. ## Documents in the export {#export} Download a copy on the Account page puts every document in `data.json`, with what it is attached to, and every active file under `files/` in the zip. The readable `index.html` links the files it can show safely (PDF, PNG, JPEG, GIF, WebP, plain text) and names the others. "Records only" leaves the files out; a file that could not be read is listed in `MISSING_FILES.txt`. ## Documents and assistants {#assistants} A connected assistant can add a document (`document_create`, a link or a file), upload a file (`asset_upload`, `asset_import_from_url`, or an upload link you open on your phone, `asset_upload_link_create`), attach a document to any record (`document_attach`) and read one with the names of what it is attached to (`document_get`, `document_list`). Detaching, archiving and removing a file need the archive permission and your approval each time; attaching does not. See [Assistants](assistants.html). ### Rules for assistants {#rules-for-assistants} 1. **Attach, do not duplicate.** `document_list` or `search` finds a document that exists; `document_attach` links it to another record. A `document_create` that looks like one already there answers with `warnings`: read them to the owner before going on. 2. **Attach on create.** `document_create` takes `attachedTo` (`{ type, id }` pairs); a document for the engine's manual is attached to the engine in the same call, not created loose and attached later. 3. **A document attached to nothing is the boat's own.** Do not attach a paper to the boat record to "file" it; Registration, Insurance, Ownership and Licence are papers by their `kind`, wherever they are attached. 4. **An expiry is a plain day** (`2027-05-03`): send it so, and Today reports it from 30 days before. 5. **A file on the owner's phone** reaches the server through `asset_upload_link_create`: send the owner the link to open on the phone; never ask them to paste a file into the chat. A file at a web address goes through `asset_import_from_url`. 6. **Detaching, archiving and removing a file need approval.** Attaching does not. Do not ask for approval unprompted. 7. **Checklists:** an outline is plain lines, a line ending in ":" or a Markdown heading opens a section, and `items` is the structured form. Never complete or cancel a run (`checklist_run_complete`, `checklist_run_abandon`) unless the owner asks for exactly that; ticking items the owner reports done (`checklist_run_update_item`) is fine. ## Checklists {#checklists} A checklist is a list of items to go through: an engine start routine, a departure list, a winter lay-up. Checklists are a view in the Boat area. **Add checklist** asks a title, **When is it used?** and an **Outline**, previewed as you type. | When is it used? | Where it appears | |---|---| | Before departure | A planned trip's Prepare section and Today's trip card | | On arrival | End trip offers "Start arrival checklist" | | Engine | A button on Today | | Other (the default) | A button on Today | The outline is plain text, one item per line. A line ending in ":" opens a section, and the lines under it belong to it until the next section at the same or a shallower indent. A Markdown heading ("# Winter lay-up", "## Engine") opens a section too, "##" inside the "#" above it. A leading "-", "*", "1." or "[ ]" is stripped, so a pasted list works as it is. A checklist needs at least one item. The Checklists page lists checklists by title, each row ending with when it is used (nothing for Other). The row opens the checklist's form; **Start** is its button. ### Running one {#running} **Start** begins a run, a copy of the checklist to work through. - **Each item** is ticked, marked **N/A** or left, and can carry a note. - **Complete checklist** finishes the run. With items still open it asks first; they stay marked "Not reviewed". - **Cancel checklist** (in the run's More menu and at its foot, and in an In progress row's More menu) ends it without completing. What was ticked is kept; a new run can be started. - **A run keeps its own copy of the list.** Editing the checklist never changes a run in progress or one done. A run started before 2026-10-10, when runs began keeping their copy, may say that some items from the earlier version can no longer be shown. The page shows **In progress** runs first and **Recently done** last. A run left in progress for two days is reported in Do first on Today until it is completed or cancelled. Checklists also appear on a plan (What each job needs) and its job's page, where a run is started for that job, and in a trip's Prepare section. ## Not in this chapter {#not-here} Records, Archive and Delete: [How LazyJack thinks](how-it-thinks.html). What an assistant may do: [Assistants](assistants.html). Boat details: [Setting up the boat and engine](setting-up.html). Prepare and the trip's checklists: [A trip](a-trip.html). Documents on jobs and problems: [Work](work.html). Receipts on Received: [Inventory and To buy](inventory.html). Invoices on expenses: [Budget and projects](budget.html). Files in a backup and restoring them: [Backup, restore and moving devices](backup.html). Refused changes: [Troubleshooting sync](sync-troubleshooting.html).