Update setup docs and scripts

Refresh setup docs, add ZXDB local setup script, and note deploy rules.

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

docs/ZXDB.md

@@ -4,13 +4,14 @@ This document explains how the ZXDB Explorer works in this project, how to set u
 
 ## What is ZXDB?
 
-ZXDB ( https://github.com/zxdb/ZXDB )is a community‑maintained database of ZX Spectrum software, publications, and related entities. In this project, we connect to a MySQL ZXDB instance in read‑only mode and expose a fast, cross‑linked explorer UI under `/zxdb`.
+ZXDB (https://github.com/zxdb/ZXDB) is a community‑maintained database of ZX Spectrum software, publications, and related entities. In this project, we connect to a MySQL ZXDB instance in read‑only mode and expose a fast, cross‑linked explorer UI under `/zxdb`.
 
 ## Prerequisites
 
 - MySQL server with ZXDB data (or at minimum the tables; data is needed to browse).
 - Ability to run the helper SQL that builds search tables (required for efficient LIKE searches).
 - A read‑only MySQL user for the app (recommended).
+- The `ZXDB` submodule is checked in for schemas/scripts; use `pnpm setup:zxdb-local` after cloning to keep local SQL dumps untracked.
 
 ## Database setup
 
@@ -19,7 +20,8 @@ ZXDB ( https://github.com/zxdb/ZXDB )is a community‑maintained database of ZX
 
 2. Create helper search tables (required).
    - Run `https://github.com/zxdb/ZXDB/blob/master/scripts/ZXDB_help_search.sql` on your ZXDB database.
-   - This creates `search_by_titles`, `search_by_names`, `search_by_authors`, and `search_by_publishers` tables.
+   - This creates `search_by_titles`, `search_by_names`, `search_by_authors`, `search_by_publishers`, `search_by_aliases`, `search_by_origins`,
+     `search_by_magrefs`, `search_by_magazines`, and `search_by_issues` tables used for search scopes and magazine references.
 
 3. Create a read‑only role/user (recommended).
    - Create user `zxdb_readonly`.
@@ -48,9 +50,14 @@ pnpm dev
 ## Explorer UI overview
 
 - `/zxdb` — Search entries by title and filter by genre, language, and machine type; sort and paginate results.
-- `/zxdb/entries/[id]` — Entry details with badges for genre/language/machine, and linked authors/publishers.
-- `/zxdb/labels` and `/zxdb/labels/[id]` — Browse/search labels (people/companies) and view authored/published entries.
+- `/zxdb/entries` — Entries search with scope toggles (titles/aliases/origins) and facets.
+- `/zxdb/entries/[id]` — Entry details with related releases, downloads, origins, relations, and media.
+- `/zxdb/releases` — Releases search + filters.
+- `/zxdb/releases/[entryId]/[releaseSeq]` — Release detail: magazine references, downloads, scraps, and issue files.
+- `/zxdb/labels` and `/zxdb/labels/[id]` — Browse/search labels (people/companies), permissions, licenses, and authored/published entries.
 - `/zxdb/genres`, `/zxdb/languages`, `/zxdb/machinetypes` — Category hubs with linked detail pages listing entries.
+- `/zxdb/magazines` and `/zxdb/magazines/[id]` — Magazine list and issue navigation.
+- `/zxdb/issues/[id]` — Issue detail with contents and references.
 
 Cross‑linking: All entities are permalinks using stable IDs. Navigation uses Next `Link` so pages are prefetched.
 
@@ -67,6 +74,7 @@ All endpoints are under `/api/zxdb` and validate inputs with Zod. Responses are
     - `page`, `pageSize` — pagination (default pageSize=20, max=100)
     - `genreId`, `languageId`, `machinetypeId` — optional filters
     - `sort` — `title` or `id_desc`
+    - `scope` — `title`, `title_aliases`, or `title_aliases_origins`
     - `facets` — boolean; if truthy, includes facet counts for genres/languages/machines
 
 - Entry detail
@@ -99,12 +107,13 @@ Runtime: API routes declare `export const runtime = "nodejs"` to support `mysql2
 ## Troubleshooting
 
 - 400 from dynamic API routes: ensure you await `ctx.params` before Zod validation.
+- Missing facets or scope toggles: ensure helper tables from `ZXDB_help_search.sql` exist.
 - Unknown column errors for lookup names: ZXDB tables use column `text` for names; Drizzle schema must select `text` as `name`.
 - Slow entry page: confirm server‑rendering is active and ISR is set; client components should not fetch on the first paint when initial props are provided.
 - MySQL auth or network errors: verify `ZXDB_URL` and that your user has read permissions.
 
 ## Roadmap
 
-- Facet counts displayed in the `/zxdb` filter UI.
-- Breadcrumbs and additional a11y polish.
-- Media assets and download links per release (future).
+- Issue-centric media grouping and richer magazine metadata.
+- Additional cross-links for tags, relations, and permissions as UI expands.
+- A11y polish and higher-level navigation enhancements.

docs/getting-started.md

@@ -15,6 +15,12 @@ Run in development
 - Command: pnpm dev
 - Then open: http://localhost:4000
 
+ZXDB submodule local setup
+- The ZXDB repo is a submodule used as a read-only reference for schemas/scripts.
+- Some local SQL files are expected to exist but should stay untracked.
+- Run: pnpm setup:zxdb-local
+  - This adds local excludes inside the submodule so `git status` stays clean.
+
 Build and start (production)
 - Build: pnpm build
 - Start: pnpm start
@@ -24,7 +30,9 @@ Lint
 - pnpm lint
 
 Deployment shortcuts
-- Two scripts are available in package.json:
+- Use pnpm deploy (or pnpm deploy:branch) to merge the current branch into `deploy` and push to explorer.specnext.dev.
+  - The deploy script refuses to run if there are uncommitted or untracked files.
+- One-step push helpers (if you prefer manual branch selection):
   - pnpm deploy-test: push the current branch to test.explorer.specnext.dev
   - pnpm deploy-prod: push the current branch to explorer.specnext.dev
-Ensure the corresponding Git remotes are configured locally before using these.
+  - Ensure the corresponding Git remotes are configured locally before using these.

docs/index.md

@@ -5,5 +5,6 @@ Welcome to the Spectrum Next Explorer docs. This site provides an overview of th
 - Getting Started: ./getting-started.md
 - Architecture: ./architecture.md
 - Register Explorer: ./registers.md
+- ZXDB Explorer: ./ZXDB.md
 
 If you’re browsing on GitHub, the main README also links to these documents.