Update setup docs and scripts

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

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

AGENTS.md

@@ -158,6 +158,11 @@ Comment what the code does, not what the agent has done. The documentation's pur
   - Call out what to inspect visually (e.g., section names, table columns, empty states).
   - Use the local `.env` for any environment-dependent behavior.
   - Provide fully clickable links when sharing validation URLs.
+- submodule hygiene:
+  - The `ZXDB` submodule is read-only in this repo; do not commit SQL dumps from it.
+  - 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.
 
 ### References
 

README.md

@@ -22,6 +22,9 @@ Project scripts (package.json)
 - `dev`: `PORT=4000 next dev --turbopack`
 - `build`: `next build --turbopack`
 - `start`: `next start`
+- `deploy`: merge current branch into `deploy` and push to `explorer.specnext.dev`
+- `deploy:branch`: same as `deploy`, but accepts a deploy branch argument
+- `setup:zxdb-local`: configure local submodule excludes for ZXDB SQL files
 - `deploy-test`: push to `test.explorer.specnext.dev`
 - `deploy-prod`: push to `explorer.specnext.dev`
 
@@ -59,6 +62,10 @@ The Registers section works without any database. The ZXDB Explorer requires a M
 3) Run the app
 - `pnpm dev` → open http://localhost:4000 and navigate to `/zxdb`.
 
+4) Keep the ZXDB submodule clean (recommended)
+- Run `pnpm setup:zxdb-local` once after cloning.
+- This keeps `ZXDB/ZXDB_mysql.sql` and `ZXDB/ZXDB_mysql_STRUCTURE_ONLY.sql` available locally without appearing as untracked changes.
+
 API (selected endpoints)
 - `GET /api/zxdb/search?q=...&page=1&pageSize=20&genreId=...&languageId=...&machinetypeId=...&sort=title&facets=1`
 - `GET /api/zxdb/entries/[id]`

bin/deploy.sh

@@ -8,6 +8,10 @@ if ! git diff --quiet || ! git diff --cached --quiet; then
   echo "Working tree is not clean. Commit or stash changes before deploy."
   exit 1
 fi
+if git ls-files --others --exclude-standard | grep -q .; then
+  echo "Untracked files present. Commit or remove them before deploy."
+  exit 1
+fi
 
 cleanup() {
   git checkout "${current_branch}" >/dev/null 2>&1 || true

bin/setup-zxdb-local.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+git_dir="$(git -C ZXDB rev-parse --git-dir)"
+exclude_file="${git_dir}/info/exclude"
+
+mkdir -p "$(dirname "${exclude_file}")"
+touch "${exclude_file}"
+
+add_exclude() {
+  local pattern="$1"
+  if ! grep -Fxq "${pattern}" "${exclude_file}"; then
+    printf "%s\n" "${pattern}" >> "${exclude_file}"
+  fi
+}
+
+add_exclude "ZXDB_mysql.sql"
+add_exclude "ZXDB_mysql_STRUCTURE_ONLY.sql"

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/entries` — Entries search with scope toggles (titles/aliases/origins) and facets.
-- `/zxdb/labels` and `/zxdb/labels/[id]` — Browse/search labels (people/companies) and view authored/published entries.
+- `/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.
+- Issue-centric media grouping and richer magazine metadata.
-- Breadcrumbs and additional a11y polish.
+- Additional cross-links for tags, relations, and permissions as UI expands.
-- Media assets and download links per release (future).
+- 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.

package.json

@@ -9,6 +9,7 @@
     "lint": "eslint",
     "deploy": "bin/deploy.sh",
     "deploy:branch": "bin/deploy.sh",
+    "setup:zxdb-local": "bin/setup-zxdb-local.sh",
     "deploy-prod": "git push --set-upstream explorer.specnext.dev deploy",
     "deploy-test": "git push --set-upstream test.explorer.specnext.dev test"
   },