Running a Checklist on a Job

A checklist run is always scoped to a specific job (project). This means you cannot tick items on a checklist from the standalone Resources library — the amber warning card that appears when you open a checklist without a project context explains this: 'Open this checklist from a job page to tick items — your ticks are saved per-shoot so you can pick up where you left off.' The correct entry point is the job detail page for the specific shoot you are working on, where a pinned or linked checklist will open the detail page pre-loaded with a ?projectId= parameter.

When a checklist opens with a valid project context, the backend calls startOrResumeRun idempotently. The first time you open it on a given job, a new run record is created and associated with (checklist, project, your user). Every subsequent time you open the same checklist on the same job, the server returns the existing run with all your previous ticks intact — you always pick up where you left off. The progress card at the top shows 'X/Y required items complete' immediately on load.

Ticking an item taps the row and fires a POST to /portal-resources/runs/:runId/items/:itemId with { completed: true }. The UI updates optimistically — the checkbox fills immediately and the label gets a strikethrough — and the network call confirms in the background. If the network call fails, the tick rolls back and a toast error appears. Un-ticking a previously completed item sends { completed: false } and the item un-strikes. Required items and optional items tick identically from a UI perspective, but only required items count toward the X/Y progress fraction.

When all required items are ticked, the progress card replaces the fraction with a green 'Done' badge containing a check-circle icon. If you need to close out a checklist quickly when all required items are done but optional ones remain, the 'Mark all complete' button (visible at the bottom whenever at least one required item is unticked) will bulk-complete the entire run with a single tap. After the run is complete, the checklist card on the browse grid shows the progress count at its maximum (e.g., 5/5), giving project managers a quick at-a-glance confirmation that the field technician completed the pre-job or on-site procedure.

Run state syncs across devices in real time for the same user. If you start ticking on your iPhone and then open the same checklist on the web portal while still on-site, you will see your ticks reflected immediately because they are persisted on the server, not stored locally. However, run state is per-user — a second technician assigned to the same job will have their own independent run and their own tick progress. This is by design: the run model attributes accountability to a specific person.