From dd12ec5591e631bf557f5a656733e73f694fa746 Mon Sep 17 00:00:00 2001
From: Chris <26607885+chrisglein@users.noreply.github.com>
Date: Wed, 1 Jul 2026 10:11:48 -0700
Subject: [PATCH 5/5] Agent written instructions and documentation
---
.github/copilot-instructions.md | 8 ++++++
AGENTS.md | 44 +++++++++++++++++++++++++++++++++
2 files changed, 52 insertions(+)
create mode 100644 .github/copilot-instructions.md
create mode 100644 AGENTS.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..edc784f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,8 @@
+# Copilot instructions — shanties
+
+**The primary artifact is the website** (`src/`): an interactive ABC-notation songbook — pick or type a song and abcjs live-renders staff notation, with transpose and lyrics / verses / guitar-tab / trumpet-fingering toggles. It deploys to https://brewingcode.github.io/shanties. The two printable **booklets** (`booklet/` = lyrics, `musicbook/` = staff) are secondary artifacts derived from the same `songs/`. **Read `AGENTS.md` for site architecture, URL params/filters, and the booklet/music-capture pipelines before any non-trivial change.**
+
+- Build the site: `npm run build` (Node-only, cross-platform → `dist/`). Serve with live reload: `npx pug-pack src -w` (http://localhost:3000); `npm run dev` rebuilds but does **not** serve.
+- `src/songs.json` + `src/by-title.json` are generated & gitignored — run a build if they're missing.
+- The Windows build is already fixed via `patches/pug-pack+1.11.0.patch` (applied by `postinstall`/patch-package). Don't re-diagnose or revert it.
+- Prefer Node built-ins over new deps; don't leave throwaway scripts; this is a PowerShell box — use single-line commands.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1a1c5db
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# AGENTS.md — shanties
+
+Fuller agent guide for the sea-shanties project. The always-loaded essentials live in `.github/copilot-instructions.md`; read this file for anything beyond a trivial change.
+
+The repo's **primary purpose is the website** (`src/`) — an interactive ABC-notation songbook. The two printable saddle-stitch booklets are secondary artifacts derived from the same `songs/`. The site deploys to https://brewingcode.github.io/shanties by `.github/workflows/gh-pages.yml` (Ubuntu, Node 20, `npm install` + `npm run build`).
+
+## Build & run
+- `npm run build` — site → `dist/`: runs `songs-to-json.js`, then `pug-pack src`, then copies `Songbook.pdf` + `qr-code.svg`. Cross-platform (Node only — no python/`cp`).
+- Serve locally with live reload: `npx pug-pack src -w` → http://localhost:3000 (browserSync). `npm run dev` watches + rebuilds but does not serve.
+- `npm run booklet` / `booklet:proof` / `booklet:single` — lyrics booklet (`booklet/`).
+- `npm run musicbook` / `musicbook:proof` — staff-notation booklet (`musicbook/`).
+- Syntax-check CoffeeScript snippets by piping (dedented) to `npx coffee -s -c -p`.
+
+## The website (`src/`) — the primary artifact
+Interactive ABC songbook: type ABC into `#abc` (or pick a song from the dropdown, or click "add a song" → GitHub `songs/`), and abcjs live-renders staff notation into `#paper`. Settings toggle inline lyrics (`#show-lyrics`), extended verses (`#show-verses`), trumpet fingering (`#show-trumpet`), and guitar tab (`#show-gtab`); `#transpose` shifts the key and shows from/to in `#fromKey`/`#toKey`. Parse warnings render to `#warnings`; on iPad the textarea sits behind an Edit button.
+- `src/index.pug` is the whole page (extends pug-pack `_base`). All logic is CoffeeScript in a `:coffeescript` filter; abcjs/jquery/bootstrap are `include`d and inlined into one big `dist/index.html`.
+- `songs/*.txt` are ABC songs. `songs-to-json.js` generates `src/songs.json` (keyed by filename) + `src/by-title.json` (keyed by `T:` title) — both are **generated and gitignored**; run a build if they're missing.
+- abcjs renders into `#paper`. UI chrome is tagged `.noprint` (hidden in print and when `body.fullscreen`).
+- URL params: `title=` / `file=` pick a song; `fullscreen=true` hides chrome; `lyrics=false`, `verses=false` hide inline / extended lyrics (read before first render).
+- `setSong` filters ABC lines pre-render: lowercase `w:` = inline lyrics (or trumpet fingering if all digits), uppercase `W:` = extended verses.
+- ABC songs use `%%` directives (e.g. `%%notelabels`, `%%notecolors`, `%%vocalfont`) alongside standard fields (`T:`, `M:`, `K:`, `w:`/`W:`).
+
+## Booklets (markdown-booklet)
+- Engine: `node node_modules/markdown-booklet/src/cli.js build /book.yaml [--out … | --reading | --single]`.
+- `booklet/` = lyrics (Markdown, two-page spreads). `musicbook/` = staff notation (single `type: html` pages, no spreads), parallel to the lyrics book.
+- Song list source of truth is `booklet/book.yaml`. Before assuming a song has staff notation, confirm its `songs/.txt` exists (e.g. `skipper-jan-rebec` was booklet-only for a while).
+
+## Music-book staff capture (`musicbook/pages/*.svg`)
+Each staff SVG is captured from the running site. To (re)generate one:
+1. Serve the site (`npx pug-pack src -w`).
+2. Headlessly load `?file=.txt&fullscreen=true&verses=false`, grab `#paper svg` outerHTML (strip its inline `style`, set `width=100%`, remove `height`).
+3. **Post-process — required, or `` renders broken:** add `xmlns="http://www.w3.org/2000/svg"` to the root `
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+