docs: add ZXDB guide; refresh README & AGENTS

Expand and update documentation to reflect the current app (Registers + ZXDB Explorer), with clear setup and usage instructions.

Changes
- README: add project overview including ZXDB Explorer; routes tour; ZXDB setup (DB import, helper search tables, readonly role); environment configuration; selected API endpoints; implementation notes (Next 15 async params, Node runtime for mysql2, SSR/ISR usage); links to AGENTS.md and docs/ZXDB.md.
- docs/ZXDB.md (new): deep-dive guide covering database preparation, helper tables, environment, Explorer UI, API reference under /api/zxdb, performance approach (helper tables, parallel queries, ISR), troubleshooting, and roadmap.
- AGENTS.md: refresh Project Overview/Structure with ZXDB routes and server/client boundaries; document Next.js 15 dynamic params async pattern for pages and API routes; note Drizzle+mysql2, Node runtime, and lookup `text`→`name` mapping; keep commit workflow guidance.
- example.env: add reference to docs/ZXDB.md and clarify mysql:// format and setup pointers.

Notes
- Documentation focuses on the current state of the codebase (what the code does), not a log of agent actions.
- Helper SQL at ZXDB/scripts/ZXDB_help_search.sql is required for performant searches.

Signed-off-by: Junie@lucy.xalior.com

README.md

@@ -1,14 +1,13 @@
 Spectrum Next Explorer
 
-A Next.js application for exploring the Spectrum Next hardware. It includes a Register Explorer with real‑time search and deep‑linkable queries.
+A Next.js application for exploring the Spectrum Next ecosystem. It ships with:
 
-Features
-- Register Explorer parsed from `data/nextreg.txt`
-- Real‑time filtering with query‑string deep links (e.g. `/registers?q=vram`)
+- Register Explorer: parsed from `data/nextreg.txt`, with real‑time search and deep links
+- ZXDB Explorer: a deep, cross‑linked browser for entries, labels, genres, languages, and machine types backed by a MySQL ZXDB instance
 - Bootstrap 5 theme with light/dark support
 
 Quick start
-- Prerequisites: Node.js 20+, pnpm (recommended)
+- Prerequisites: Node.js 20+, pnpm (recommended), access to a MySQL server for ZXDB (optional for Registers)
 - Install dependencies:
   - `pnpm install`
 - Run in development (Turbopack, port 4000):
@@ -26,11 +25,53 @@ Project scripts (package.json)
 - `deploy-test`: push to `test.explorer.specnext.dev`
 - `deploy-prod`: push to `explorer.specnext.dev`
 
-Documentation
-- Docs index: `docs/index.md`
-- Getting Started: `docs/getting-started.md`
-- Architecture: `docs/architecture.md`
-- Register Explorer: `docs/registers.md`
+Routes
+- `/` — Home
+- `/registers` — Register Explorer
+- `/zxdb` — ZXDB Explorer (search + filters)
+- `/zxdb/entries/[id]` — Entry detail
+- `/zxdb/labels` and `/zxdb/labels/[id]` — Labels search and detail
+- `/zxdb/genres` and `/zxdb/genres/[id]` — Genres list and entries
+- `/zxdb/languages` and `/zxdb/languages/[id]` — Languages list and entries
+- `/zxdb/machinetypes` and `/zxdb/machinetypes/[id]` — Machine types list and entries
+
+ZXDB setup (database, env, and helper tables)
+The Registers section works without any database. The ZXDB Explorer requires a MySQL ZXDB database and one environment variable.
+
+1) Prepare the database (outside this app)
+- Import ZXDB data into MySQL. If you want only structure, use `ZXDB/ZXDB_mysql_STRUCTURE_ONLY.sql` in this repo. For data, import ZXDB via your normal process.
+- Create the helper search tables (required for fast search):
+  - Run `ZXDB/scripts/ZXDB_help_search.sql` against your ZXDB database.
+- Create a read‑only role/user (recommended):
+  - Example (see `bin/import_mysql.sh`):
+    - Create role `zxdb_readonly`
+    - Grant `SELECT, SHOW VIEW` on database `zxdb`
+
+2) Configure environment
+- Copy `.env` from `example.env`.
+- Set `ZXDB_URL` to a MySQL URL, e.g. `mysql://zxdb_readonly:password@hostname:3306/zxdb`.
+- On startup, `src/env.ts` validates env vars (t3.gg pattern with Zod) and will fail fast if invalid.
+
+3) Run the app
+- `pnpm dev` → open http://localhost:4000 and navigate to `/zxdb`.
+
+API (selected endpoints)
+- `GET /api/zxdb/search?q=...&page=1&pageSize=20&genreId=...&languageId=...&machinetypeId=...&sort=title&facets=1`
+- `GET /api/zxdb/entries/[id]`
+- `GET /api/zxdb/labels/search?q=...`
+- `GET /api/zxdb/labels/[id]?page=1&pageSize=20`
+- `GET /api/zxdb/genres` and `/api/zxdb/genres/[id]?page=1`
+- `GET /api/zxdb/languages` and `/api/zxdb/languages/[id]?page=1`
+- `GET /api/zxdb/machinetypes` and `/api/zxdb/machinetypes/[id]?page=1`
+
+Implementation notes
+- Next.js 15 dynamic params: pages and API routes that consume `params` must await it, e.g. `export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; }`
+- ZXDB integration uses Drizzle ORM over `mysql2` with a singleton pool at `src/server/db.ts`; API routes declare `export const runtime = "nodejs"`.
+- Entry and detail pages server‑render initial content and use ISR (`revalidate = 3600`) for fast time‑to‑content; index pages avoid a blocking first client fetch.
+
+Further reading
+- ZXDB details and API usage: `docs/ZXDB.md`
+- Agent/developer workflow and commit guidelines: `AGENTS.md`
 
 License
 - See `LICENSE.txt` for details.