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

AGENTS.md

@@ -4,9 +4,11 @@ This document provides an overview of the Next Explorer project, its structure,
 
 ## Project Overview
 
-Next Explorer is a web application for browsing and exploring the registers of the Spectrum Next computer. It is built with Next.js (App Router), React, and TypeScript.
+Next Explorer is a web application for exploring the Spectrum Next ecosystem. It is built with Next.js (App Router), React, and TypeScript.
 
-The application reads register data from `data/nextreg.txt`, parses it on the server, and displays it in a user-friendly interface. Users can search for specific registers and view their details, including per-register notes and source snippets.
+It has two main areas:
+- Registers: parsed from `data/nextreg.txt`, browsable with real-time filtering and deep links.
+- ZXDB Explorer: a deep, cross‑linked browser for ZXDB entries, labels, genres, languages, and machine types backed by MySQL using Drizzle ORM.
 
 ## Project Structure
 
@@ -64,6 +66,17 @@ next-explorer/
     - `RegisterBrowser.tsx`: Client Component implementing search/filter and listing.
     - `RegisterDetail.tsx`: Client Component that renders a single register’s details, including modes, notes, and source modal.
     - `[hex]/page.tsx`: Dynamic route that renders details for a specific register by hex address.
+- `src/app/zxdb/`: ZXDB Explorer routes and client components.
+  - `page.tsx` + `ZxdbExplorer.tsx`: Search + filters with server-rendered initial content and ISR.
+  - `entries/[id]/page.tsx` + `EntryDetail.tsx`: Entry details (SSR initial data).
+  - `labels/page.tsx`, `labels/[id]/page.tsx` + client: Labels search and detail.
+  - `genres/`, `languages/`, `machinetypes/`: Category hubs and detail pages.
+- `src/app/api/zxdb/`: Zod‑validated API routes (Node runtime) for search and category browsing.
+- `src/server/`:
+  - `env.ts`: Zod env parsing/validation (t3.gg style). Validates `ZXDB_URL` (mysql://).
+  - `server/db.ts`: Drizzle over `mysql2` singleton pool.
+  - `server/schema/zxdb.ts`: Minimal Drizzle models (entries, labels, helper tables, lookups).
+  - `server/repo/zxdb.ts`: Repository queries for search, details, categories, and facets.
 - **`src/components/`**: Shared UI components such as `Navbar` and `ThemeDropdown`.
 - **`src/services/register.service.ts`**: Service layer responsible for loading and caching parsed register data.
 - **`src/utils/register_parser.ts` & `src/utils/register_parsers/`**: Parsing logic for `nextreg.txt`, including mode/bitfield handling and any register-specific parsing extensions.
@@ -91,23 +104,34 @@ Comment what the code does, not what the agent has done. The documentation's pur
 
 - **Server Components**:
   - `src/app/registers/page.tsx` and `src/app/registers/[hex]/page.tsx` are Server Components.
-  - They call `getRegisters()` on the server and pass the resulting data down to client components as props.
+  - ZXDB pages under `/zxdb` server‑render initial content for fast first paint, with ISR (`export const revalidate = 3600`) on non‑search pages.
+  - Server components call repository functions directly on the server and pass data to client components for presentation.
 
 - **Client Components**:
   - `RegisterBrowser.tsx`:
     - Marked with `'use client'`.
     - Uses React state to manage search input and filtered results.
-    - Renders a list or grid of registers.
   - `RegisterDetail.tsx`:
     - Marked with `'use client'`.
     - Renders a single register with tabs for different access modes.
-    - Uses a modal to show the original source lines for the register.
+  - ZXDB client components (e.g., `ZxdbExplorer.tsx`, `EntryDetail.tsx`, `labels/*`) receive initial data from the server and keep interactions on the client without blocking the first paint.
 
 - **Dynamic Routing**:
-  - `src/app/registers/[hex]/page.tsx`:
-    - Resolves the `[hex]` URL segment.
-    - Looks up the corresponding register by `hex_address`.
-    - Calls `notFound()` when no matching register exists.
+  - Pages and API routes must await dynamic params in Next.js 15:
+    - Pages: `export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; }`
+    - API: `export async function GET(req, ctx: { params: Promise<{ id: string }> }) { const raw = await ctx.params; /* validate with Zod */ }`
+  - `src/app/registers/[hex]/page.tsx` resolves the `[hex]` segment and calls `notFound()` if absent.
+
+### ZXDB Integration
+
+- 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.
+- 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`).
+- API routes under `/api/zxdb/*` validate inputs with Zod and run on Node runtime.
+- UI under `/zxdb` is deeply cross‑linked and server‑renders initial data for performance. Links use Next `Link` to enable prefetching.
+  - Helper SQL `ZXDB/scripts/ZXDB_help_search.sql` must be run to create `search_by_*` tables for efficient searches.
+  - Lookup tables use column `text` for display names; the Drizzle schema maps it as `name`.
 
 ### Working Patterns***
 
@@ -120,4 +144,8 @@ Comment what the code does, not what the agent has done. The documentation's pur
 - git commit messages:
   - Use imperative mood (e.g., "Add feature X", "Fix bug Y").
   - Include relevant issue numbers if applicable.
-  - Sign-off commit message as Junie@<hostname>
+  - Sign-off commit message as Junie@<hostname>
+
+### References
+
+- ZXDB setup and API usage: `docs/ZXDB.md`