Rewrite PROCESS.md with full contracts system integration

Incorporates answered questions from user, two-system architecture
diagram, 8-stage job lifecycle, contracts/ client-facing system,
integration gap map, and prioritised build list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

PROCESS.md

@@ -1,322 +1,360 @@
 # Modulos Design — Job Process Flow
 
-This document maps the end-to-end workflow for a new architectural job, from first contact through to final documentation. It also identifies which pages handle each step, flags gaps in the current system, and asks questions where the intended process is unclear.
+**Last updated:** June 2026
 
-Items marked **> ❓** are questions that need answers before that section can be finalised.
+This document is the authoritative reference for how a job flows through the system from first contact to completion. It covers both the internal staff dashboard and the client-facing contracts system, maps what each tool handles, and lists what still needs to be built.
 
 ---
 
-## Job Lifecycle Overview
+## System Overview
+
+The platform is two separate applications that share a MySQL database and are served from the same domain:
 
 ```
-New Enquiry
-    │
-    ▼
-Stage 1 — ENQUIRY         Record client contact, assign DRG
-    │
-    ▼
-Stage 2 — SETUP           Physical folder, Drive folder, send LOA
-    │
-    ▼
-Stage 3 — BRIEF & SITE    Site visit, scope, planning data from LIST
-    │
-    ▼
-Stage 4 — ONBOARDING      Client signs LOA, pays deposit, sends documents
-    │
-    ▼
-Stage 5 — PLANNING        Assess zones/codes, prepare council request
-    │
-    ▼
-Stage 6 — DESIGN          Floor plans, 3D concepts, renders
-    │
-    ▼
-Stage 7 — APPLICATIONS    DA / BA submissions, council forms
-    │
-    ▼
-Stage 8 — POST-APPROVAL   Tender set, quantity survey, construction docs
+┌─────────────────────────────────────────────────────────────────┐
+│  INTERNAL DASHBOARD  (staff only)                               │
+│  /internal/                                                     │
+│  ─────────────────────────────────────────────────────────────  │
+│  • Job/client records (client-brief.php)                        │
+│  • Dashboard and search (dashboard.php)                         │
+│  • Planning data lookup from THE LIST (list_lookup)             │
+│  • Council application forms (council_forms/)                   │
+│  • Manila folder label printer (manilla_folder.php)             │
+│  • Google Drive job folder creation (client-brief.php)          │
+└─────────────────────────────────────────────────────────────────┘
+            │  shared MySQL  │  shared PHPMailer  │  shared CSS
+┌─────────────────────────────────────────────────────────────────┐
+│  CONTRACTS SYSTEM  (staff + client-accessible)                  │
+│  /contracts/                                                     │
+│  ─────────────────────────────────────────────────────────────  │
+│  • Contract creation & signing  (contract.php — client)         │
+│  • LOA creation & signing       (loa.php — client)              │
+│  • Application progress tracker (progress.php — client)         │
+│  • Contracts admin              (contracts-admin/               │
+│                                  contracts-admin.php — staff)   │
+│  • Application timeline editor  (edit_application.php — staff)  │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
+**Key rule:** The internal dashboard is never shown to clients. The contracts system is what clients interact with — it is the only client-accessible part of the platform.
+
 ---
 
-## Stage 1 — New Enquiry
+## Job Lifecycle — Full Flow
+
+```
+Phone/email enquiry
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 1    │  ENQUIRY       Create job record, assign DRG
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 2    │  SETUP         Physical folder, Drive folder
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 3    │  BRIEF         Site visit, scope, LIST data
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 4    │  ONBOARDING    LOA → Contract → Deposit
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 5    │  PLANNING      Zones/codes, council assessment
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 6    │  DESIGN        Drawings, 3D, energy/fire reports
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 7    │  APPLICATIONS  DA/BA forms, lodge with council
+ └─────────────┘
+       │
+       ▼
+ ┌─────────────┐
+ │  Stage 8    │  POST-APPROVAL Tender set, QS, close out
+ └─────────────┘
+```
 
-**Trigger:** Phone call, email, or website form from a potential client.
+---
 
-**Goal:** Create a job record and capture enough information to call them back or begin scoping.
+## Stage 1 — New Enquiry
 
-### Steps
+**Trigger:** Phone call, email, or website contact from a potential client.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 1.1 | Click **Create Enquiry** on the dashboard | `dashboard.php` | ✅ Built |
-| 1.2 | System assigns the next DRG number | `create_enquiry.php` | ✅ Built |
-| 1.3 | Enter client name, phone, email | `client-brief.php` | ✅ Built |
-| 1.4 | Enter site address (Google Maps autocomplete fills lat/lng) | `client-brief.php` | ✅ Built |
-| 1.5 | Record how the enquiry came in (referral, web, etc.) | — | ❌ Not built |
-| 1.6 | Note any initial scope mentioned on the call | `client-brief.php` → Scope field | ✅ Built |
+**Goal:** Create a job record and capture enough to begin.
 
-> ❓ **Q1.1** — Is there a source/referral field needed (e.g. "Google", "word of mouth", "past client")? If so, should this feed into HubSpot?
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 1.1 | Click **Create Enquiry** | Internal | `dashboard.php` | ✅ |
+| 1.2 | System assigns next DRG number | Internal | `create_enquiry.php` | ✅ |
+| 1.3 | Enter client name, phone, email | Internal | `client-brief.php` | ✅ |
+| 1.4 | Enter site address (Google Maps autocomplete) | Internal | `client-brief.php` | ✅ |
+| 1.5 | Record enquiry source (referral, web, etc.) | Internal | `client-brief.php` | ❌ Field missing |
+| 1.6 | Note initial scope / building description | Internal | `client-brief.php` → Scope | ✅ |
 
-> ❓ **Q1.2** — Should a new enquiry automatically create a HubSpot deal, or is that done manually later once the job is more certain?
+**What needs building:**
+- Add a **Referral Source** dropdown to the client brief (e.g. Word of mouth, Google, Past client, Referral, Builder, Real estate agent, Other)
+- HubSpot deals integration is **not used** — remove HubSpot deal creation from the workflow
 
 ---
 
 ## Stage 2 — Initial Setup
 
-**Trigger:** Enquiry logged, decision made to proceed with a site visit or formal scope.
-
-**Goal:** Set up the physical and digital job infrastructure.
-
-### Steps
+**Trigger:** Decision made to proceed — site visit booked or formal scope requested.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 2.1 | Print manila folder label — file physical folder | `manilla_folder.php?drg=XXXX` | ✅ Built |
-| 2.2 | Create Google Drive job folder | `client-brief.php` → **Create Job** button | ✅ Built (needs API key) |
-| 2.3 | Generate LOA and send to client for signing | `client-brief.php` → LOA section | ✅ Built |
-| 2.4 | Set `PROJECTS_PARENT_FOLDER_ID` so Drive folder lands in the right place | `.env` | ⚠️ Needs config |
+**Goal:** Create the physical and digital job infrastructure.
 
-**Currently missing from this stage:**
-- There is no navigation shortcut from `client-brief.php` to the manila folder page — you have to remember the URL (`manilla_folder.php?drg=XXXX`). A button should be added.
-- After the Drive folder is created, the folder link is shown in an `alert()` dialog and then lost. It should be saved back to the job record.
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 2.1 | Print manila folder label, file physical folder | Internal | `manilla_folder.php?drg=XXXX` | ✅ (not linked) |
+| 2.2 | Create Google Drive job folder | Internal | `client-brief.php` → Create Job | ✅ (needs API key in .env) |
+| 2.3 | Save Drive folder link back to job record | Internal | (after Create Job) | ❌ Not saved |
 
-> ❓ **Q2.1** — What is the folder naming convention in Google Drive? Currently the code uses `DRG - Site Address Street`. Is that correct?
+**Drive folder naming convention:**
+```
+[02] Design / [06] Projects {YEAR} / {DRG} - {Client Surname} /
+e.g.  [02] Design / [06] Projects 2026 / 3048 - Truscott /
+```
 
-> ❓ **Q2.2** — Is the LOA sent as a link (via the contracts system) or printed and posted/scanned back?
+**What needs building:**
+- Add a **Manila Folder** button to the `client-brief.php` action bar (links to `manilla_folder.php?drg={drg}`)
+- After Drive folder is created, save the folder ID and URL to the `details` table. Show an **Open Drive Folder** button on the client brief.
+- Set `PROJECTS_PARENT_FOLDER_ID` in `.env` to the ID of the `[06] Projects {YEAR}` parent folder.
 
 ---
 
 ## Stage 3 — Brief & Site Visit
 
-**Trigger:** LOA sent; site visit arranged.
-
-**Goal:** Capture the full project brief and pull accurate property/planning data.
+**Trigger:** LOA sent (or about to be sent); site visit arranged.
 
-### Steps
+**Goal:** Confirm the full project scope and pull accurate planning data.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 3.1 | Complete site visit, take photos | — | ❌ No site visit notes field |
-| 3.2 | Tick **Site Visit** checkbox | `client-brief.php` | ✅ Built |
-| 3.3 | Confirm and enter site address if not already done | `client-brief.php` | ✅ Built |
-| 3.4 | Click **Planbuild** to fetch property data from THE LIST | `client-brief.php` → Planbuild | ✅ Built |
-| 3.5 | Confirm PID, Title ID, zone, planning codes are populated | `client-brief.php` | ✅ Built |
-| 3.6 | Record design style, build type, scope, budget | `client-brief.php` | ✅ Built |
-| 3.7 | Record registered owner (matches title) | `client-brief.php` | ✅ Built |
-| 3.8 | Record total site area (auto-filled from LIST) | `client-brief.php` | ✅ Built |
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 3.1 | Complete site visit | Off-system | — | — |
+| 3.2 | Tick **Site Visit** done checkbox | Internal | `client-brief.php` | ✅ |
+| 3.3 | Confirm/enter site address | Internal | `client-brief.php` | ✅ |
+| 3.4 | Click **Planbuild** → auto-fills PID, Title ID, zones, codes, area | Internal | `client-brief.php` | ✅ |
+| 3.5 | Confirm planning data is correct | Internal | `client-brief.php` | ✅ |
+| 3.6 | Record design style, build type, scope, budget | Internal | `client-brief.php` | ✅ |
+| 3.7 | Record registered owner (must match title) | Internal | `client-brief.php` | ✅ |
+| 3.8 | Determine if DA is required — tick if yes | Internal | `client-brief.php` | ✅ (see note) |
+| 3.9 | Determine if BA is required — tick if yes | Internal | `client-brief.php` | ✅ (see note) |
+| 3.10 | Record if exempt development (no DA/BA needed) | Internal | `client-brief.php` | ❌ Field missing |
 
-**Currently missing from this stage:**
-- No site visit notes or photo upload field.
-- No prompt to run Planbuild after address entry — it requires manual button click with no reminder.
+**Note on DA/BA checkboxes:** These mean **"we are responsible for handling this application"**, not "the application has been received". They drive whether the applications workflow in Stage 7 is triggered.
 
-> ❓ **Q3.1** — Is there information captured during the site visit that isn't currently in the system (e.g. existing building dimensions, contours, setbacks, easements)?
-
-> ❓ **Q3.2** — Do you need to record the date the site visit happened, or just a checkbox?
+**What needs building:**
+- Add an **Exempt Development** checkbox/field to the client brief — records that no DA or BA is required and why.
+- Consider auto-triggering the Planbuild lookup when site address coordinates are set (rather than requiring a manual button click).
 
 ---
 
 ## Stage 4 — Client Onboarding
 
-**Trigger:** Scope agreed, client ready to formally engage.
-
-**Goal:** Get LOA signed, collect required documents, receive deposit.
+**Trigger:** Scope confirmed, client ready to formally engage.
 
-### Steps
+**Goal:** Get LOA signed, sign the contract, receive deposit — and give the client their first look at the contracts system.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 4.1 | Confirm LOA signed — tick checkbox | `client-brief.php` → Brief Checklist | ✅ Built |
-| 4.2 | Send payment/deposit request to client | `payment_request.php?drg=XXXX` | ⚠️ Sandbox only |
-| 4.3 | Record payment plan stages | `progress.php?drg=XXXX` | ✅ Built (see note) |
-| 4.4 | Request title copy | `client-brief.php` → Brief Checklist | ✅ Checkbox only |
-| 4.5 | Request original plans / survey if existing building | `client-brief.php` → Brief Checklist | ✅ Checkbox only |
-| 4.6 | Tick documents received as they arrive | `client-brief.php` → Brief Checklist | ✅ Built |
+This stage involves both systems. The internal dashboard prepares the data; the contracts system handles client-facing document signing.
 
-**Notes:**
-- `progress.php` is the payment plan tracker (milestone payments). It is currently titled "Client Onboarding Form" in the browser title — this is confusing.
-- `payment_request.php` is the Square payment form, also titled "Client Onboarding Form" — equally confusing.
-- The Square integration is still using sandbox credentials — live payments not yet enabled.
-- There is no link from `client-brief.php` to either `progress.php` or `payment_request.php`. You have to know the URL.
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 4.1 | Create LOA in contracts admin | Contracts | `contracts-admin/contracts-admin.php` | ✅ |
+| 4.2 | Email LOA link to client (link + PDF attachment) | Contracts | Contracts admin → Email link | ✅ |
+| 4.3 | Client receives email, clicks link, signs LOA | Contracts | `loa.php` (client-facing) | ✅ |
+| 4.4 | LOA signed status updates in contracts admin | Contracts | `contracts-admin.php` | ✅ |
+| 4.5 | Tick **LOA Signed** in internal dashboard | Internal | `client-brief.php` → Checklist | ✅ (manual — see below) |
+| 4.6 | Invoice deposit (once LOA returned / contract signed) | Off-system | Accounting software | — |
+| 4.7 | Create contract in contracts admin, email link | Contracts | `contracts-admin/contracts-admin.php` | ✅ |
+| 4.8 | Client signs contract | Contracts | `contract.php` (client-facing) | ✅ |
+| 4.9 | Request title copy | Internal | `client-brief.php` → Checklist | ✅ (checkbox) |
+| 4.10 | Request original plans (if alteration) | Internal | `client-brief.php` → Checklist | ✅ (checkbox) |
+| 4.11 | Tick documents received as they arrive | Internal | `client-brief.php` → Checklist | ✅ |
 
-> ❓ **Q4.1** — When is the deposit invoiced vs. when is the Square form sent? Is the deposit always the same amount or does it vary per job?
-
-> ❓ **Q4.2** — How many payment milestones does a typical job have? (e.g. Deposit, DA lodgement, BA lodgement, Final)
-
-> ❓ **Q4.3** — Is `progress.php` still being used, or has it been superseded by something else?
+**What needs building:**
+- The **LOA Signed** checkbox in the internal dashboard is manual — staff have to check contracts admin and then tick it in client-brief. Ideally, when the client signs the LOA via `loa.php`, it should automatically update the `loa_signed` flag in the internal `details` table.
+- Add a direct link from `client-brief.php` to the matching contracts admin record for that job.
+- The payment plan tracker (`progress.php` in `/internal/`) purpose needs clarifying — if it tracks invoice milestones it should be linked from the client brief. **Recommend renaming it to `payment_plan.php`** to avoid confusion with `contracts/progress.php`.
 
 ---
 
 ## Stage 5 — Planning Assessment
 
-**Trigger:** Site data collected, brief confirmed.
-
-**Goal:** Understand what planning approvals are needed and prepare council communications.
-
-### Steps
+**Trigger:** Brief and site data confirmed.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 5.1 | Review planning zones and codes (populated from LIST) | `client-brief.php` | ✅ Built |
-| 5.2 | Generate planning report | `classes/generate_planning_report.php` | ✅ Built (API) |
-| 5.3 | Use email template to draft planning request to council | `client-brief.php` → Planning request text modal | ✅ Built |
-| 5.4 | Determine if DA is required | `client-brief.php` | ✅ Field only |
-| 5.5 | Determine if BA is required | `client-brief.php` | ✅ Field only |
-| 5.6 | Lodge planning inquiry with council | — | ❌ No tracking |
-| 5.7 | Tick DA/BA fields once lodged | `client-brief.php` | ✅ Built |
+**Goal:** Understand planning requirements and communicate with council if needed.
 
-> ❓ **Q5.1** — When you tick DA/BA in the checklist, does that mean "we have the application" or "it has been submitted to council"? Both states may need to be tracked separately.
-
-> ❓ **Q5.2** — Are there cases where neither a DA nor a BA is needed (e.g. exempt development)? If so, how is that recorded?
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 5.1 | Review planning zones and codes (from LIST data) | Internal | `client-brief.php` | ✅ |
+| 5.2 | Generate planning report | Internal | `client-brief.php` → Planbuild output | ✅ |
+| 5.3 | Draft planning request text for council | Internal | `client-brief.php` → Planning request modal | ✅ |
+| 5.4 | Send planning inquiry to council (if needed) | Off-system | Email / council portal | — |
+| 5.5 | Record if DA required (already done in Stage 3) | Internal | `client-brief.php` | ✅ |
+| 5.6 | Record if BA required (already done in Stage 3) | Internal | `client-brief.php` | ✅ |
+| 5.7 | Record if exempt development | Internal | `client-brief.php` | ❌ |
 
 ---
 
 ## Stage 6 — Design Phase
 
-**Trigger:** Planning confirmed, client brief locked.
-
-**Goal:** Produce drawings, 3D models, and documentation for approval.
+**Trigger:** Planning confirmed, brief locked.
 
-### Steps
+**Goal:** Produce drawings and documentation for approval.
 
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 6.1 | Draft floor plans | `planner/index.html` (in-browser editor) | ✅ Built |
-| 6.2 | Tick Draft Floor Plan received | `client-brief.php` | ✅ Checkbox |
-| 6.3 | 3D concepts | External software | ❌ No integration |
-| 6.4 | Tick 3D Concepts received | `client-brief.php` | ✅ Checkbox |
-| 6.5 | Renders | External software | ❌ No integration |
-| 6.6 | Tick Render Set received | `client-brief.php` | ✅ Checkbox |
-| 6.7 | Upload all files to Google Drive job folder | Google Drive (via browser) | ⚠️ No direct link from job |
-| 6.8 | Energy assessment | External consultant | ✅ Checkbox to track receipt |
-| 6.9 | Fire report (if required) | External consultant | ✅ Checkbox to track receipt |
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 6.1 | Draft floor plans (external software, not in-browser) | Off-system | Archicad / Chief Architect | — |
+| 6.2 | Tick Draft Floor Plan done | Internal | `client-brief.php` → Checklist | ✅ |
+| 6.3 | 3D concepts | Off-system | External software | — |
+| 6.4 | Tick 3D Concepts done | Internal | `client-brief.php` → Checklist | ✅ |
+| 6.5 | Renders (if requested) | Off-system | External software | — |
+| 6.6 | Tick Render Set done | Internal | `client-brief.php` → Checklist | ✅ |
+| 6.7 | Fire report (if required) | Off-system | External consultant | — |
+| 6.8 | Tick Fire Report received | Internal | `client-brief.php` → Checklist | ✅ |
+| 6.9 | Energy assessment | Off-system | External consultant | — |
+| 6.10 | Tick Energy Report received | Internal | `client-brief.php` → Checklist | ✅ |
+| 6.11 | Upload all files to Google Drive job folder | External | Google Drive | ⚠️ No direct link from job |
 
-**Currently missing from this stage:**
-- No direct link to the job's Google Drive folder from the client brief page (the folder ID is created but not stored back to the DB).
-- No link from `client-brief.php` to the in-browser floor plan planner.
+**Note:** The in-browser floor plan editor (`planner/`) is a work-in-progress and is not currently used for production drawings.
 
-> ❓ **Q6.1** — Is the in-browser planner (`planner/`) used in practice, or is design done in external software (e.g. Archicad, Chief Architect)? If it's external, is there value in keeping the in-browser planner?
+**What needs building:**
+- Once the Drive folder ID is saved (Stage 2), show an **Open Drive Folder** button on the client brief so files can be uploaded without navigating Drive manually.
 
 ---
 
 ## Stage 7 — Applications
 
-**Trigger:** Design documentation complete, ready to lodge with council.
-
-**Goal:** Prepare and submit DA and/or BA applications.
-
-### Steps
-
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 7.1 | Fill in council application forms | `council_forms/form_XX.php` | ✅ Built |
-| 7.2 | Compile drawing set for submission | — | ❌ No bundling tool |
-| 7.3 | Lodge DA with council | External (council portal) | ❌ No tracking |
-| 7.4 | Lodge BA with council | External (council portal) | ❌ No tracking |
-| 7.5 | Track council reference numbers | — | ❌ No field for this |
-| 7.6 | Track approval status | — | ❌ No field for this |
-
-> ❓ **Q7.1** — Are the council forms (Form 2, 20, 39, etc.) pre-filled from the job data currently, or are they blank templates that get printed and filled manually?
-
-> ❓ **Q7.2** — After DA/BA is lodged, what information do you need to track? (council reference number, lodgement date, expected decision date, approval date?)
+**Trigger:** Design documentation complete, ready to lodge.
+
+**Goal:** Prepare and submit council applications; give the client visibility of the progress.
+
+This is where the two systems come together most closely. The council forms are prepared in the internal system; the application progress tracking is in the contracts system.
+
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 7.1 | Fill council application forms (pre-filled from job data) | Internal | `council_forms/form_XX.php` | ✅ (not linked) |
+| 7.2 | Create application record in contracts system | Contracts | `admin_dashboard.php` → new | ⚠️ Manual, separate step |
+| 7.3 | Lodge DA with council (email or council portal) | Off-system | — | — |
+| 7.4 | Lodge BA with council | Off-system | — | — |
+| 7.5 | Update application stage to "Submitted" | Contracts | `edit_application.php` | ✅ |
+| 7.6 | Client receives email notification, can view progress | Contracts | `progress.php` (client-facing) | ✅ |
+| 7.7 | Update stages as council acknowledges, processes, decides | Contracts | `edit_application.php` | ✅ |
+| 7.8 | Add correspondence (emails, calls, notes) to timeline | Contracts | `edit_application.php` | ✅ |
+| 7.9 | Client views progress and correspondence | Contracts | `progress.php` (client-facing) | ✅ |
+
+**Council forms currently available:**
+- Form 2 — Application to commence/complete work
+- Form 20 — Building application
+- Form 39 — Planning application
+- Form 60 — Certificate of completion
+- Form 71a — Adjoining owner notification
+- Form 71b — Adjoining owner consent
+- Form 80 — Notification of building work
+
+**What needs building:**
+- Add links to all council forms on `client-brief.php`, pre-filled with the DRG (e.g. `council_forms/form_39.php?drg={drg}`).
+- There is currently **no connection** between creating a job in internal and creating an application record in contracts. Staff have to do both manually. A button on `client-brief.php` should create the application record automatically when DA/BA is ticked.
+- Fields still missing in the internal system: council reference number, lodgement date, expected decision date, approval date.
 
 ---
 
-## Stage 8 — Post-Approval
+## Stage 8 — Post-Approval & Close Out
 
 **Trigger:** DA/BA approved by council.
 
-**Goal:** Prepare final construction documentation package.
-
-### Steps
-
-| # | Action | Page / Tool | Status |
-|---|--------|------------|--------|
-| 8.1 | Prepare tender set | External software | ✅ Checkbox to track |
-| 8.2 | Quantity survey (if required) | External consultant | ✅ Checkbox to track |
-| 8.3 | VR concepts (if requested) | External software | ✅ Checkbox to track |
-| 8.4 | Final billing | `payment_request.php` | ⚠️ Sandbox only |
-| 8.5 | Archive job | — | ❌ No archive/close mechanism |
-
-> ❓ **Q8.1** — Is there a formal job close-out step? (e.g. final invoice issued, drawings archived, job marked complete on dashboard?)
-
-> ❓ **Q8.2** — Is the tender set prepared in-house or sent to a builder? What format?
+**Goal:** Complete construction documentation and formally close the job.
+
+| # | Action | System | Page | Status |
+|---|--------|--------|------|--------|
+| 8.1 | Prepare tender set | Off-system | External software | — |
+| 8.2 | Tick Tender Set done | Internal | `client-brief.php` → Checklist | ✅ |
+| 8.3 | Quantity survey (if required) | Off-system | External consultant | — |
+| 8.4 | Tick Quantity Survey done | Internal | `client-brief.php` → Checklist | ✅ |
+| 8.5 | VR concepts (if requested) | Off-system | External software | — |
+| 8.6 | Tick VR Concepts done | Internal | `client-brief.php` → Checklist | ✅ |
+| 8.7 | Issue final invoice | Off-system | Accounting software | — |
+| 8.8 | Mark job as complete / archive | Internal | — | ❌ Not built |
+
+**What needs building:**
+- Add a **Mark Complete** button to the client brief. This should:
+  - Set a `completed_date` timestamp on the job record
+  - Change the dashboard display for completed jobs (greyed out / filtered to "Archive" view)
+  - Optionally update the application stage to "Decision" in the contracts system
+- Add an **Archived** filter to the dashboard so the main view only shows active jobs.
 
 ---
 
-## Current Page Inventory
-
-| Page | What it actually does | Linked from |
-|------|-----------------------|-------------|
-| `dashboard.php` | Lists all active jobs with status flags | — (entry point) |
-| `create_enquiry.php` | Creates next DRG, inserts DB row, redirects | Dashboard "Create Enquiry" button |
-| `client-brief.php` | Central job record — all data, documents, planning, actions | Dashboard row click |
-| `manilla_folder.php` | Prints physical folder label (PDF) | **Not linked — URL must be typed** |
-| `progress.php` | Payment plan / milestone tracker | **Not linked — URL must be typed** |
-| `payment_request.php` | Square payment form for clients | **Not linked — URL must be typed** |
-| `draft_page.php` | Site drafting view | **Not linked — URL must be typed** |
-| `planner/index.html` | In-browser floor plan editor | **Not linked — URL must be typed** |
-| `council_forms/form_XX.php` | Tasmanian council application forms | **Not linked — URL must be typed** |
-| `classes/generate_planning_report.php` | Planning report JSON API | Called internally by Planbuild button |
-| `g_letter.php` / `google.php` | Google Drive auth test pages (prototypes) | Not linked |
-| `old_g_letter.php` | LOA document creation via Google Docs | Not linked (prototype) |
+## Answered Questions (Incorporated Above)
+
+| Q | Answer | Actioned In |
+|---|--------|-------------|
+| Q1.1 Referral source field? | Yes, add it | Stage 1 — build list |
+| Q1.2 Auto-create HubSpot deal? | HubSpot deals not used — remove | Stage 1 |
+| Q2.1 Drive folder naming? | `[06] Projects YYYY / DRG - Surname /` | Stage 2 |
+| Q2.2 LOA sent as link or print? | Link + PDF attached to email | Stage 4 |
+| Q3.2 Site visit — date or checkbox? | Checkbox only | Stage 3 |
+| Q4.1 When is deposit invoiced? | Once LOA returned or contract signed | Stage 4 |
+| Q5.1 What does DA/BA tick mean? | We are responsible for handling it | Stage 3 / 7 |
+| Q5.2 Exempt development? | Needs a field adding | Stage 3 / 5 |
+| Q6.1 In-browser planner used? | Not currently — WIP | Stage 6 |
+| Q7.1 Council forms pre-filled? | Yes they are | Stage 7 |
+| Q8.1 Job close-out step? | Needs building | Stage 8 |
 
 ---
 
-## Immediate Improvements Needed
-
-The following are quick wins that don't require major new features — just wiring up pages that already exist.
-
-### 1. Add a Job Action Bar to `client-brief.php`
+## Integration Gap Map
 
-A persistent button row (or sidebar) on the client brief that links directly to all job-related pages, pre-filled with the current DRG:
+The two systems share a database and config but are not yet connected in the UI. Here is every gap:
 
-```
-[ Manila Folder ]  [ Payment Plan ]  [ Payment Request ]  [ Floor Planner ]  [ Draft Page ]
-[ Form 2 ]  [ Form 20 ]  [ Form 39 ]  [ Form 80 ]
-```
+| Gap | Impact | Effort |
+|-----|--------|--------|
+| No link from internal client brief → contracts admin for that job | Staff must manually navigate between systems | Low |
+| LOA signed status not auto-synced from contracts → internal | Manual double-entry | Medium |
+| Creating a DA/BA job in internal does not create an application record in contracts | Staff forget to create the tracker | Medium |
+| Council forms not linked from client brief | Forms exist but are typed-in URLs | Low |
+| Drive folder ID not saved after creation | No "Open Drive Folder" button | Medium |
+| No "Back to Dashboard" nav on any page except dashboard | Navigation is broken | Low |
+| Manila folder not linked from client brief | Staff must remember URL | Low |
+| No job archive / close-out | Dashboard grows without end | Medium |
+| No referral source field | Can't track enquiry origins | Low |
+| No exempt development flag | No way to record this outcome | Low |
 
-All of these pages already exist — they just aren't linked.
-
-### 2. Save Google Drive Folder ID back to the job record
-
-When the "Create Job" button creates the Drive folder, save the returned folder ID and web link to the `details` table. Then show a "Open Drive Folder" button on the client brief.
+---
 
-### 3. Rename pages to reflect their actual function
+## Build Priority List
 
-| Current title | Should be |
-|---|---|
-| `progress.php` — "Client Onboarding Form" | Payment Plan Tracker |
-| `payment_request.php` — "Client Onboarding Form" | Payment Request Form |
+Work in rough priority order:
 
-### 4. Add a stage indicator to the dashboard
+### Quick wins (< 1 hour each)
 
-The dashboard shows boolean checkboxes but no overall stage. A computed "current stage" label (based on which flags are set) would give an at-a-glance view of where each job is up to.
+1. **Add "Back to Dashboard" link** to every page's navbar
+2. **Add Job Actions row to `client-brief.php`** — buttons for: Manila Folder, Contracts Admin, Council Forms (Form 2, 20, 39, 60, 71a, 71b, 80), Floor Planner (disabled for now)
+3. **Add Referral Source field** to `client-brief.php` and `details` table
+4. **Add Exempt Development field** to `client-brief.php` and `details` table
+5. **Fix `progress.php` title** from "Client Onboarding Form" to "Payment Plan Tracker"
 
-### 5. Add a "Back to Dashboard" nav link
+### Medium work (half day each)
 
-No page (other than the dashboard itself) has a link back to the dashboard. Adding it to every page's navbar would take 5 minutes.
+6. **Save Drive folder ID + URL to DB** when Create Job runs; show Open Drive Folder button
+7. **Auto-create application record in contracts** when DA/BA is ticked on a job
+8. **Add council tracking fields** to `details` table: `council_ref`, `lodgement_date`, `decision_date`, `approval_date`
+9. **Job close-out** — Mark Complete button + archived state on dashboard
 
----
+### Larger work (requires design)
 
-## Questions Summary
-
-For reference, all open questions in one place:
-
-| # | Stage | Question |
-|---|-------|----------|
-| Q1.1 | Enquiry | Is a referral/source field needed? |
-| Q1.2 | Enquiry | Auto-create HubSpot deal on new enquiry, or manual? |
-| Q2.1 | Setup | Correct Drive folder naming convention? |
-| Q2.2 | Setup | Is LOA sent as a link or printed? |
-| Q3.1 | Brief | What site visit info is captured that's not in the system? |
-| Q3.2 | Brief | Date of site visit or just a checkbox? |
-| Q4.1 | Onboarding | When is deposit invoiced vs. Square form sent? |
-| Q4.2 | Onboarding | How many payment milestones typically? |
-| Q4.3 | Onboarding | Is `progress.php` still in use? |
-| Q5.1 | Planning | Does DA/BA tick mean "received" or "lodged"? |
-| Q5.2 | Planning | How is exempt development recorded? |
-| Q6.1 | Design | Is the in-browser planner used, or is design done externally? |
-| Q7.1 | Applications | Are council forms pre-filled from job data? |
-| Q7.2 | Applications | What needs tracking after DA/BA is lodged? |
-| Q8.1 | Post-approval | Is there a formal job close-out step? |
-| Q8.2 | Post-approval | Tender set format and destination? |
+10. **Auto-sync LOA signed status** from contracts SQLite → internal MySQL when client signs
+11. **Unified navigation** — shared top-nav with links between internal and contracts admin so staff don't maintain two separate browser tabs
+12. **Client progress link** — show the contracts `progress.php` link for a job directly on the internal client brief