Employee directory: note it varies per site + add self-hosted option

- Flag the employee directory as the integration most likely to differ per
  site; USB (cmmc_usb) is standardized and rarely needs adaptation.
- Add "Option B: stand up a self-hosted directory" with the canonical employees
  table DDL, for sites with no HR database. In-app management (CRUD/CSV import)
  noted as a possible future enhancement.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plugins/employees/README.md

@@ -8,6 +8,10 @@ Read-only lookups against a **separate** employee/HR directory database. Powers:
 
 The plugin never writes to this database. Use a read-only account.
 
+> **This is the integration most likely to differ per site.** HR / directory
+> systems vary widely, so expect to map a site's schema to the contract below -
+> the `CREATE VIEW` recipe at the end is the normal way to do it.
+
 ## Connection
 
 Credentials resolve **settings-first, then environment**, except the password
@@ -63,6 +67,39 @@ The app renders it as `/static/employees/<Picture>`, so the image files must
 live in the app's `static/employees/` directory. Leave `Picture` empty/NULL for
 people with no photo; the UI falls back to initials.
 
+## Two ways to provide the directory
+
+**Option A - map an existing HR/directory database** (see the view recipe
+below). Use this when the site already has a system of record for people.
+
+**Option B - stand up a self-hosted directory** for sites with no HR database.
+Create the canonical table and point `employee_db_*` at it:
+
+```sql
+CREATE DATABASE shopdb_directory CHARACTER SET utf8mb4;
+USE shopdb_directory;
+
+CREATE TABLE employees (
+  SSO         INT          NOT NULL PRIMARY KEY,
+  First_Name  VARCHAR(100) NOT NULL,
+  Last_Name   VARCHAR(100) NOT NULL,
+  Team        VARCHAR(100) NULL,
+  Role        VARCHAR(100) NULL,
+  Picture     VARCHAR(255) NULL
+);
+
+-- add people (or bulk-load from CSV with LOAD DATA INFILE)
+INSERT INTO employees (SSO, First_Name, Last_Name, Team, Role, Picture)
+VALUES (123456, 'Jane', 'Doe', 'Inspection', 'Quality Tech', '123456.jpg');
+```
+
+Put photo files (named as in `Picture`) under the app's `static/employees/`.
+This can be a dedicated MySQL database or another schema on the same server as
+the main app DB - the plugin connects to it independently.
+
+> A future enhancement could manage this self-hosted directory in-app (add /
+> edit people, CSV import) so a site needs no direct SQL. Not built yet.
+
 ## Adapting a different site schema (recommended: a view)
 
 Sites whose HR/directory database uses different table or column names should

plugins/usb/README.md

@@ -9,6 +9,12 @@ The plugin's own reference tables (`usbdevicetypes`, `usbdevices`,
 `usbcheckouts`) live in the main app database; only the live check-in/out data
 is in `cmmc_usb`.
 
+> **This schema is typically standardized across sites** - the `cmmc_usb`
+> check-in/out solution is the same deployment everywhere, so the tables below
+> usually match as-is and no adaptation is needed. The view recipe at the end is
+> a fallback for the rare site that differs. (Contrast the employee directory,
+> which genuinely varies per site.)
+
 ## Connection
 
 Credentials resolve **settings-first, then environment**, except the password