Expand README config docs with everything today's debugging surfaced

- Full inline entity.json example plus a Required? column in the field table
- Explicit JSON editing rules (exact key names, comma placement, straight
  quotes, no quotes on numbers/booleans)
- insurance_file_type placement called out (top level, not inside ftps)
- practice.json can add fields entity.json lacks, with a different-paths
  example; note that workflow/insurance_file_type are entity-wide only
- Troubleshooting entries for CONFIG ERROR, wrong-file-type "No .pdf files",
  all-fields-missing (bad section name), and the startup banner check

README.md

@@ -78,22 +78,50 @@ leave its login and every other path alone.
 
 1. Create a folder under `Entities\` with the entity name (e.g. `Entities\CAMBS\`)
 2. Copy `run.bat` into it
-3. Create `entity.json` in that folder — copy from `Entities\EXAMPLE\entity.json` and fill in:
+3. Create `entity.json` in that folder — copy from `Entities\EXAMPLE\entity.json`
+   and fill in your real values. A complete file looks like this:
 
-| Setting | What to put |
-|---------|------------|
-| `workflow` | `insurance` if no patient files, `insurance+patient` if both |
-| `insurance_file_type` | Optional, defaults to `pdf`. Set to `tif` for an entity whose imaging system exports the daily insurance/PT STMT files as TIFs instead of PDFs (e.g. CAMBS, RMI, CONSENSIO, INLAND) |
-| `ftps.host` | FTP server address |
-| `ftps.username` | FTP username (shared across all practices) |
-| `ftps.password` | FTP password |
-| `ftps.tls` | `true` for FTPS (secure), `false` for plain FTP |
-| `ftps.insurance_path` | Remote path for insurance PDFs — keep `{practice}` in it |
-| `ftps.pdf_path` | Remote path for PT STMT PDFs — keep `{practice}` in it |
-| `sftp.host` | SFTP server (only needed if workflow is `insurance+patient`) |
-| `sftp.username` | SFTP username |
-| `sftp.password` | SFTP password |
-| `sftp.patient_path` | Remote path for patient files — keep `{practice}` in it |
+```json
+{
+  "workflow": "insurance+patient",
+  "insurance_file_type": "pdf",
+
+  "ftps": {
+    "host": "ftp.example.com",
+    "port": 21,
+    "tls": true,
+    "username": "shared-username",
+    "password": "shared-password",
+    "insurance_path": "/{practice}/Insurance",
+    "pdf_path": "/{practice}/PDF"
+  },
+
+  "sftp": {
+    "host": "sftp.example.com",
+    "port": 22,
+    "username": "shared-username",
+    "password": "shared-password",
+    "patient_path": "/{practice}/Patient"
+  }
+}
+```
+
+| Setting | Required? | What to put |
+|---------|-----------|------------|
+| `workflow` | Yes | `insurance` if no patient files, `insurance+patient` if both |
+| `insurance_file_type` | No (defaults to `pdf`) | Set to `tif` for an entity whose imaging system exports the daily files as TIFs instead of PDFs (CAMBS, RMI, CONSENSIO, INLAND). Goes at the top level, next to `workflow` — NOT inside `ftps` |
+| `ftps.host` | Yes | FTP server address |
+| `ftps.port` | No (defaults to 21) | FTP port, only if not 21 |
+| `ftps.tls` | Yes | `true` for FTPS (secure), `false` for plain FTP |
+| `ftps.username` | Yes | FTP username (shared across all practices) |
+| `ftps.password` | Yes | FTP password |
+| `ftps.insurance_path` | Yes | Remote folder for insurance files — keep `{practice}` in it |
+| `ftps.pdf_path` | Yes | Remote folder for PT STMT files — keep `{practice}` in it |
+| `sftp.host` | Only if `insurance+patient` | SFTP server address |
+| `sftp.port` | No (defaults to 22) | SFTP port, only if not 22 |
+| `sftp.username` | Only if `insurance+patient` | SFTP username |
+| `sftp.password` | Only if `insurance+patient` | SFTP password |
+| `sftp.patient_path` | Only if `insurance+patient` | Remote folder for patient files — keep `{practice}` in it |
 
 4. Create the `Export1\` folder and a subfolder for each practice inside the entity folder
 
@@ -101,17 +129,39 @@ leave its login and every other path alone.
 folder name — so one `entity.json` can serve every practice as long as they
 all follow the same folder-naming pattern on the server.
 
+**Every "Yes" field must be present in `entity.json`** unless *every single
+practice* under the entity supplies it in its own `practice.json`. If a
+required field is missing or blank, the run stops that practice with a
+`CONFIG ERROR` message naming exactly which fields it couldn't find — nothing
+uploads and nothing archives for that practice until it's fixed.
+
+**Editing JSON — the rules that bite:**
+- Key names must match **exactly** (all lowercase, underscores): `host`, not
+  `hostname`; `username`, not `user`; `insurance_path`, not `insurancepath`
+- Every `"key": "value"` pair ends with a comma **except the last one in its
+  block** — a missing or extra comma breaks the whole file
+- Keep values inside straight double quotes (`"`). Avoid editing in Word or
+  anything that turns quotes curly — use Notepad
+- `port` numbers and `tls` true/false do **not** get quotes; everything else does
+
 ---
 
 ## `practice.json` — overriding one practice
 
 If one practice needs a different login, a different folder path, or both:
 
-1. Create a `practice.json` file inside that practice's folder
+1. Create a `practice.json` file inside that practice's folder (next to its
+   date folders, e.g. `Entities\CAMBS\Export1\AJMAT\practice.json`)
 2. Copy from `Entities\EXAMPLE\Export1\PRACTICE_NAME\practice.json`
 3. Delete every line you *don't* need to change — keep only the fields that
    differ for this practice. Everything you delete falls back to `entity.json`.
 
+The field names are the same ones as `entity.json`, wrapped in the same
+`ftps` / `sftp` sections. A `practice.json` can also **add** a field that
+`entity.json` doesn't have at all — e.g. if `entity.json` has no
+`insurance_path` because every practice's path is different, each practice's
+`practice.json` can carry its own.
+
 Example — this practice only has its own PDF folder name, nothing else differs:
 
 ```json
@@ -133,6 +183,23 @@ Example — this practice has its own SFTP login but uses the same paths as ever
 }
 ```
 
+Example — this practice has completely different remote folders for everything:
+
+```json
+{
+  "ftps": {
+    "insurance_path": "/SpecialFolder/Claims",
+    "pdf_path": "/SpecialFolder/Statements"
+  },
+  "sftp": {
+    "patient_path": "/SpecialFolder/Patients"
+  }
+}
+```
+
+Note: a `practice.json` never needs `workflow` or `insurance_file_type` —
+those are entity-wide only.
+
 ---
 
 ## Something went wrong?
@@ -140,3 +207,16 @@ Example — this practice has its own SFTP login but uses the same paths as ever
 - **Files failed to upload** — they stay in the date folder. Fix the issue and run again.
 - **A date folder is still there after running** — one or more files failed. Check the output window.
 - **WinSCP error on startup** — run `setup.bat` again to re-download WinSCP.
+- **`CONFIG ERROR: entity.json is missing or has blank: ...`** — the fields it
+  lists couldn't be found in that entity's `entity.json` (or the practice's
+  `practice.json`). Open the file and check those exact key names against the
+  example above — a typo in the key name counts as missing.
+- **`No .pdf files in <date>\` but the folder isn't empty** — the files in the
+  date folder are probably TIFs. Add `"insurance_file_type": "tif",` at the top
+  level of that entity's `entity.json` (right under `workflow`).
+- **Every field shows missing at once** — the section name itself is probably
+  wrong (must be exactly `ftps` / `sftp`), or the file's structure got damaged
+  while editing. Compare the overall shape against `Entities\EXAMPLE\entity.json`.
+- **The startup banner shows the wrong file type** — the banner line
+  (`Entity: ... | File type: .pdf | ...`) shows what was actually read from
+  `entity.json`, so it's the quickest way to confirm your edit took effect.