Using the Contractor app — module by module

Every module the Contractor app ships today, what each one is for, and the steps to use it.

This page describes what is on dev today. Where a feature exists but is switched off, or exists but never appears because its precondition has never been met in production, that is said inline rather than left for the reader to discover on a screen that does not match the document.

For why a rule exists rather than how to satisfy it, see What each role does.

Updated for CR round 4, re-checked 2026-09-12 against what has actually landed since

What moved since the previous version of this page: the menu shrank (History became a view on My Permits; Certificates and Workers sit under Personnel; Getting started moved to the top bar); step 3 now selects a pin safety placed instead of choosing an area, and the map-link coordinate is gone; step 5 gained a PPE declaration; a worker is now just a name, with the role chosen per permit; certificates gained a licence number and description; the detail page is tabbed — seven tabs now, a Report tab among them. Closing a permit is no longer the contractor's to do — and since wayfinder 098's contractor half (bd6ca96d, 2026-09-11) this works end to end: see Closing the work.

The modules

The drawer has three entries — one link and one group of two — plus the profile, reached from the account card at the bottom of the drawer. Getting started is the help icon in the top bar.

Module	Path	What it is for
My Permits	/permits	Every permit this contractor owns. Two view modes: Permits (live and draft work) and History (closed and expired)
Personnel → Certificates	/certificates	The safety cards held by the workers this contractor sends
Personnel → Workers	/workers	The people this contractor sends — their certificates and which permits they appear on
Profile	/profile	This account's own details
Getting started	/getting-started	A static walkthrough of the app — the top-bar help icon. (The first-run checklist is a separate card on My Permits.)

Personnel is a group heading, not a page — it has no route of its own.

Four more screens are not in the drawer, because you reach them from a permit or a button rather than from the menu: the request wizard (/permits/create, from New Permit on My Permits), edit (/permits/:id/edit), duplicate (/permits/:id/duplicate) and the permit detail page (/permits/:id).

Removed from the menu in round 4: New Permit (the button on My Permits does the same) and History (now a view mode on My Permits — every filter and the CSV export moved with it). An old /history link still works; it redirects to /permits?view=history.

Module 1 — New Permit (the wizard)

The core of the app, opened from New Permit on My Permits. A permit is built across steps that each validate before the next unlocks.

Step by step

The wizard is always seven steps, in this order, and Review is always last — no step is filtered out and none moves depending on what has or has not been set up elsewhere in the app.

1. Select Permit Type — pick one of Hot Work, Confined Space or Working at Heights. This choice drives everything after it: which safety checks appear, whether a Fire Watch will be required at the end, which roles are suggested for your workers, and which certificate they need.

2. Basic Information — Project (the permit's title), Contractor and Foreman. The free-text location that used to sit here moved to step 3.

3. Where & When — where the work happens and when:

   • Facility Plan, then Pin. Pick a plan, then one of the pins safety has placed and named on it; the plan image shows the pin you picked as a read-only marker. You select a pin — you do not place one, and you cannot move it. If no plan has been added yet, or the plan has no active pins, the step says so and you carry on.
   • Location Detail — free text for anything the pin cannot say ("north corner, near the loading dock").
   • Start Date, End Date, Daily Start Time, Daily End Time — one daily window that repeats on every day in the range.
   • Schedule / Location Note — exceptions the dates cannot express, such as "not working Sat/Sun".

   See What is the pin for? below.

4. Safety Checks — the readings. Which readings you are asked for depends on the type you picked at step 1, not on one fixed list:

   Permit type	Readings asked for
   Hot Work	LEL, O₂
   Confined Space	LEL, O₂, CO, SO₂
   Working at Heights	Wind, height from ground

   Some readings block submission and some only advise:

   Reading	Limit	Blocks?
   LEL	0%	yes
   O₂	19.5–23.5%	yes
   CO	≤50 ppm	yes
   Wind	≤25 km/h	yes
   SO₂	≤10 ppm	no — guidance only
   Height from ground	≥4 m	no — informational

   Flagging the work as outdoors skips LEL, O₂ and CO entirely. Wind is deliberately not skippable — Working at Heights is outdoors by definition, so bypassing its one blocking reading would leave nothing.

   What you enter here is not trusted. The server revalidates every blocking threshold when you submit, so a reading edited to pass in the browser is rejected on the server.

   This step also carries a pre-work Safety Checks list — 13 to 17 Yes/No/N-A items, the exact count depending on the permit type you picked at step 1. Saved automatically with your draft (on dev as of this writing, not yet merged/deployed) — it used to be answered but silently discarded, never reaching the API at all. It has no effect on whether you can submit either way: it is a pre-work reference aid for your own crew, not a gate, and is not the same list the safety officer fills in at closure (that one is a separate, officer-only checklist).

5. PPE & Workers — three things on one step:

   • PPE Worn — tick what will be worn on this job, from seven items: Safety Glasses, Hardhat, Respiratory Protection, Earmuffs, Construction Vest, Gloves, Protective Boots, plus an optional note. Optional unless the facility has switched on mandatory PPE declarationflag-gated (PPE_REQUIRED), in which case a permit with nothingticked is refused at submit. What you tick is exactly what the inspector checks on site — and the inspector can also flag something you didn't declare as missing.
   • Required Photo Evidence where the step marks it.
   • Workers — pick each worker from your own worker directory, and give them a Role on permit: pick from the suggested roles for this permit type, or type your own. The role belongs to this job, not to the person — the same worker can be a welder on one permit and a fire watcher on the next. Each worker is checked against a certificate that has not expired.

   On a Confined Space permit only, each worker also gets a pre-work health check — blood pressure and an alcohol reading:

   • Blood pressure is judged only once it is entered as systolic/diastolic. Outside 90–140 over 60–90 reads as abnormal; left blank it reads as unrecorded, not as a failure.
   • Alcohol is zero-tolerance, and a blank reading fails. A breath test that was never taken is not a pass, so a freshly added worker reads as failing until you enter the result. That is the intended default for a permit to work.

   This check is a client-side aid. Unlike the atmosphere readings, the server stores blood pressure and alcohol as free text and does not validate them — so it is the one thing on this screen that a determined person could get past. Treat it as a checklist for the foreman, not as a gate.

6. Job Safety Analysis — one row per step: its phase, the step itself, the hazard, and the control. A row is either complete or it blocks the step; a half-filled row is not accepted.

7. Review & Submit — everything on one screen before it leaves your hands. Saving keeps it as DRAFT; submitting moves it to PENDING and puts it in the safety officer's queue.

What is the pin for?

A pin is a named place that safety has marked on a facility plan — "Tank Farm north valve", "Roof B access hatch". It is how the system knows where your work is, and it is what the overlap warning checks: when the safety officer reviews your permit they are shown every other permit on the same pin whose dates and daily hours collide with yours, with the other permit, the colliding date and time, and the pin named. The warning is advisory — it never blocks approval — but it only works if you pick the right pin.

Once safety has an active plan with at least one pin on it, a pin is required to submit. Until then the step still appears and you can submit without one.

Things you cannot do, on purpose:

• Place or move a pin yourself. Pins are safety's. If the place you need is not in the list, ask the safety officer to add it — a pin exists only because someone in safety placed and named it.
• Upload your own plan. Two crews on the same roof each drawing their own map is exactly the case the overlap warning could not see through. A sketch you attach to the permit is a plain document with no coordinate system.

What round 4 removed from this step

Areas are gone entirely: there is no area picker, and you no longer propose areas for safety to approve — pick a pin instead. The map-link field that turned a pasted Google Maps link into a stored coordinate is gone too, along with the coordinate itself. A permit's place is its pin. Permits that had an area or an old-style pin position before 2026-09-11 now read as having no pin.

The certificate type still does not gate anything by default

Step 5 checks that each worker holds a certificate that has not expired. Each permit type now has exactly one matching certificate type (Hot Work, Confined Space Entry, Working at Heights), but the check that a worker's card is the right type only runs when a deployment switches on

flag-gated CERT_TYPE_REQUIRED. It is off by default, so a card of the

wrong type still satisfies a permit today. See Open items.

Module 2 — My Permits

Everything you own, in two view modes along the top of the page.

Permits

1. Open /permits — the drawer's first entry.
2. Search by ID, title or location, and narrow with the chips — All, Active, Pending, Closed. The list is paged.
3. Pick a permit to open its detail page, or press New Permit to start the wizard.
4. From a permit's detail page you can edit it, or duplicate it into a new draft when the next job is much like the last one.

Editing a permit that is already PENDING warns you first: an officer may be reading it right now, and an edit puts it back in front of them.

History

Finished permits only — CLOSED and EXPIRED. Anything still in play lives under Permits.

1. Switch to History (or open /permits?view=history).
2. Narrow the list by search text, status, permit type, or a date range.
3. Export CSV hands you the filtered list as a file.

Read-only, and deliberately so: the record of a permit that has closed is part of the audit trail, and the audit trail has no edit or delete path anywhere in the system.

Module 3 — Permit detail

The detail page is where a permit lives out its life. What it offers depends on the permit's status and type.

What the page shows

The status banner sits at the top, with the one action the permit's state allows. Below it, anything urgent is pinned above the tabs so it needs no click — today that is the "Closure requested — awaiting Safety Officer" strip, which names who asked, when and why. The rest is in seven tabs: 1. Overview, 2. Safety readings, 3. Workers & PPE, 4. Job Safety Analysis, 5. Closure & Fire Watch (just 5. Closure on a permit type that has no Fire Watch), 6. Audit trail and — since wayfinder 112's contractor half (8265679f, 2026-09-11) — 7. Report. The QR panel sits beside them on a wide screen and below them on a narrow one. On a Hot Work permit in FIRE_MONITOR, a Fire Watch panel with a countdown appears.

A Print / Export PDF button sits above the tabs, not inside any of them — the document it produces covers every tab at once (checklist, readings, JSA, workers/PPE, entrants, gas log, visits, approval/closure, audit), formatted for A4 with an e-safework header/footer repeating on every printed page. Browser print (window.print()), not a downloaded file from the server. On dev as of this writing, not yet merged/deployed.

Checked against permit.ts's detail.sections keys.

Report — visits, gaps and the closure record

The Report tab is a print-ready view built from what the system already holds, no second fetch: every inspector visit on the permit — entrant activity, PPE, gas readings, notes and photos, in full, per map ruling 18 (you read the same content the safety app does, on your own permits only) — plus a gap list (days with no visit; a gas reading whose retest missed its server-computed dueAt) and, once the permit is closed, a closure summary (reason, who was auto-checked-out at close, and final PPE as you declared it on the permit — not what the last inspector visit observed; the owner's original question had two valid answers and this is the default that shipped). Print / Save as PDF uses the browser's own print dialog and stylesheet — there is no PDF dependency. Checked against PermitReportSection.vue and en/permit.ts's detail.report keys.

Inspector notes are visible here because they are meant to be

Since round 4 you may read the full content of an inspector's visit on your own permits, notes included — the owner chose this over filtering by note type. If a note reads as a surprise, it isn't a bug: What each role does has the reasoning.

Closing the work

Since wayfinder 098's contractor half (bd6ca96d, 2026-09-11), this works end to end. Only a safety officer can close a permit; the contractor's old closure checklist and its e-signature are gone, replaced by a request:

• Hot Work: Mark complete. On an ACTIVE Hot Work permit, press Mark Work Complete → and confirm Start 30-min Fire Watch. The permit moves to FIRE_MONITOR and the server starts the Fire Watch countdown. It is driven by the server's own remaining time, not by the browser — reloading the page, or closing it and coming back, does not restart it. The Fire Watcher must stay on site for the whole period. This step is unchanged and still yours.
• Request Closure →, on an ACTIVE or FIRE_MONITOR permit, opens RequestCloseModal.vue: an optional reason, sent to POST /close-request. During FIRE_MONITOR you can send the request before the Fire Watch countdown ends — the button reads Request Closure ✓ and the screen tells you safety cannot act on it until the watch elapses. A second request is not an error: the button becomes Update Request, prefilled with what you last sent, and sending again just refreshes who/when/why.
• Seeing a request. When someone has asked for closure, the strip above the tabs says so, with who asked, when, and their reason. The permit stays ACTIVE (or FIRE_MONITOR) until safety acts — a request is not a status.

Planned: a permit-timeout warning card

Nothing today tells a contractor that a permit's work window is about to end, or has already ended, while the permit is still open. A planned (not yet built) card above the tabs will warn at 30 minutes remaining — offering Dismiss or Extend, with a date/time picker to propose a new end — and, once the window has actually passed, will drop the dismiss option and offer only Extend or Request Closure (reusing the flow above, pre-filled to say the permit expired).

No e-signature is asked for. The old checklist's e-signature is gone with it, and the server has no field for one — the owner's open question about whether the closure report needs a signature block is still open.

When safety does close a Confined Space permit, anyone still checked in is checked out automatically at that moment and the record says the system did it — you no longer have to get the register to zero first.

The QR panel

The permit's QR code is what an inspector scans on site. Show it from the detail page. Anyone scanning it gets the permit's live status, not a snapshot from when it was printed.

Module 4 — Certificates (under Personnel)

The safety cards belonging to the workers you send. A worker whose card has expired cannot be added to a permit at step 5, so this list is where you find out before you are half-way through a request rather than during it.

Search by worker name or filter by worker; the list is paged.

Adding one

1. Open Personnel → Certificates and press ＋ Add Certificate.
2. Choose the worker. Start typing and pick them from the list; if they are new, Add "…" as a new worker registers them inline by name, and you stay on the form.
3. Pick the Certificate type — Hot Work, Confined Space Entry or Working at Heights — and fill in the Issued date and Expiry date.
4. Give a Licence number, attach a scan or photo of the card (JPEG, PNG, WEBP, HEIC or PDF), or both. At least one of the two is required — a certificate with neither is refused. The Description field (training or examination detail) is optional.
5. Save.

An already-expired expiry date is not rejected. The record is the truth; the card simply shows as Expired, and that worker is blocked at step 5 until it is renewed.

Looking at one

Tap any card to open /certificates/:id. It shows the same details plus the attachment, and Open attachment fetches the file when you press it rather than when the page loads — the link the storage system hands out expires after a minute, so it has to be asked for at the moment you want it.

Correcting one

From the detail page, Edit certificate. The type, both dates, the licence number and the description can be corrected — a mistyped expiry date is exactly the kind of thing that makes a card unusable. Correcting a date does not let anything through that should not: the check runs again on the server every time a permit is submitted.

The worker field re-points the certificate at a different person. It is not where you fix a misspelled name — a worker is a record of their own, so correcting their spelling changes it everywhere at once rather than on this one card.

A certificate recorded before the type list existed may carry a type that is not one of the three; the form shows it as "(not in the standard list)" rather than silently changing it.

The attachment has three behaviours on that form, and the difference matters:

What you do	What happens to the file
Leave the file box alone	The existing attachment is kept
Pick a new file	It replaces the old one
Press Remove attachment	The certificate is saved with no file — allowed only if it has a licence number

There is no delete button for a certificate itself. Retiring one is not built yet — see Open items.

Attachments added before September 2026 are gone

Until recently the server accepted the upload and then discarded the reference, so certificates registered before then show no attachment even if a file was picked at the time. The files were never linked to any record. Re-attach them by editing the certificate.

Module 5 — Workers (under Personnel)

The people this contractor sends, reached from Personnel → Workers (/workers). Each entry carries the worker's certificate status and which permits they appear on.

1. Open /workers, and Register worker to add someone.
2. Search, or tap a worker to open /workers/:id.
3. From a worker's detail page you can edit their identity — Name, ID card number, Phone — see their certificates and permits in one place, add a certificate, print their Worker QR card, or Retire worker.

A worker is a name, not a job title. Round 4 removed the role that used to be asked once at registration; what someone does is chosen per permit, at step 5. A worker is registered either from here or inline while adding a certificate — the two paths reach the same record, so correcting a name here corrects it everywhere the worker appears (every certificate, every permit's worker roster), rather than on one form at a time.

Module 6 — Profile

This account's own details, reached from the account card at the bottom of the drawer — this app has no header menu, so that card is the only route into the profile.

Signing in

/auth/login, and /auth/reset-password for a forgotten password.

If you use both this app and the Safety app in the same browser, be aware that signing into one currently signs you out of the other. The server-side fix has shipped; the infrastructure change that completes it has not. See Open items.