diff --git a/AGENTS.md b/AGENTS.md
index de5c2ed..c46f5e5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -134,6 +134,7 @@ Comment what the code does, not what the agent has done. The documentation's pur
 
 - Database connection via `mysql2` pool wrapped by Drizzle (`src/server/db.ts`).
 - Env validation via Zod (`src/env.ts`) ensures `ZXDB_URL` is a valid `mysql://` URL.
+- Supports optional local file mirroring via `ZXDB_LOCAL_FILEPATH` and `WOS_LOCAL_FILEPATH` env vars.
 - Minimal Drizzle schema models used for fast search and lookups (`src/server/schema/zxdb.ts`).
 - Repository consolidates SQL with typed results (`src/server/repo/zxdb.ts`). Gracefully handles missing tables (e.g. `releases`) by checking `information_schema.tables`.
 - API routes under `/api/zxdb/*` validate inputs with Zod and run on Node runtime.
@@ -163,7 +164,10 @@ Comment what the code does, not what the agent has done. The documentation's pur
   - Use `bin/setup-zxdb-local.sh` (or `pnpm setup:zxdb-local`) to add local excludes for SQL files.
 - deploy workflow:
   - `bin/deploy.sh` refuses to run with uncommitted or untracked files at the repo root.
-
+- testing:
+  - Do not restart the dev-server, use the already running one.
+  - use tsc -noEmit to check for type errors, build breaks the dev-server.
+  
 ### References
 
 - ZXDB setup and API usage: `docs/ZXDB.md`
diff --git a/docs/ZXDB.md b/docs/ZXDB.md
index 88e4538..99f3128 100644
--- a/docs/ZXDB.md
+++ b/docs/ZXDB.md
@@ -39,6 +39,35 @@ Notes:
 - The URL must start with `mysql://`. Env is validated at boot by `src/env.ts` (Zod), failing fast if misconfigured.
 - The app uses a singleton `mysql2` pool (`src/server/db.ts`) and Drizzle ORM for typed queries.
 
+### Local File Mirrors
+
+The explorer can optionally show "Local Mirror" links for downloads if you have local copies of the ZXDB and World of Spectrum (WoS) file archives.
+
+#### Configuration
+
+To enable local mirrors, set the following variables in your `.env`:
+
+```bash
+# Absolute paths to your local mirrors
+ZXDB_LOCAL_FILEPATH=/path/to/your/zxdb/mirror
+WOS_LOCAL_FILEPATH=/path/to/your/wos/mirror
+
+# Optional: Remote path prefixes to strip from database links before prepending local paths
+# Defaults shown below if omitted:
+ZXDB_FILE_PREFIX=/zxdb/sinclair/
+WOS_FILE_PREFIX=/pub/sinclair/
+```
+
+#### How it works
+
+1. The app identifies if a download link matches `ZXDB_FILE_PREFIX` or `WOS_FILE_PREFIX`.
+2. It strips the prefix from the database link.
+3. It joins the remaining relative path to the corresponding `*_LOCAL_FILEPATH`.
+4. It checks if the file exists on the local disk.
+5. If the file exists and the environment variable is set, a "Local Mirror" link is displayed in the UI.
+
+Note: Obtaining these mirrors is left as an exercise to the host. The paths do not need to share a common parent directory. Both mirrors are optional and independent; you can configure one, both, or neither.
+
 ## Running
 
 ```